API reference

Everything the UI does is a REST call, and everything is callable by you.

Base URL and versioningCopy Anchor Link

Routes live under /api/v1/.... A few routes that outside systems have on file — webhooks, OAuth callbacks, health probes, the unsubscribe link — stay version-neutral at /api/...:

curl http://localhost:8000/api/health

AuthCopy Anchor Link

Two schemes, both on every protected route:

• Authorization: Bearer <jwt> — user sessions.
• X-API-Key: <key> — service callers. Keys are made at Settings → API Keys; see Settings for scopes and limits.

If both are sent, the key wins. Most routes then check a permission such as agent:read; see the role matrix in People & sharing. A key over its rate limit answers 429.

ChattingCopy Anchor Link

POST /threads/chat runs one turn. The body's input is an array of messages, each with a role (user or assistant) and parts — a plain content string is not read, and a body with no parts is a 400:

curl -X POST http://localhost:8000/api/v1/threads/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "<agent id>",
    "input": [{ "role": "user", "parts": [{ "type": "text", "text": "hello" }] }],
    "stream": false
  }'

Which agent runs. Name a stored agent with agentId, or define one for this turn with an inline agent object (needs agent:create). Sending both is a 400, and agent: { id } is rejected — agentId is the only way to name a stored agent, and it carries the id alone, so the agent's own tools and instructions always apply.

Delivery. By default the turn streams back as server-sent events (an AI SDK UI message stream). "stream": false runs the same turn and answers with one JSON body: id (the thread), messages (what this turn added), and text (the final answer's text). Omit id to start a new thread; send it to continue one. The other request fields — model, store, tools, scope, output, metadata — are covered in Chat & threads.

Rate limit. Chat is throttled per signed-in user, or per address for anonymous visitors — 30 turns a minute by default, plus a shared 60 a minute per address for visitors — and over the limit answers 429 with Retry-After. Calls with an API key skip this limiter; the key's own limit applies instead.

Interactive referenceCopy Anchor Link

Outside production, the API serves a full interactive reference (Scalar UI) at /reference on the API origin — every resource below, with schemas, try-it calls, and both auth schemes wired in.

Endpoint indexCopy Anchor Link

All paths below sit under /api/v1 unless noted.

A few notes on the less obvious groups:

• Entitlements reads the account's plan, features, limits (base plus add-ons), usage, active add-ons, and the add-on catalog. Plan and add-on changes need billing:update (owner only, never an API key); with payments connected, only platform operators may make them. The two check routes answer whether one more seat or API key fits, or whether the plan includes sso or nestedWorkspaces.
• Appearance is the org-wide chat theme every agent uses: GET needs agent:read (so widget visitors can load it), PATCH needs agent:update. Branding assets are the logos and icons it points at.
• Dashboard routes are the read models behind the Dashboard and need trace:read.
• Health: /api/health is liveness; /api/health/ready checks each dependency and answers 503 only when MongoDB is down — anything else down reports degraded at 200.

Members, invitations, roles, API keys, SSO, and notifications run through Better Auth (browser or server functions), not the Assivy REST API.