Conventions

Shared rules that apply across every /v1 endpoint.

Response envelope

Successful responses wrap the payload in a data key. List endpoints add meta:

{ "data": { "id": "…", "title": "…" } }

{ "data": [ /* … */ ], "meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3, "has_next": true } }

The one exception is the OpenAI-compatible chat/models surface, which uses OpenAI's native shapes ({ "object": "list", "data": [...] }).

Errors

Errors use a consistent shape with a machine-readable code, a human message, and the request_id for support:

{
  "error": {
    "code": "forbidden_scope",
    "message": "API key lacks required scope: consultations:write",
    "request_id": "3f9c…",
    "details": null
  }
}

Pagination

Most list endpoints use page-based pagination: page (default 1) and per_page (default 20, max 100). The meta block reports total, total_pages, and has_next.

/v1/panels uses cursor pagination instead: pass limit and a cursor (the ISO 8601 created_at of the last item).

Rate limits

Limits are enforced per API key and returned on every response:

x-ratelimit-limit: 200
x-ratelimit-remaining: 197
x-ratelimit-reset: 1770000060

Exceeding the limit returns 429 with a retry-after header. The per-minute request limit depends on your plan:

Idempotency

Endpoints that create work (consultations, batches) accept an idempotency key so retries never create duplicates. Send it either in the body as idempotency_key or as an Idempotency-Key header. A repeated key returns the original result.

Versioning

The API is versioned in the URL (/v1). Additive changes (new fields, new endpoints) ship within v1; breaking changes would land under a new prefix. Every response also carries an X-API-Version date header and an X-Request-ID you should log for support.

Usage and billing

GET /v1/usage reports cost for a period (from/to, max range 365 days), broken down by user and by source (ui vs api). Costs are in cents. Your monthly snapshot is also on /v1/me.