Version 2.5
REST API

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 under your deployment host:

https://{your-deployment-host}/api/v2

Replace {your-deployment-host} with your deployment's hostname. 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}/api/v2/agents.

Older integrations may use paths carrying a /tenants/spar/ prefix before /api (for example /tenants/spar/api/v2/agents). Those prefixed paths are still served for backwards compatibility, but new integrations should use the shorter base URL above.

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

  1. Open the application and go to Configuration > API Keys.
  2. Create a new key, give it a name, and copy the value.
  3. 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}/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 with a single error object:

{
  "error": {
    "error_id": "string",
    "code": "string",
    "message": "string"
  }
}
FieldTypeDescription
error_idstringUnique ID for this error occurrence. Include it when contacting support — it traces the request to the server logs.
codestringStable, machine-readable code, e.g. bad_request, unauthorized, forbidden, not_found, unprocessable_entity, too_many_requests, internal_error.
messagestringHuman-readable description of what went wrong.

Some errors include extra context fields alongside these — for example the offending value, such as "llm_id" or "setting".

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.
  • LLMs — manage LLM configurations and the workspace default models (admin only).
  • Branding — read and update the workspace name, logos, and primary color.
  • Advanced settings — read and update workspace quotas, retention, and feature toggles (admin only).
  • Document Intelligence — read the Document Intelligence configuration.
  • Agent MCP — talk to an agent as an MCP server over JSON-RPC.
Audit logAgents