Skip to main content

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, rotated and revoked under Workspace → Integrations → API keys, or with the /api/v1/auth/keys endpoints. 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 422 with 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 /async variant for this.
  • List endpoints paginate with page and per_page and return a pagination object.
  • 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.

Public endpoints​

A small set of endpoints under /api/public/ takes no API key and is used by the app's own sign-in flow to resolve a signed-in user to their workspaces and keys. They are listed in the reference for completeness; integrations should use a workspace key instead.

API reference

Every endpoint with request and response schemas.

Claude MCP server

A higher-level way to use the API from Claude.