REST API Reference

Base URL

The API lives at /api/v1 and /api/v2 under one origin:

The examples on these pages use http://localhost:3000; put your origin in its place. A self-hosted install serves the API through the web UI's port, which forwards /api/v1 and /api/v2 to the backend. Where you can reach the backend directly, http://localhost:8765/api/v1 works too (8765, or your SYNAPSE_BACKEND_PORT); the Docker images bind the backend to 127.0.0.1.

The CLI takes the origin alone, in SYNAPSE_API_URL, and adds the path itself.

Authentication

Every /api/v1 and /api/v2 endpoint requires an API key as a Bearer token:

Authorization: Bearer sk-syn-...

A missing, invalid or revoked key returns 401 with Invalid or revoked API key. The key goes in that header only: an API key in the URL (?token=…) is refused, so read a stream with fetch rather than a browser EventSource, which cannot send the header.

Synapse's own MCP endpoint, /api/v1/mcp, takes the same key.

Generating API keys

Go to Settings → API keys, enter a name for the key (e.g. "Slack Bot") and click Generate — or run synapse api-keys generate <name>. On SynapseOrch Cloud, owners and admins create keys under Settings → Developer — see API keys and the Developer page for what a Cloud key can and cannot reach. The key — sk-syn- followed by 32 hex characters — is shown once; copy it then.

SynapseOrch stores only a SHA-256 hash of each key, in its database, so a lost key can't be recovered: delete it and generate another.

The screens, step by step: The public API, in the Guides.

Content type

All request bodies must be JSON:

Content-Type: application/json

Response format

Responses are JSON, except the /stream endpoints, which return text/event-stream: data: {…} lines, plus a : ping comment line after 10 seconds without an event. SSE clients ignore comment lines; if you parse the stream yourself, skip lines that start with :.

Errors follow this format:

{
  "detail": "Error message describing what went wrong"
}

Endpoints — /api/v1

V1 runs everything in the API process, and its run and chat calls either wait for the result or stream it. The work belongs to the server, not the request: a caller that stops waiting or reading leaves it running to the end — cancel it to stop it.

See Chat API, Workflows API, Knowledge API and Webhooks. Each endpoint's page in the reference — under Reference: v1 in the sidebar — has its fields, every answer and samples in cURL, JavaScript, Python and Go.

Endpoints — /api/v2

V2 queues work for scale mode workers and answers at once. On a self-hosted install without scale mode, every V2 endpoint returns 503; SynapseOrch Cloud always serves it. Like v1, it does not list, serve or run Synapse AI's own workflow, nor read its runs. Each endpoint's page is under Reference: v2 in the sidebar.

Run and resume requests accept webhook_url and webhook_secret to be called back when the run ends. See Scale Architecture for the full round trip. A chat request accepts them too: the callback carries status completed with the answer, or failed with The agent encountered an error processing your request. when the turn failed — its model's own error included, which is never sent as the answer.

The run stream is resumable with Last-Event-ID; read it with fetch and the Authorization header, never a browser EventSource with the key in the URL, which is a 401. A chat stream's or events' error says which kind of failure it was — the model's quota, a refusal, a rate limit, an outage, or no usable answer — and never passes on the provider's own words. /chat/{session_id}/status returns the conversation's messages; an assistant message may carry reasoning and thoughts, lists of the newest 20 of each, each at most 4,000 characters.

Agent resolution

The chat endpoints of both /api/v1 and /api/v2 accept an optional agent parameter (name or ID). It is matched in this order:

1. Exact ID match
2. Exact name match, ignoring case

Anything else — a partial or misspelt name — returns 404; there is no fallback to another agent. With no agent given, the workspace's first agent, the oldest in the store, answers. Synapse AI's own agents are never chosen or matched, and GET /api/v1/agents does not list them.

Rate limits

On a self-hosted install, /api/v1 does not enforce rate limits — limits are determined by your model provider's quotas. /api/v2 run submissions are limited per tenant (1,000 per second by default) and return 429 above it, as they do when 1,000 runs are already queued, running or paused; a nested run counts as part of the run that started it. A full queue returns 503. See Configuration.

SynapseOrch Cloud limits each key to 300 requests a minute, and each organisation to 1,200. Starting work — a run, a chat turn, an answer to a paused run — has its own limit of 60 a minute per key, and a key holds at most 25 open streams. Above any of these the answer is 429 with Retry-After. Knowledge searches have their own limit, 120 a minute per key, shared with MCP's search_knowledge. A run also needs credits. One started beyond your plan's runs at once is not refused: it waits in line and reads queued, with its queue_position, until a slot frees — see Capacity. 429 then means the line itself is full.

Error codes