Avido provides official SDKs for Node.js / TypeScript and Python.
Installation
npm install @avidoai/sdk-node
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'],
});
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: [...] },
],
});
| 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,
});
| 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');
| 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');
| 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' });
| 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');
| 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 });
| 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');
| 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 });
| 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 });
| 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 });
| 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;
}
}
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;
}
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
