SDK Reference

Avido provides official SDKs for Node.js / TypeScript and Python.

Installation

npm install @avidoai/sdk-node

pip install avido

Client initialization

Create a client instance with your Application ID and API key. You can find these in the Avido dashboard under Settings > API Keys.

import Avido from '@avidoai/sdk-node';

const client = new Avido({
  applicationId: process.env['AVIDO_APPLICATION_ID'],
  apiKey: process.env['AVIDO_API_KEY'],
});

import os
from avido import Avido

client = Avido(
    application_id=os.environ.get("AVIDO_APPLICATION_ID"),
    api_key=os.environ.get("AVIDO_API_KEY"),
)

Both SDKs read AVIDO_API_KEY and AVIDO_APPLICATION_ID from environment variables by default. You only need to pass them explicitly if you want to override the defaults.

Resources

Ingest

Send trace events to Avido. See the Tracing guide for detailed event type documentation.

const response = await client.ingest.create({
  events: [
    { type: 'trace', timestamp: new Date().toISOString(), testId: '...' },
    { type: 'llm', event: 'start', timestamp: '...', modelId: 'gpt-4o', input: [...] },
  ],
});

response = client.ingest.create(
    events=[
        {"type": "trace", "timestamp": "...", "testId": "..."},
        {"type": "llm", "event": "start", "timestamp": "...", "modelId": "gpt-4o", "input": [...]},
    ],
)

Method	Endpoint	Description
`ingest.create()`	`POST /v0/ingest`	Ingest an array of trace events

Validate Webhook

Verify that an incoming webhook request was signed by Avido. See the Webhooks guide for a full integration example.

const { valid } = await client.validateWebhook.validate({
  signature: req.get('x-avido-signature'),
  timestamp: req.get('x-avido-timestamp'),
  body: req.body,
});

resp = client.validate_webhook.validate(
    signature=request.headers.get("x-avido-signature"),
    timestamp=request.headers.get("x-avido-timestamp"),
    body=request.get_json(),
)
# resp.valid -> bool

Method	Endpoint	Description
`validateWebhook.validate()`	`POST /v0/validate-webhook`	Validate a webhook signature

Traces

Retrieve and list traces that have been ingested.

// List traces with pagination
const traces = await client.traces.list({ limit: 20, offset: 0 });

// Get a specific trace
const trace = await client.traces.retrieve('trace-uuid');

# List traces with pagination
traces = client.traces.list(limit=20, offset=0)

# Get a specific trace
trace = client.traces.retrieve("trace-uuid")

Method	Endpoint	Description
`traces.list()`	`GET /v0/traces`	List traces (paginated)
`traces.retrieve(id)`	`GET /v0/traces/{id}`	Get a single trace by ID

Applications

Manage your Avido applications programmatically.

// Create a new application
const newApp = await client.applications.create({ name: 'My Chatbot' });

// List all applications
const apps = await client.applications.list({ limit: 10 });

// Get a specific application
const app = await client.applications.retrieve('app-uuid');

# Create a new application
app = client.applications.create(name="My Chatbot")

# List all applications
apps = client.applications.list(limit=10)

# Get a specific application
app = client.applications.retrieve("app-uuid")

Method	Endpoint	Description
`applications.create()`	`POST /v0/applications`	Create a new application
`applications.retrieve(id)`	`GET /v0/applications/{id}`	Get an application
`applications.list()`	`GET /v0/applications`	List applications (paginated)

Tasks

Manage test tasks and trigger them programmatically.

// Create a task
const task = await client.tasks.create({
  name: 'Onboarding email test',
  prompt: 'Write a concise onboarding email for new users.',
});

// List tasks
const tasks = await client.tasks.list({ limit: 10 });

// Trigger a task
await client.tasks.trigger({ taskId: 'task-uuid' });

# Create a task
task = client.tasks.create(
    name="Onboarding email test",
    prompt="Write a concise onboarding email for new users.",
)

# List tasks
tasks = client.tasks.list(limit=10)

# Trigger a task
client.tasks.trigger(task_id="task-uuid")

Method	Endpoint	Description
`tasks.create()`	`POST /v0/tasks`	Create a new task
`tasks.retrieve(id)`	`GET /v0/tasks/{id}`	Get a task
`tasks.list()`	`GET /v0/tasks`	List tasks (paginated)
`tasks.trigger()`	`POST /v0/tasks/trigger`	Trigger a task to run

Tests

View test definitions and results.

const tests = await client.tests.list({ limit: 10 });
const test = await client.tests.retrieve('test-uuid');

tests = client.tests.list(limit=10)
test = client.tests.retrieve("test-uuid")

Method	Endpoint	Description
`tests.retrieve(id)`	`GET /v0/tests/{id}`	Get a test
`tests.list()`	`GET /v0/tests`	List tests (paginated)

Annotations

Add annotations to traces for labeling and review.

const annotation = await client.annotations.create({
  traceId: 'trace-uuid',
  label: 'incorrect',
  comment: 'The response contained outdated pricing.',
});

const annotations = await client.annotations.list({ limit: 10 });

annotation = client.annotations.create(
    trace_id="trace-uuid",
    label="incorrect",
    comment="The response contained outdated pricing.",
)

annotations = client.annotations.list(limit=10)

Method	Endpoint	Description
`annotations.create()`	`POST /v0/annotations`	Create an annotation
`annotations.retrieve(id)`	`GET /v0/annotations/{id}`	Get an annotation
`annotations.list()`	`GET /v0/annotations`	List annotations (paginated)

