Agent APIReference
Endpoint reference
Every Agent API endpoint, grouped by resource, with method, path, and required scope.
The Agent API has 43 operations across 38 paths. All are under the /v1 prefix except GET /health and GET /openapi.json. This page is the full index; each resource has a detail page with request and response fields and copy-paste examples.
Conventions
- Base URL:
http://127.0.0.1:8420 - Version prefix:
/v1on every path except/health - Every error response is JSON of this shape:
{"error":{"code":"not_found","message":"..."}}- Pagination uses
limit(max 200, default 50) andoffset. - Request and response bodies use snake_case field names on the wire. camelCase appears only inside the desktop app's internal calls, not in this HTTP API.
Unauthenticated endpoints
Three endpoints need no bearer token:
GET /healthPOST /v1/pair/requestGET /v1/pair/:id
All endpoints
Meetings endpoints are detailed on the meetings reference, recording endpoints on the recording reference, job endpoints on the jobs reference, system and config endpoints on the system reference, and error codes on the errors reference. Events and webhooks are covered separately in Events and SSE and Webhooks.
| Method + path | Scope | Summary |
|---|---|---|
GET /health | none | Liveness check; returns status, version, and webhook counters (events_dropped, deliveries_failed). |
GET /openapi.json | Read | The OpenAPI 3.1 manifest for the API. |
GET /v1/whoami | Read | Identify the caller: token id, scopes, license tier. |
GET /v1/meetings | Read | List meetings, paginated. |
GET /v1/meetings/:id | Read | Get one meeting. |
GET /v1/meetings/:id/transcript | Read | Get a meeting's transcript segments. |
GET /v1/meetings/:id/summary | Read | Get a meeting's summary. |
GET /v1/meetings/:id/export | Read | Export a meeting as JSON, Markdown, or plain text. |
GET /v1/search | Read | Full-text search across meetings. |
GET /v1/config/:section | Read | Get one config section. |
GET /v1/jobs | Read | List background jobs. |
GET /v1/jobs/:id | Read | Get one job by id. |
GET /v1/devices | Read | List audio devices. |
GET /v1/models | Read | List transcription models. |
GET /v1/recording | Read | Get current recording state. |
PATCH /v1/meetings/:id | Write | Rename a meeting. |
DELETE /v1/meetings/:id | Delete | Delete a meeting (cascades, irreversible). |
PUT /v1/meetings/:id/summary | Write | Set a meeting's summary text. |
POST /v1/meetings/:id/summary/regenerate | Write | Regenerate a summary; returns a process id. |
PUT /v1/meetings/:id/speaker-labels | Write | Set speaker label names for diarized clusters. |
PUT /v1/config/:section | Write | Update one config section. |
POST /v1/jobs/diarization | Write | Submit a diarization job for a meeting. |
POST /v1/jobs/import | Write | Import an audio file as a new meeting (raw bytes). |
POST /v1/jobs/:id/cancel | Write | Cancel a job. |
POST /v1/jobs/:id/pause | Write | Pause a job. |
POST /v1/jobs/:id/resume | Write | Resume a paused job. |
POST /v1/jobs/:id/retry | Write | Retry a job. |
POST /v1/recording/start | Record | Start recording; remote callers need remote_recording_prearmed. |
POST /v1/recording/stop | Record | Stop recording. |
POST /v1/recording/pause | Record | Pause recording. |
POST /v1/recording/resume | Record | Resume recording. |
GET /v1/jobs/:id/wait | Read | SSE; blocks until the job reaches a terminal state. |
GET /v1/recording/wait | Record | SSE; blocks until recording starts or stops. |
POST /v1/webhooks | Read (per-event scope escalation) | Register a webhook subscription; requires webhooks_enabled. |
GET /v1/webhooks | Read (Admin for ?all=true) | List your webhooks, or all webhooks as Admin. |
DELETE /v1/webhooks/:id | Write (owner) or Admin | Delete a webhook subscription. |
GET /v1/webhooks/:id/deliveries | Owner or Admin | List delivery attempts for a webhook. |
POST /v1/webhooks/:id/test | Write | Send a synthetic test delivery to this webhook. |
GET /v1/pairings | Admin | List pairing requests. |
DELETE /v1/pairings/:id | Admin | Revoke a pairing (atomic cascade: token revoke, owner webhooks delete, row delete). |
POST /v1/mcp/client-token | Admin | Mint a scoped per-client token for an MCP client. Loopback only. |
POST /v1/pair/request | none | Request a pairing from a remote client. |
GET /v1/pair/:id | none | Poll pairing status; returns the raw token once on approval. |
Which client can do what
| Capability | HTTP | CLI | Python SDK | MCP tool |
|---|---|---|---|---|
| List / read / export meetings | yes | yes | yes | yes |
| Rename / summary / speaker labels | yes | yes | yes | yes |
| Delete a meeting | yes (Delete scope) | yes | yes | not a tool (destructive) |
| Start / stop / pause / resume recording | yes | yes | yes | yes |
| Recording state | yes | not available | yes | yes |
| Submit diarization | yes | yes | yes | yes |
| Import an audio file | yes | not available | not available | not available |
| Get one job | yes | not available | not available | yes (get_job) |
| Wait for job / recording | yes | not available | yes | yes |
| Config get | yes | yes | yes | yes |
| Config set | yes | yes | yes | not a tool |
| Webhooks (create/list/test/delete) | yes | not available | yes | gated (start server with --allow-webhooks) |
| Pairings list / revoke | yes (Admin) | not available | yes | list only (list_pairings); revoke never a tool |
| whoami / health / devices / models | yes | yes | yes | yes (except health) |
Cells marked not available have no client command; use curl for those. Never assume a CLI or SDK method exists just because the HTTP route does.
Last updated on