REST API
Kumkuat exposes the same operations the app uses over a REST API, documented in full in the API reference, which is generated from the live OpenAPI specification.
Base URL
https://api.kumkuat.ai
Interactive Swagger and ReDoc views are served by the API itself at /docs and /redoc, and the raw specification at /openapi/openapi.json.
Authentication
Every request carries a workspace API key in the X-API-Key header. Keys are minted, listed and revoked under Workspace → Integrations → API keys. A key is bound to one workspace and acts with the workspace's rights; keep it in a secret store.
curl -H "X-API-Key: $KUMKUAT_API_KEY" https://api.kumkuat.ai/api/v1/workspace
Conventions
- JSON in and out. Request bodies are validated; a failed validation returns
422with the field errors. - Long-running work (reaction generation, narrative tests, backloads, persona builds) is queued as a job. The response returns a job id you can poll; some endpoints have an
/asyncvariant for this. - List endpoints paginate with
pageandper_pageand return apaginationobject. - Identifiers are strings; persona, document and run ids are stable across a workspace's life.
Rate limits and quotas
Model-backed endpoints consume the workspace's run budget. A demo workspace has a fixed budget; a customer workspace's budget is agreed in the contract. Provider feeds carry their own rate limits, shown next to the feed in Workspace Status.
What the reference leaves out
The API's full OpenAPI document also carries routes the Kumkuat app uses for its own sign-in flow (under /api/public/), debug endpoints, and pilot features that are switched off for most workspaces. The API reference on this site leaves those out so that everything it lists can be called with a workspace key; the raw specification at /openapi/openapi.json still lists everything.