HTTP API reference
This reference documents the gateway API, including orchestration, tasks and voice. Start with endpoint and authorization tables, then use the detailed request fields, response schemas, errors and examples for each family below.
Authentication and public paths
Configure API keys in gateway.api.keys in config.json. Send X-Api-Key: <key> or Authorization: Bearer <key>. The API returns 401 for a missing key and 403 for an invalid key. Agent access is checked separately; agents: "*" grants all-agent scope, write: true allows scoped writes, and admin: true allows administrative operations. See key configuration examples.
Public and cookie/ticket-authenticated exceptions are identified in the overview: health checks, provider-verified webhooks, capability share URLs, the dashboard, the paired terminal and OAuth callbacks have their own access rules. Monitoring requires admin access when keys are configured and fails closed on non-loopback keyless binds.
Use http://127.0.0.1:10850 for a local gateway or your configured gateway origin. API routers are mounted under /api, so router-local /v1/... paths (including route-manifest entries) become public /api/v1/... URLs. Root paths such as /health, /dashboard, /webhooks/..., /shared/... and /oauth/mcp/callback do not take this prefix. No real credentials are included in these examples: replace example values with your own configured keys and identifiers.
curl --fail http://127.0.0.1:10850/api/v1/agents \
-H "X-Api-Key: $CLAUDE_GATEWAY_API_KEY"Endpoint families
| Family | Reference |
|---|---|
| Endpoint overview | Open reference |
| System, health and route metadata | Open reference |
| Agents, avatars and creation wizard | Open reference |
| Messages and slash commands | Open reference |
| SSE, tool events and reconnects | Open reference |
| Models | Open reference |
| Session management | Open reference |
| Chat history and search | Open reference |
| Workspace files | Open reference |
| Skills and metrics | Open reference |
| Telegram access controls | Open reference |
| WhatsApp and Cloud API | Open reference |
| Open reference | |
| Discord access controls | Open reference |
| LINE and Slack webhooks | Open reference |
| Cron jobs | Open reference |
| Media upload and delivery | Open reference |
| File shares and image artifacts | Open reference |
| App Store, backups, proxy and app.yaml | Open reference |
| Connectors and OAuth | Open reference |
| Package updates | Open reference |
| Paired terminal viewer | Open reference |
| PTY screen and WebSocket | Open reference |
| Orchestration and activity | Open reference |
| Tasks and worker lifecycle | Open reference |
| Voice settings and streaming | Open reference |
For command-line usage, see CLI and HTTP API.