Conventions

The SDK covers the routes an app calls, so most apps never call the API directly; user erasure, MCP, message deletion and the project read API other than its thread and message lists are REST only. These pages are for the cases that do: a server in another language, an exporter, an evaluation job, or a look at what the SDK sends. Each resource has its own page with every route, parameter table, example and status table; this page holds what they share.

Hosts and credentials

A credential is accepted only on its own host; presented elsewhere it answers 403 with Origin does not match project ID. On a valid provider JWT the response carries an Authorization header with a five minute token of the project's own, which the SDK uses for the following requests. The API key routes, the routes that accept nothing but a key, and how each credential names the user and the workspace are on Authentication.

Headers

The frontend host answers the browser origins listed under Settings › Access; an empty list answers every origin. See Allowed origins.

Send a request

A server call carries the key and the two identity headers. The same request, creating a thread, in curl and in TypeScript:

curl https://backend.assistant-api.com/v1/threads \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Aui-User-Id: user_123" \
  -H "Aui-Workspace-Id: workspace_123" \
  -H "Content-Type: application/json" \
  -d '{ "last_message_at": "2026-09-17T09:30:00.000Z", "external_id": "crm:conversation:42" }'

const response = await fetch("https://backend.assistant-api.com/v1/threads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASSISTANT_API_KEY}`,
    "Aui-User-Id": "user_123",
    "Aui-Workspace-Id": "workspace_123",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    last_message_at: new Date().toISOString(),
    external_id: "crm:conversation:42",
  }),
});
const { thread_id } = await response.json();

A browser call carries the token the SDK holds for the session, on the project's frontend host:

const response = await fetch(
  `${process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL}/v1/threads?limit=20`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
);
const { threads } = await response.json();

Every route on the following pages has this curl form with its headers, then the request and response bodies and the status table.

Ids, time and paging

Ids are a prefix and 24 characters: thread_0…, msg_0…, run_0…, score_…, usr_anon_0…. Timestamps are ISO 8601 in UTC. Thread, project, MCP and trace responses are sent with Cache-Control: private, no-store.

Errors

Errors return JSON. The message is in a string error, such as { "error": "Thread not found" }, except for the /v1/mcp transport's 401 and 406 responses, which MCP describes. Branch on the status code, not the text: the message is for people. A body or query that fails the route's schema answers 400 with { "error": "Schema validation error", "details": […] }, where details lists the failed checks. An unknown route answers 404 with { "error": "Not Found" }. The 402 and 429 bodies below carry more fields beside error, and an unexpected failure answers 500 with { "error": "Internal Server Error" }.

Threads, messages, run reports, scores, traces, the project read API and MCP are not rate limited. Every size limit is on Limits.

Routes

GET /healthz answers { "ok": true } without a credential. The TypeScript surface of the same routes is on The assistant-cloud client.