KaiHTTP API
The routes the web app uses, how they authenticate, and their errors.
The API exists for Kai's own web app. It isn't versioned and may change between releases; there are no API keys for scripts yet.
Conventions
- Authentication: the better-auth session cookie, set by
/api/auth/*. Every route except/api/health,/api/auth/*,/api/auth-configand the OAuth callback and client metadata needs it. - Workspace: the session's active workspace. No route takes a workspace id from the client.
- Bodies: JSON, at most 2 MB (files go straight to S3 with presigned URLs).
- Errors: one shape,
{ "error": "<code>", "message"?: "…" }, with the matching status:unauthorized(401),no_workspaceandforbidden(403),not_found(404),busyandconflict(409),invalid_requestand other input problems (422),rate_limited(429, withRetry-After), andprovider_*(502) when the model provider failed. The full list ispackages/core/errors; the web app keys its messages by code. - Secrets: never returned. Keys and credentials come back as
hasKeyand a shortkeyHint. - Streams: server-sent events with
Last-Event-IDresumption.
Handlers live in apps/api/src/routes/<path>/route.ts; [id] segments become
:id. scripts/gen-routes.mjs maps them to URLs in src/routes.gen.ts; the dev and
build scripts run it, so a new file is picked up on restart.
Routes
Account and workspace
| Method | Path | |
|---|---|---|
GET POST | /api/auth/* | better-auth: sign-up, sign-in, email codes, Google, sessions, organizations, invitations. |
GET | /api/auth-config | Which sign-in methods and sign-up mode the instance has. Public. |
GET | /api/me | The user, their workspaces and role. |
PATCH | /api/me/settings | Personal settings. |
POST DELETE | /api/me/delete-account | POST emails a code (and refuses while you own shared workspaces); DELETE with { code } deletes the account. |
GET PATCH | /api/workspace/settings | Workspace settings (owners and admins). |
GET PATCH | /api/workspace/preferences | Workspace defaults, like the default model. |
POST | /api/workspace/transfer-ownership | Owner only. |
GET | /api/workspace/usage | Token usage by day, member or model. |
GET | /api/events | SSE: the user's events in this workspace, shared across tabs (titles, new chats, runs finishing). |
GET | /api/health | Liveness. Public. |
Keys and models
| Method | Path | |
|---|---|---|
GET POST | /api/connections | List or add a key. |
POST | /api/connections/test | Test a key before saving it. |
GET PATCH DELETE | /api/connections/:id | |
POST | /api/connections/:id/test | |
POST | /api/connections/:id/discover | Ask the provider which models the key can use. |
GET PUT | /api/connections/:id/models | The key's models and which are enabled. |
GET | /api/models | Every model the user can pick, with capabilities. |
Chats and runs
| Method | Path | |
|---|---|---|
GET POST | /api/conversations | List (paged, searchable) or create. |
GET PATCH DELETE | /api/conversations/:id | The conversation with its active branch; rename, pin, archive. |
POST | /api/conversations/:id/messages | Send, edit or regenerate. Creates a run and returns its id. |
GET | /api/conversations/:id/messages/:messageId/siblings | A message's alternatives. |
POST | /api/conversations/:id/active-leaf | Switch branch. |
POST | /api/conversations/:id/compact | Summarize older messages. |
GET | /api/runs/:id | A run's state. |
GET | /api/runs/:id/events | SSE: the run's parts as they stream. |
POST | /api/runs/:id/cancel | Stop. |
POST | /api/runs/:id/interrupts/:interruptId | Answer an approval: allow or deny, once, for the chat, or always. |
GET | /api/tool-outputs/:partId | A large tool output, from S3. |
GET | /api/tool-outputs/:partId/text | The same, as text. |
POST | /api/attachments | Start an upload: returns a presigned PUT URL. |
POST | /api/attachments/:id/complete | Finish it (images are resized here). |
GET | /api/attachments/:id/url | A presigned download URL. |
Tools and agents
| Method | Path | |
|---|---|---|
GET POST | /api/mcp/servers | List (with this user's status) or add. |
GET PATCH DELETE | /api/mcp/servers/:id | |
POST | /api/mcp/servers/:id/test | Connect and list tools. |
PUT DELETE | /api/mcp/servers/:id/credentials | This user's values, or the shared ones. |
POST | /api/mcp/servers/:id/connect | Start OAuth sign-in: returns the authorization URL. |
DELETE | /api/mcp/servers/:id/connection | Sign out of the server. |
GET | /api/mcp/oauth/callback | The OAuth redirect URI. |
GET | /api/mcp/oauth/client-metadata.json | Kai's OAuth client metadata document. Public. |
POST | /api/mcp/openapi/preview | Fetch an OpenAPI document and list the tools it would give. |
GET | /api/mcp/catalog | The library's servers. |
GET DELETE | /api/tool-grants | Remembered approvals; DELETE with { ids }. |
DELETE | /api/tool-grants/:id | |
GET POST | /api/tool-groups | |
PATCH DELETE | /api/tool-groups/:id | |
GET POST | /api/agents | |
GET PATCH DELETE | /api/agents/:id |