REST API Reference

Synapse exposes a REST API for integrating agents and orchestrations into external applications. All endpoints require an API key for authentication.

Base URL

http://localhost:8000/api/v1

Change 8000 to your SYNAPSE_BACKEND_PORT if different.

Authentication

All API v1 endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Generating API keys

Go to Settings → API Keys → Generate Key. API keys are shown only once — copy and store them securely.

API keys are stored in DATA_DIR/api_keys.json.

Content type

All request bodies must be JSON:

Content-Type: application/json

Response format

All responses are JSON. Errors follow this format:

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

Endpoints

Method	Path	Description
POST	/chat	Synchronous chat
POST	/chat/stream	SSE streaming chat
GET	/agents	List all agents
GET	/agents/{agent_id}	Get agent details
GET	/orchestrations	List all orchestrations
GET	/orchestrations/{orch_id}	Get orchestration details
POST	/orchestrations/{orch_id}/run	Run orchestration (sync)
POST	/orchestrations/{orch_id}/run/stream	Run orchestration (SSE)
POST	/orchestrations/runs/{run_id}/resume	Resume paused run (sync)
POST	/orchestrations/runs/{run_id}/resume/stream	Resume paused run (SSE)

Agent resolution

The /chat endpoint accepts an optional agent parameter (name or ID). If omitted, the first configured agent is used. Agent names are matched:

1. Exact ID match
2. Case-insensitive name match
3. Partial name match
4. Fallback to first agent

Rate limits

Synapse does not enforce rate limits at the API layer — limits are determined by your LLM provider's API quotas.

Error codes

Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
404	Resource not found — agent, orchestration, or run ID doesn't exist
500	Internal server error — agent encountered an error
503	Service unavailable — server not fully started yet