Skip to main content
The OpenAPI document is at /v1/openapi.json; every endpoint is in the API reference tab.

​
Authentication

Send Authorization: Bearer <token>. Two kinds of token:
Soma’s authorization server follows the MCP authorization spec. Discover it from GET /.well-known/oauth-protected-resource/v1, which points at /.well-known/oauth-authorization-server. Register your app with a Client ID Metadata Document (your client_id is the https URL of your metadata) or through Dynamic Client Registration (POST /oauth/register), then run the authorization-code flow with PKCE (S256) and resource=https://staging.soma.evarist.com/v1. Ask for knowledge:read knowledge:write to create workspaces and add documents. Access tokens last one hour; refresh tokens rotate.
A request without a valid token gets 401 with a WWW-Authenticate header pointing at the metadata above. A read-only token used for a write gets 403 with type insufficient_scope.

​
Errors

Every error has the same shape:

​
Pagination

Lists return { "data": [...], "has_more": true, "next_cursor": "..." }. Pass cursor=<next_cursor> to get the next page, and limit to size them.

​
Long operations

  • Uploads return a job (202); follow it with GET /v1/jobs/{job_id} until status is done.
  • Ask takes 10 to 120 seconds; stream its progress with "stream": true. See Ask.

​
Limits

  • Ask: 60 questions per hour per user or key.
  • Uploads: 20 files per request, 100 MB per file.