AVCodex Builder API Overview

Programmatic access to your AVCodex agent's data: chat logs, consumers, analytics, and more.

The AVCodex Builder API gives you read access to your AVCodex agent's data through a standard REST API. Use it to pull chat transcripts into your CRM or PM tool, sync consumer data with Google Sheets, build custom dashboards, or connect to automation platforms like Zapier and Make.

Note: The AVCodex Builder API is separate from the AVCodex Chat Completions API. The Chat API sends messages to your agent. The Builder API reads data *from* your agent.

Quick start#

1. Get your API key#

Log into app.avcodex.com.
Open your agent.
Navigate to Builder Keys in the sidebar.
Create a new key or copy an existing one.

API keys use the avcodex_ prefix (for example, avcodex_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6).

2. Make your first request#

bash

curl https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"

That's it. You'll get a JSON response with your agent's recent chat sessions.

Base URL#

All Builder API endpoints are scoped to a specific agent:

code

https://app.avcodex.com/api/v1/apps/{appId}

Replace {appId} with your agent's ID (a UUID).

Authentication#

Every request requires a Bearer token in the Authorization header:

bash

Authorization: Bearer avcodex_YOUR_API_KEY

Keys are scoped to a single agent. A key for Agent A cannot read Agent B's data.

Response format#

All responses use a consistent JSON envelope.

List endpoints#

json

{
  "data": [
    { "id": "...", "..." : "..." }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6...",
    "limit": 25
  }
}

Some endpoints use offset-based pagination instead of cursors:

json

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "total": 142,
    "limit": 25,
    "offset": 0
  }
}

Single resource endpoints#

json

{
  "data": {
    "id": "...",
    "...": "..."
  }
}

Error format#

Errors return a JSON object with an error field containing code and message:

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Status codes#

Code	Description
200	Success.
400	Invalid request parameters.
401	Missing or invalid API key.
403	Key does not have access to this resource.
404	Resource not found.
429	Rate limit exceeded.
500	Server error.

Common error responses#

Missing API key (401)

json

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

Invalid key format (401)

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key format"
  }
}

Invalid API key (401)

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Expired API key (401)

json

{
  "error": {
    "code": "expired",
    "message": "API key has expired"
  }
}

Wrong agent (403)

json

{
  "error": {
    "code": "forbidden",
    "message": "API key does not match application"
  }
}

Not found (404)

json

{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}

Rate limited (429)

json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

The Retry-After response header contains the number of seconds to wait before retrying.

Rate limiting#

The AVCodex Builder API allows 120 requests per minute per API key.

Rate limit status is included in successful responses via headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window (120).
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.

These X-RateLimit-* headers are only present on successful (non-429) responses. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

JavaScript example#

javascript

const APP_ID = "your-app-id";
const API_KEY = "avcodex_your_api_key";

async function fetchSessions() {
  const response = await fetch(
    `https://app.avcodex.com/api/v1/apps/${APP_ID}/sessions`,
    {
      headers: {
        Authorization: `Bearer ${API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const { data, pagination } = await response.json();
  console.log(`Fetched ${data.length} sessions`);
  console.log(`Has more: ${pagination.has_more}`);
  return data;
}

Paginating through all results#

javascript

async function fetchAllSessions() {
  const sessions = [];
  let cursor = undefined;

  while (true) {
    const url = new URL(
      `https://app.avcodex.com/api/v1/apps/${APP_ID}/sessions`
    );
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const { data, pagination } = await response.json();

    sessions.push(...data);

    if (!pagination.has_more) break;
    cursor = pagination.next_cursor;
  }

  return sessions;
}

Available endpoints#

Endpoint	Description
Sessions	List sessions, get session details, read messages.
Consumers	List and look up consumers.
Feedback	Message ratings.
Tags	Message tags.
Knowledge Sources	Training data status.
Memories	User memory entries.
Analytics	Usage and token analytics.

*AVCodex · Your AV expertise. Amplified by AI.*