> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avidoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Complete reference for the Avido Node.js and Python SDKs.

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

## Installation

<CodeGroup>
  ```bash Node theme={null}
  npm install @avidoai/sdk-node
  ```

  ```bash Python theme={null}
  pip install avido
  ```
</CodeGroup>

***

## 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**.

<CodeGroup>
  ```ts Node theme={null}
  import Avido from '@avidoai/sdk-node';

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

  ```python Python theme={null}
  import os
  from avido import Avido

  client = Avido(
      application_id=os.environ.get("AVIDO_APPLICATION_ID"),
      api_key=os.environ.get("AVIDO_API_KEY"),
  )
  ```
</CodeGroup>

<Callout type="info">
  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.
</Callout>

***

## Resources

### Ingest

Send trace events to Avido. See the [Tracing guide](/traces) for detailed event type documentation.

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

  ```python Python theme={null}
  response = client.ingest.create(
      events=[
          {"type": "trace", "timestamp": "...", "testId": "..."},
          {"type": "llm", "event": "start", "timestamp": "...", "modelId": "gpt-4o", "input": [...]},
      ],
  )
  ```
</CodeGroup>

| 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](/webhooks) for a full integration example.

<CodeGroup>
  ```ts Node theme={null}
  const { valid } = await client.validateWebhook.validate({
    signature: req.get('x-avido-signature'),
    timestamp: req.get('x-avido-timestamp'),
    body: req.body,
  });
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

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

***

### Traces

Retrieve and list traces that have been ingested.

<CodeGroup>
  ```ts Node theme={null}
  // 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');
  ```

  ```python Python theme={null}
  # List traces with pagination
  traces = client.traces.list(limit=20, offset=0)

  # Get a specific trace
  trace = client.traces.retrieve("trace-uuid")
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  // 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');
  ```

  ```python Python theme={null}
  # 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")
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  // 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' });
  ```

  ```python Python theme={null}
  # 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")
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  const tests = await client.tests.list({ limit: 10 });
  const test = await client.tests.retrieve('test-uuid');
  ```

  ```python Python theme={null}
  tests = client.tests.list(limit=10)
  test = client.tests.retrieve("test-uuid")
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  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 });
  ```

  ```python Python theme={null}
  annotation = client.annotations.create(
      trace_id="trace-uuid",
      label="incorrect",
      comment="The response contained outdated pricing.",
  )

  annotations = client.annotations.list(limit=10)
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  const runs = await client.runs.list({ limit: 10 });
  const run = await client.runs.retrieve('run-uuid');
  ```

  ```python Python theme={null}
  runs = client.runs.list(limit=10)
  run = client.runs.retrieve("run-uuid")
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  const topic = await client.topics.create({ name: 'Pricing questions' });
  const topics = await client.topics.list({ limit: 10 });
  ```

  ```python Python theme={null}
  topic = client.topics.create(name="Pricing questions")
  topics = client.topics.list(limit=10)
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  const guide = await client.styleGuides.create({
    name: 'Formal tone',
    content: 'Responses should use professional language...',
  });
  const guides = await client.styleGuides.list({ limit: 10 });
  ```

  ```python Python theme={null}
  guide = client.style_guides.create(
      name="Formal tone",
      content="Responses should use professional language...",
  )
  guides = client.style_guides.list(limit=10)
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  // 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 });
  ```

  ```python Python theme={null}
  # 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)
  ```
</CodeGroup>

| 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.

<CodeGroup>
  ```ts Node theme={null}
  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;
    }
  }
  ```

  ```python Python theme={null}
  from avido import Avido, NotFoundError, AuthenticationError

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

***

## Pagination

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

<CodeGroup>
  ```ts Node theme={null}
  // 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;
  }
  ```

  ```python Python theme={null}
  # 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
  ```
</CodeGroup>

***

## TypeScript types

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

```ts theme={null}
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.

```python theme={null}
from avido.types import (
    IngestCreateResponse,
    ValidateWebhookValidateResponse,
    TraceRetrieveResponse,
    TraceListResponse,
    Task,
    TaskResponse,
    Annotation,
    AnnotationResponse,
)
```

***

## Next steps

* Follow the [Tracing guide](/traces) to instrument your LLM pipeline.
* Set up [Webhooks](/webhooks) for automated test triggering.
* Explore the full HTTP API in the <a href="/api-reference" target="_blank">API Reference</a>.