Skip to main content
Base URL: https://api.sempera.org/v1. Every request is JSON over HTTPS with an API key in the Authorization header.

​
Before you start

  • You need a workspace and an API key. New registrations are temporarily unavailable; existing customers can log in to the Sempera App at https://app.sempera.org. The workspace owner creates API keys there under Settings, API keys, or with POST /v1/api-keys (Authentication and credentials). If you do not have a workspace yet, write to hello@sempera.org to ask for access.
  • There is one API hostname and no separate test host. Everything below runs against https://api.sempera.org. Experiment in a workspace you can afford to change, and use Idempotency-Key on writes you may retry (Errors and limits).
  • A key is a secret. Keep it on your server, never in a browser or a repository (Security and privacy).
  • Examples here are synthetic. They use a demonstration agent, northwind-barbers. Substitute your own agent’s id.

​
The developer journey

  1. Get an API key. The workspace owner creates one in the App (Settings, API keys, New API key) or with POST /v1/api-keys. The secret starts with sempera_sk_ and is shown once.
  2. Create an Agent. POST /v1/agents with {"name": "Northwind Barbers"}. The response is the Agent, including its stable id.
  3. Configure instructions and voice. PATCH /v1/agents/{id}/draft with {"fields": {...}}. Read GET /v1/agents/{id}/draft first: editable_fields lists the keys a PATCH may carry, and GET /v1/agents/{id} shows their current values.
  4. Attach tools. Create them once with POST /v1/tools, then reference their ids in the draft’s attachment fields.
  5. Attach knowledge. Upload documents with POST /v1/knowledge-sources?agent_id=... (multipart), then attach the collection in the draft.
  6. Preview. POST /v1/agents/{id}/preview with {"message": "Hi, can I book a haircut?"} runs one typed turn against the draft.
  7. Run tests. POST /v1/tests with {"agent_id": "..."} starts the scripted battery; poll GET /v1/tests/{test_id}.
  8. Publish. POST /v1/agents/{id}/publish creates a new immutable version. Production only ever uses a published version.
  9. Open a conversation. POST /v1/sessions with {"agent_id": "...", "channel": "web_voice"} returns a short-lived realtime token for a browser, or bind a number with POST /v1/phone-numbers.
  10. Inspect it. GET /v1/sessions?agent_id=... lists every conversation; GET /v1/sessions/{id} has the transcript, tool timeline and outcome.
  11. Run evals. Define criteria with POST /v1/evals, judge conversations with POST /v1/evals/run.
  12. Iterate. Edit the draft, preview, publish again. Versions are never rewritten; roll back with POST /v1/agents/{id}/rollback.

​
First request

The answer says what the credential is: its kind, workspace, role, scopes and the agents it can see. Every response carries X-Request-Id; quote it when you write to support.

​
Create and publish an agent

​
Connecting a coding agent (MCP)

POST /v1/mcp is a JSON-RPC 2.0 Model Context Protocol endpoint (initialize, tools/list, tools/call), for driving Sempera from a coding agent instead of a browser. It needs agents:read, the same bearer key as every other route. Three tools: list_agents and get_agent wrap the Agents API; mcp_client_setup (arguments {"client": "claude-code" | "claude-desktop" | "cursor" | "vs-code" | "windsurf" | "gemini-cli" | "codex" | "other"}) returns that client’s own URL, header and config snippet, so a coding agent (or you) can connect any of them without leaving the session:
The same answer is a plain read at GET /v1/mcp/clients/{client} (same key, same scope), which is what the App’s Settings > API keys page uses. Writes stay on the REST routes above; nothing here mutates a workspace yet.

​
What the API does not do yet

Plan for these before you design around the API:
  • Create a workspace. A workspace is created in the App when a person signs up. No API route creates one, and the first API key is created in the App too (Authentication and credentials).
  • Buy or search for a phone number. POST /v1/phone-numbers points a number you supply at an agent.
  • Manage plans, payment methods or invoices. Those live in the Sempera App (Billing boundaries).
  • Change recording, retention or deletion settings, or hand you call audio. Those are workspace owner settings in the App, and an API key is never given audio (Call recordings).
  • Replace the App’s owner features. Call-data exports, outbound scheduling and tool analytics have no API route (Owner features in the App).
  • Install a Sempera SDK. None is published; the OpenAPI document is the contract (Web SDK).

​
Where the rest is

The full contract is https://api.sempera.org/openapi.json. The guide pages are listed in https://api.sempera.org/llms.txt. Three pages answer the questions teams ask before they commit: security and privacy, billing boundaries and supported clients.