> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sempera.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with the Sempera API

> The twelve-step developer journey from key to published agent to a real conversation.

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](https://docs.sempera.org/authentication.md)). If you do not have a workspace yet, write to [hello@sempera.org](mailto: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](https://docs.sempera.org/errors-and-limits.md)).
* **A key is a secret.** Keep it on your server, never in a browser or a repository ([Security and privacy](https://docs.sempera.org/security-and-privacy.md)).
* **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

```bash theme={null}
curl https://api.sempera.org/v1/me \
  -H "Authorization: Bearer sempera_sk_..."
```

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

```bash theme={null}
curl -X POST https://api.sempera.org/v1/agents \
  -H "Authorization: Bearer sempera_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-northwind-1" \
  -d '{"name": "Northwind Barbers"}'

curl -X PATCH https://api.sempera.org/v1/agents/northwind-barbers/draft \
  -H "Authorization: Bearer sempera_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"fields": {"greeting": "Thanks for calling Northwind Barbers, this is Nova."}}'

curl -X POST https://api.sempera.org/v1/agents/northwind-barbers/publish \
  -H "Authorization: Bearer sempera_sk_..." \
  -H "Idempotency-Key: publish-northwind-1"
```

## Connecting a coding agent (MCP)

`POST /v1/mcp` is a JSON-RPC 2.0 [Model Context Protocol](https://modelcontextprotocol.io) 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:

```bash theme={null}
curl -X POST https://api.sempera.org/v1/mcp \
  -H "Authorization: Bearer sempera_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp_client_setup","arguments":{"client":"claude-code"}}}'
```

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](https://docs.sempera.org/authentication.md)).
* **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](https://docs.sempera.org/billing-boundaries.md)).
* **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](https://docs.sempera.org/recordings.md)).
* **Replace the App's owner features.** Call-data exports, outbound scheduling and tool analytics have no API route ([Owner features in the App](https://docs.sempera.org/app-features.md)).
* **Install a Sempera SDK.** None is published; the OpenAPI document is the contract ([Web SDK](https://docs.sempera.org/web-sdk.md)).

## 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](https://docs.sempera.org/security-and-privacy.md), [billing boundaries](https://docs.sempera.org/billing-boundaries.md) and [supported clients](https://docs.sempera.org/supported-clients.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.