REST API

The Sema4.ai REST API lets you drive the platform programmatically — list and talk to agents, stream responses, queue and manage Work Items, read data connections, and more. It's the same surface the application uses, exposed for your own integrations and automations.

Alpha. This is the new v2 public API. It covers many more endpoints than the previous Agent and Work Item APIs and is still evolving — endpoints and fields may change. Pin to specific behavior with care.

Base URL

The API is served per-tenant, under your deployment host:

https://{your-deployment-host}/tenants/{tenant-id}/api/v2

Replace {your-deployment-host} with your deployment's hostname and {tenant-id} with your tenant. You can copy your exact base URL from the application — open Configuration > API Keys and it's shown next to the key. Every path in this reference is relative to that base — for example, GET /agents is https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents.

Every v1 endpoint is also reachable under v2 via the same handler. New endpoints (data connections, conversation files and data frames, and the richer Work Item surface) exist only under v2. The Agent MCP endpoint is the exception — it stays under the v1 prefix.

Authentication

The API authenticates with an API key as a bearer token. Include it on every request:

Authorization: Bearer YOUR_API_KEY

Create an API key

Open the application and go to Configuration > API Keys.
Create a new key, give it a name, and copy the value.
Store it securely — it's shown only once.

An API key carries the permissions of the workspace it belongs to. Treat it like a password: keep it server-side, never commit it, and rotate it if it leaks.

Pagination

The API uses two pagination styles depending on the resource:

Cursor-based (agents, conversations, messages). Pass limit, and when has_more is true, pass the next token to fetch the following page.

{ "next": "string", "has_more": true, "data": [ /* ... */ ] }

curl 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents?limit=50&next={next_token}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Offset-based (Work Items). Pass limit and offset; the response returns records and a next_offset to use for the next page.

Response codes

200 OK — the request succeeded; the body contains the result.
202 Accepted — the request was accepted for processing (used by the MCP endpoint for notification-only input).
400 Bad Request — malformed request or missing required parameters.
401 Unauthorized — missing or invalid API key.
403 Forbidden — the key isn't allowed to perform this operation.
404 Not Found — the agent, conversation, work item, or other resource doesn't exist.
412 Precondition Failed — the resource isn't in a state that allows this operation (e.g. an illegal Work Item lifecycle transition).
422 Unprocessable Entity — the request was well-formed but failed validation.
500 / 503 — server error or temporary unavailability; retry with backoff.

POST creates return 200 OK (not 201). Successful deletes and some attach/detach actions return 204 No Content.

Error format

Errors return a JSON body describing what went wrong:

{
  "error": {
    "code": "string",
    "message": "string",
    "details": { "field": "string", "issue": "string" }
  }
}

Reference

Agents — create, edit, and delete agents; drive the draft → publish version lifecycle; attach data and tools; export and import.
Conversations — open conversations, post and stream messages, and work with conversation files and data frames.
Work items — create, list, and drive Work Items through their lifecycle.
Data connections — manage the databases and files agents query, and read their semantic views.
Semantic data models — create, import, export, and scaffold the semantic layer agents query in natural language.
MCP servers — register and manage the tool providers agents attach to.
Document Intelligence — read the Document Intelligence configuration.
Agent MCP — talk to an agent as an MCP server over JSON-RPC.

Audit log Agents