# Create a new application
Source: https://docs.avidoai.com/api-reference/applications/create-a-new-application
openapi.json post /v0/applications
Creates a new application configuration.
# Get a single application by ID
Source: https://docs.avidoai.com/api-reference/applications/get-a-single-application-by-id
openapi.json get /v0/applications/{id}
Retrieves detailed information about a specific application.
# List applications
Source: https://docs.avidoai.com/api-reference/applications/list-applications
openapi.json get /v0/applications
Retrieves a paginated list of applications with optional filtering.
# Get a single evaluation by ID
Source: https://docs.avidoai.com/api-reference/evals/get-a-single-evaluation-by-id
openapi.json get /v0/evals/{id}
Retrieves detailed information about a specific evaluation.
# List evaluations
Source: https://docs.avidoai.com/api-reference/evals/list-evaluations
openapi.json get /v0/evals
Retrieves a paginated list of evaluations with optional filtering.
# List tests
Source: https://docs.avidoai.com/api-reference/evals/list-tests
openapi.json get /v0/tests
Retrieves a paginated list of tests with optional filtering.
# Ingest events
Source: https://docs.avidoai.com/api-reference/ingestion/ingest-events
openapi.json post /v0/ingest
Ingest an array of events (threads or traces) to store and process.
# Get a single run by ID
Source: https://docs.avidoai.com/api-reference/runs/get-a-single-run-by-id
openapi.json get /v0/runs/{id}
Retrieves detailed information about a specific run.
# List runs
Source: https://docs.avidoai.com/api-reference/runs/list-runs
openapi.json get /v0/runs
Retrieves a paginated list of runs with optional filtering.
# Create a new style guide
Source: https://docs.avidoai.com/api-reference/style-guides/create-a-new-style-guide
openapi.json post /v0/style-guides
Creates a new style guide.
# Get a single style guide by ID
Source: https://docs.avidoai.com/api-reference/style-guides/get-a-single-style-guide-by-id
openapi.json get /v0/style-guides/{id}
Retrieves detailed information about a specific style guide.
# List style guides
Source: https://docs.avidoai.com/api-reference/style-guides/list-style-guides
openapi.json get /v0/style-guides
Retrieves a paginated list of style guides with optional filtering.
# Create a new task
Source: https://docs.avidoai.com/api-reference/tasks/create-a-new-task
openapi.json post /v0/tasks
Creates a new task.
# Get a single task by ID
Source: https://docs.avidoai.com/api-reference/tasks/get-a-single-task-by-id
openapi.json get /v0/tasks/{id}
Retrieves detailed information about a specific task.
# List tasks
Source: https://docs.avidoai.com/api-reference/tasks/list-tasks
openapi.json get /v0/tasks
Retrieves a paginated list of tasks with optional filtering.
# Run a task
Source: https://docs.avidoai.com/api-reference/tasks/run-a-task
openapi.json post /v0/tasks/trigger
Triggers the execution of a task.
# Get a single test by ID
Source: https://docs.avidoai.com/api-reference/tests/get-a-single-test-by-id
openapi.json get /v0/tests/{id}
Retrieves detailed information about a specific test.
# Get a single trace by ID
Source: https://docs.avidoai.com/api-reference/threads/get-a-single-trace-by-id
openapi.json get /v0/traces/{id}
Retrieves detailed information about a specific trace.
# List Traces
Source: https://docs.avidoai.com/api-reference/threads/list-traces
openapi.json get /v0/traces
Retrieve threads with associated traces, filtered by application ID and optional date parameters.
# Create a new topic
Source: https://docs.avidoai.com/api-reference/topics/create-a-new-topic
openapi.json post /v0/topics
Creates a new topic.
# Get a single topic by ID
Source: https://docs.avidoai.com/api-reference/topics/get-a-single-topic-by-id
openapi.json get /v0/topics/{id}
Retrieves detailed information about a specific topic.
# List topics
Source: https://docs.avidoai.com/api-reference/topics/list-topics
openapi.json get /v0/topics
Retrieves a paginated list of topics with optional filtering.
# Validate an incoming webhook request
Source: https://docs.avidoai.com/api-reference/webhook/validate-an-incoming-webhook-request
openapi.json post /v0/validate-webhook
Checks the body (including timestamp and signature) against the configured webhook secret. Returns `{ valid: true }` if the signature is valid.
# Authentication
Source: https://docs.avidoai.com/authentication
How to authenticate with Avido's API endpoints.
1. **`Authorization: Bearer YOUR_API_KEY`**
2. **`x-avido-app-id: UUID_OF_YOUR_APPLICATION`**
## Retrieving Your API Key
1. Log in to the Avido dashboard.
2. Navigate to **API Keys** in your account settings.
3. Copy the generated Bearer token.
4. Always store this securely.
## Retrieving Your Application ID
Every application within Avido has a unique **UUID**. In your **Avido dashboard**:
1. Go to **Applications**.
2. Select an application to see its details.
3. Note the **App ID (UUID)**.
## Example Request
```bash
curl -X POST "https://api.avidoai.com/v0/ingest" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-avido-app-id: 310adba1-7cc0-4fa7-9e2b-8bd2fdf281b2" \
-d '{"events": [...]}'
```
If either header is missing or invalid, you’ll receive a 401 or 403 error.
# Introduction
Source: https://docs.avidoai.com/introduction
Welcome to the Avido API docs! Learn how to integrate Avido's LLM usage events, create threads, handle webhooks, and more.
* Track events from your LLM usage (e.g., calls, tool interactions, chat messages).
* Create threads for conversation-based flows.
* Validate external webhooks for secure data handoffs.
## Quick Overview
1. **Authentication**: You'll need a valid `x-avido-app-id` (Application ID) and a Bearer token (`Authorization` header).
2. **Ingestion**: Send an array of typed events to our `/v0/ingest` endpoint to store and analyze them.
3. **Threads**: If you need to create a new conversation (thread), you can do so via `/v0/threads`.
4. **Webhooks**: Validate incoming requests from external sources with our signature-based webhook system.
In the following pages, you'll learn everything you need to effectively use the Avido API.
# Quickstart
Source: https://docs.avidoai.com/quickstart
Get started with Avido quickly—create an account, obtain credentials, send your first events, and set up a webhook.
1. Create (or configure) an **Avido account**.
2. Obtain your **API Key** and **App ID**.
3. Send your **first event** using the Ingestion endpoint.
4. Optionally, **create a new thread** for conversation-based tracking.
5. Set up a **webhook** for signature-based validation.
## Step 1: Create or Access Your Avido Account
If you're new to Avido, start by creating an account in our dashboard. Once
you log in, head to the **Applications** section to manage your app IDs.
Each application has a unique UUID. From the **Applications** page, select
or create a new application. Note its **App ID (UUID)**—we'll need this
shortly.
## Step 2: Obtain Your Bearer API Key
Head to **API Keys** in the Avido dashboard. Generate a new key if you don't
have one already. Keep it secure—this key grants access to your data via the
Avido API.
For every API request, you'll need two headers: `Authorization: Bearer
YOUR_API_KEY x-avido-app-id: YOUR_APP_UUID` If either is missing or
invalid, you'll encounter a 401/403 error.
## Step 3: Send Your First Ingestion Event
To log your first LLM event:
```bash
curl -X POST "https://api.avidoai.com/v0/ingest" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-avido-app-id: YOUR_APP_UUID" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "llm",
"event": "start",
"runId": "run_123",
"timestamp": "2025-01-05T12:34:56.789Z",
"input": "Hello from the quickstart!"
}
]
}'
```
If everything is correct, you'll get a 200 response with a JSON body like:
```json
{
"results": [
{
"id": "run_123",
"success": true
}
]
}
```
You've officially recorded your first event in Avido!
Avido stores this data internally. You can view it in your dashboard to track
LLM usage, measure cost, or debug calls. If monitoring is disabled for your
app, make sure `evaluationId` is present on your events to avoid filtering.
## Step 4: Create a Thread
Threads let you model **conversations** or **sessions** in your app. They're
handy for chat-based flows where you want to group messages and responses
under a single parent.
```bash
curl -X POST "https://api.avidoai.com/v0/threads" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "x-avido-app-id: YOUR_APP_UUID" \
-H "Content-Type: application/json" \
-d '{
"threadId": "thread_custom_0001",
"metadata": { "topic": "Support session" },
"message": {
"role": "user",
"content": "Hello, I'd like some help with your API."
}
}'
```
On success, you'll see a response like:
```json
{
"threadId": "thread_custom_0001",
"success": true
}
```
Use that `threadId` as `parentRunId` for subsequent events in this
conversation.
## Step 5: Validate a Webhook
If your use case involves receiving or validating external requests, head to
your **Application** settings. Enable **webhooks** and note your
`webhookSecret`.
Every incoming request to
```
POST /v0/webhook
```
will include a signature header. Our server will compare that header with an
HMAC generated using your `webhookSecret`. If valid, you'll see:
```json
{
"valid": true
}
```
Otherwise, you'll receive a 401 error and a short message (e.g.
`"Invalid webhook signature"`).
## Next Steps
Read the full guide on API key usage and app IDs.
See how to batch events, store LLM usage, and integrate with Avido's
analytics.
Securely verify incoming requests from external sources.
Explore a complete, auto-generated reference of Avido's endpoints.
## That's it!
You’ve successfully:
1. **Set up your account** and **keys**,
2. Sent your **first event**,
3. Created a **thread** for conversational flows,
4. (Optionally) validated a **webhook** signature.
Now, check out our [full reference](/reference) or continue exploring the docs for more advanced scenarios.
# SDKs
Source: https://docs.avidoai.com/sdks
Official client libraries for the Avido API
## Node.js
Our Node.js SDK provides a type-safe way to interact with the Avido API. You can install it using npm:
```bash
npm install avido
```
### Basic Usage
```typescript
import Avido from "avido";
const client = new Avido({
bearerToken: process.env["BEARER_TOKEN"],
environment: "production", // or 'environment_1'
});
async function main() {
const evaluationCase = await client.evaluations.create({
applicationId: "456e4567-e89b-12d3-a456-426614174000",
evaluationCriteria:
"The function should handle empty arrays, null values, and correctly sum all prices",
factualCorrectness: true,
styleRequirements: true,
task: "Implement a function to calculate the total price of items in a shopping cart",
topicId: "789e4567-e89b-12d3-a456-426614174000",
});
console.log(evaluationCase.data);
}
```
## Python
Our Python SDK provides both synchronous and asynchronous clients for the Avido API. Install it using pip:
```bash
pip install avido
```
### Basic Usage
```python
import os
from avido import Avido
client = Avido(
bearer_token=os.environ.get("BEARER_TOKEN"),
environment="production" # defaults to "production"
)
webhook_validation_response = client.webhook.validate(
body={},
)
print(webhook_validation_response.valid)
```
### Async Usage
```python
python
import os
import asyncio
from avido import AsyncAvido
client = AsyncAvido(
bearer_token=os.environ.get("BEARER_TOKEN"),
environment="production"
)
async def main():
webhook_validation_response = await client.webhook.validate(
body={},
)
print(webhook_validation_response.valid)
asyncio.run(main())
```
## Error Handling
Both SDKs provide consistent error handling with specific error types for different scenarios:
| Status Code | Error Type |
| ----------- | ------------------------ |
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| ≥500 | InternalServerError |
| N/A | APIConnectionError |
## Additional Features
Both SDKs include:
* Full TypeScript/Python type definitions
* Automatic retries with exponential backoff
* Pagination helpers
* Configurable timeouts
* Detailed logging options
* Customizable HTTP clients
For more detailed documentation, visit:
* Node.js SDK: [NPM](https://www.npmjs.com/package/avido)
* Python SDK: [PyPI](https://pypi.org/project/avido/)
# Webhooks
Source: https://docs.avidoai.com/webhooks
Avido’s **Webhooks** enable you to programmatically trigger evaluations in your AI application. By setting up an endpoint to receive the webhook, you can initiate chats or other processes whenever Avido wants to run an evaluation. This guide walks you through how to receive and validate a webhook from Avido and then leverage the webhook payload to start a new chat.
## Table of Contents
1. [Expose a Public Endpoint for Webhooks](#1-expose-a-public-endpoint-for-webhooks)
2. [Receive the Webhook and Validate It](#2-receive-the-webhook-and-validate-it)
3. [Start a Chat in Your Application](#3-start-a-chat-in-your-application)
***
## 1. Expose a Public Endpoint for Webhooks
Your application must have a publicly accessible endpoint that can accept incoming **POST** requests from Avido.
1. **Create an HTTPS Endpoint**\
Ensure the endpoint is secured with TLS (HTTPS).
2. **Accept JSON Payloads**\
Avido sends webhook data in JSON format. Your endpoint should parse the JSON from the request body.
3. **Respond Quickly**\
Return a successful status code (e.g., `200 OK`) if the request was received successfully.
## 2. Receive the Webhook and Validate It
Before trusting the data in the webhook, you must validate its authenticity. This ensures the request truly originated from Avido and has not been tampered with.
**Example Validation Flow (Typescript)**
```ts
// 1) Parse the JSON body
const body = await request.json();
// 2) Extract signature & timestamp from headers
const signature = request.headers.get("x-avido-signature");
const timestamp = request.headers.get("x-avido-timestamp");
if (!signature || !timestamp) {
return NextResponse.json({ error: "Missing headers" }, { status: 400 });
}
// 3) Validate the webhook
const { valid } = await client.webhook.validate({
signature,
timestamp: Number(timestamp), // Important! Must be sent as Number
body,
});
if (!valid) {
return new Response(JSON.stringify({ error: "Invalid webhook" }), {
status: 400,
});
}
// If valid, do something with the body
// ...
return new Response(JSON.stringify({ received: true }), { status: 200 });
}
```
## 3. Start a Chat in Your Application
Once you have verified the webhook, you can initiate a chat or handle the prompt in your system. If the conversation is triggered by Avido, the evaluationId should match the one provided in the webhook, allowing you to track which test triggered the conversation.
Learn more about webhook validation in the [API Reference](https://docs.avidoai.com/api-reference).