Runs

View test run history and results.

const runs = await client.runs.list({ limit: 10 });
const run = await client.runs.retrieve('run-uuid');

runs = client.runs.list(limit=10)
run = client.runs.retrieve("run-uuid")

Method	Endpoint	Description
`runs.retrieve(id)`	`GET /v0/runs/{id}`	Get a run
`runs.list()`	`GET /v0/runs`	List runs (paginated)

Topics

Organize and group related content.

const topic = await client.topics.create({ name: 'Pricing questions' });
const topics = await client.topics.list({ limit: 10 });

topic = client.topics.create(name="Pricing questions")
topics = client.topics.list(limit=10)

Method	Endpoint	Description
`topics.create()`	`POST /v0/topics`	Create a topic
`topics.retrieve(id)`	`GET /v0/topics/{id}`	Get a topic
`topics.list()`	`GET /v0/topics`	List topics (paginated)

Style Guides

Manage evaluation style guides.

const guide = await client.styleGuides.create({
  name: 'Formal tone',
  content: 'Responses should use professional language...',
});
const guides = await client.styleGuides.list({ limit: 10 });

guide = client.style_guides.create(
    name="Formal tone",
    content="Responses should use professional language...",
)
guides = client.style_guides.list(limit=10)

Method	Endpoint	Description
`styleGuides.create()`	`POST /v0/style-guides`	Create a style guide
`styleGuides.retrieve(id)`	`GET /v0/style-guides/{id}`	Get a style guide
`styleGuides.list()`	`GET /v0/style-guides`	List style guides (paginated)

Documents

Manage knowledge base documents for RAG workflows.

// Upload a document
const doc = await client.documents.create({
  name: 'Product FAQ',
  content: 'Frequently asked questions about our product...',
});

// List documents
const docs = await client.documents.list({ limit: 10 });

// List chunked documents (for RAG inspection)
const chunks = await client.documents.listChunks({ limit: 10 });

# Upload a document
doc = client.documents.create(
    name="Product FAQ",
    content="Frequently asked questions about our product...",
)

# List documents
docs = client.documents.list(limit=10)

# List chunked documents (for RAG inspection)
chunks = client.documents.list_chunks(limit=10)

Method	Endpoint	Description
`documents.create()`	`POST /v0/documents`	Upload a document
`documents.retrieve(id)`	`GET /v0/documents/{id}`	Get a document
`documents.list()`	`GET /v0/documents`	List documents (paginated)
`documents.listChunks()`	`GET /v0/documents/chunked`	List document chunks (paginated)

Error handling

Both SDKs throw typed errors for API failures.

import Avido from '@avidoai/sdk-node';

try {
  await client.traces.retrieve('nonexistent-id');
} catch (err) {
  if (err instanceof Avido.NotFoundError) {
    console.log('Trace not found');
  } else if (err instanceof Avido.AuthenticationError) {
    console.log('Invalid API key');
  } else {
    throw err;
  }
}

from avido import Avido, NotFoundError, AuthenticationError

try:
    client.traces.retrieve("nonexistent-id")
except NotFoundError:
    print("Trace not found")
except AuthenticationError:
    print("Invalid API key")

Pagination

List endpoints return paginated results. Use limit and offset to page through data.

// Fetch all traces in pages of 50
let offset = 0;
const limit = 50;

while (true) {
  const page = await client.traces.list({ limit, offset });
  for (const trace of page.data) {
    console.log(trace.id);
  }
  if (page.data.length < limit) break;
  offset += limit;
}

# Fetch all traces in pages of 50
offset = 0
limit = 50

while True:
    page = client.traces.list(limit=limit, offset=offset)
    for trace in page.data:
        print(trace.id)
    if len(page.data) < limit:
        break
    offset += limit

TypeScript types

The Node SDK exports all request and response types for full type safety.

import Avido from '@avidoai/sdk-node';
import type {
  IngestCreateResponse,
  ValidateWebhookValidateResponse,
  TraceRetrieveResponse,
  TraceListResponse,
} from '@avidoai/sdk-node/resources';

Python type imports

The Python SDK exports typed response objects.

from avido.types import (
    IngestCreateResponse,
    ValidateWebhookValidateResponse,
    TraceRetrieveResponse,
    TraceListResponse,
    Task,
    TaskResponse,
    Annotation,
    AnnotationResponse,
)

Next steps

Follow the Tracing guide to instrument your LLM pipeline.
Set up Webhooks for automated test triggering.
Explore the full HTTP API in the API Reference.

What's New

Get Started

Features

SDK Reference

Installation

Client initialization

Resources

Ingest

Validate Webhook

Traces

Applications

Tasks

Tests

Annotations

Runs

Topics

Style Guides

Documents

Error handling

TypeScript types

Python type imports

Next steps

​Installation

​Client initialization

​Resources

​Ingest

​Validate Webhook

​Traces

​Applications

​Tasks

​Tests

​Annotations

​Runs

​Topics

​Style Guides

​Documents

​Error handling

​Pagination

​TypeScript types

​Python type imports

​Next steps

Installation

Client initialization

Resources

Ingest

Validate Webhook

Traces

Applications

Tasks

Tests

Annotations

Runs

Topics

Style Guides

Documents

Error handling

Pagination

TypeScript types

Python type imports

Next steps