docs/en/reference/server-api.md

# Server API

The local server started by `kimi web` exposes two programmatic surfaces: a REST API (`/api/v1`, plus `/api/v2/sessions` and `/api/v2/mcp`) and a WebSocket event stream (`/api/v1/ws`). This page is the protocol reference for both. For how to start the server and its command-line options, see the [kimi command](./kimi-command.md#kimi-web) reference; for an end-to-end walkthrough, see [Drive a session over the API](#drive-a-session-over-the-api) below.

This page is a curated, human-readable reference: it documents every endpoint's parameters, request bodies, and response shapes below. The precise machine-readable schema of every endpoint is owned by the server's live specification documents: `GET /openapi.json` (OpenAPI) and `GET /asyncapi.json` (AsyncAPI), both generated from the same validation schemas the server enforces at runtime. Both require authentication; when this page and the live spec ever disagree, the live spec wins.

::: warning
The REST and WebSocket APIs described on this page are experimental: interface stability is not guaranteed, and endpoints, fields, and event types may change in any release. When integrating, rely on the `/openapi.json` and `/asyncapi.json` documents served by your version.
:::

## Conventions

### Address

The default address is `http://127.0.0.1:58627`. When the port is taken, the server retries with the next port (up to 100 times); use `--port` / `--host` to change the bind. Multiple instances can coexist under the same home directory; running instances register under `~/.kimi-code/server/instances/`.

### Authentication

All `/api/*` paths (including `/openapi.json` and `/asyncapi.json`) require the bearer token, except:

- `OPTIONS` preflight requests
- `GET /api/v1/healthz` (liveness probe)
- Static web assets (non-`/api/` paths)

How to carry it: REST uses the `Authorization: Bearer <token>` header; the WebSocket upgrade accepts the same header or the subprotocol `kimi-code.bearer.<token>`. Token generation and rotation are covered in [Using Kimi Code in the browser: Getting started](../guides/web.md#getting-started).

Failed authentication returns HTTP 401 with envelope code `40101`. On non-loopback binds, a source that fails authentication 10 times within 60 seconds is banned for 60 seconds, during which every request gets HTTP 429 (code `42901`).

### Response envelope

Every JSON response is wrapped in a uniform envelope:

```json
{
  "code": 0,
  "msg": "success",
  "data": {},
  "request_id": "01JZX4A6E7M8V0R3Q0N2K2M5Q9"
}
```

- `code`: the business outcome; `0` means success. See the error-code bands below.
- `data`: the payload on success. Note that some "error" envelopes also carry a non-null `data` — for example, resolving an already-resolved approval returns `40902` with `data.resolved` set to `false` — so clients should check `code` first, then `data`.
- `request_id`: a ULID for this request. Clients may supply one via the `X-Request-Id` header; invalid values are regenerated by the server.

The HTTP status is almost always 200; the business outcome lives in `code`. Exceptions:

| Situation | HTTP status |
| --- | --- |
| Authentication failure / rate limit | 401 / 429 |
| Provider created, provider catalog imported | 201 |
| Provider deleted | 204 |
| Binary/streaming endpoints | 206 (Range) / 304 (ETag unchanged) where supported — capabilities differ per endpoint, see [Binary and streaming endpoints](#binary-and-streaming-endpoints) |
| `GET /api/v1/files/{file_id}` download errors | real 404 / 500 (still carrying an envelope body) |

The 201 responses still carry the standard envelope (`code` 0) — only the status line follows the REST convention for resource creation. A 204 response has no body by definition, so a successful delete is reported by the status code itself.

### Error codes

Error codes are grouped by band:

| Band | Meaning | Examples |
| --- | --- | --- |
| `0` | Success | |
| `400xx` | Bad request | `40001` validation failed (`details` lists each field), `40003` provider is OAuth-managed |
| `401xx` | Auth and readiness | `40101` unauthorized, `40110` no provider configured, `40113` model not resolved |
| `404xx` | Not found | `40401` session, `40408` MCP server, `40409` file path |
| `409xx` | State conflict | `40901` session busy, `40902` approval already resolved, `40922` page conditions mismatch `page_token` |
| `410xx` | Expired | `41001` approval timed out, `41002` question timed out, `41003` temporary file expired |
| `413xx` | Size or boundary exceeded | `41302` file read over 10 MB, `41304` path escapes the session directory |
| `429xx` | Rate limited | `42901` auth-failure ban, `42902` too many fs watches |
| `500xx` | Server internal error | `50001` uncaught exception, `50003` persistence failure |
| `6xxxx` / `7xxxx` / `8xxxx` | Tool runtime / LLM provider / MCP passthrough errors; `msg` carries the upstream text | |

### Pagination

List endpoints come in two styles:

- **Cursor style**: `before_id` / `after_id` (mutually exclusive) plus `page_size` (1–100), responding with `{ items, has_more }`. Used by the session list, message list, transcript, and others.
- **`page_token`**: an opaque token (bound to a fingerprint of the query conditions), used by `POST /api/v1/search` and `GET /api/v2/sessions`. Changing any query condition mid-pagination invalidates the token: v2 returns `40922`, search returns `40001`. `GET /api/v2/sessions` also offers a stateless `page` page-number mode as an alternative.

## Drive a session over the API

The minimal flow with curl: check the server → create a session → subscribe to events → submit a prompt → read history back. The examples assume the server runs at the default address and the token is stored in the shell variable `TOKEN`.

1. Check server status:

```sh
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:58627/api/v1/meta
```

Every JSON response is wrapped in a uniform envelope — `{ "code": 0, "msg": "success", "data": ..., "request_id": "..." }`. The business outcome lives in `code` (`0` means success); the HTTP status only reports transport-level results.

2. Create a session; `metadata.cwd` sets the working directory:

```sh
curl -s -X POST http://127.0.0.1:58627/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"cwd": "/path/to/project"}}'
```

The returned `data.id` (shaped like `session_...`) is the session id used by every subsequent request.

3. Connect to the WebSocket and subscribe to session events. Any WebSocket client works; below is a dependency-free Node.js script (Node.js 22+ ships a built-in `WebSocket` client):

```js
// subscribe.mjs — usage: TOKEN=... node subscribe.mjs session_...
const ws = new WebSocket('ws://127.0.0.1:58627/api/v1/ws', [
  `kimi-code.bearer.${process.env.TOKEN}`,
]);
ws.onmessage = (e) => console.log(e.data);
ws.onopen = () =>
  ws.send(
    JSON.stringify({
      type: 'subscribe',
      id: '1',
      payload: { session_ids: [process.argv[2]] },
    }),
  );
```

4. Submit a prompt:

```sh
curl -s -X POST http://127.0.0.1:58627/api/v1/sessions/<session_id>/prompts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"type": "text", "text": "Introduce this repository in one sentence"}]}'
```

The subscriber sees, in order: `turn.started` (turn begins) → `assistant.delta` (streaming text increments) → `tool.call.started` / `tool.result` when tool calls happen → `turn.ended` (turn finishes).

5. Read history back over REST at any time:

```sh
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:58627/api/v1/sessions/<session_id>/messages?page_size=20"
```

## REST endpoints

Endpoints are grouped by resource below. A `:{action}` suffix in a path is the action convention — POST to `path:action` on a single resource for non-CRUD operations (such as `:fork` and `:archive` on a session).

### Server and metadata

| Method and path | Description |
| --- | --- |
| `GET /api/v1/healthz` | Liveness probe; auth-exempt |
| `GET /api/v1/meta` | Server version, capability map, `server_id`, experimental flags |
| `POST /api/v1/shutdown` | Graceful shutdown (replies 200 first); mounted only on loopback binds |

#### `GET /api/v1/healthz`

Liveness probe for scripts and process supervisors. It is the one `/api` endpoint exempt from the bearer token (see [Authentication](#authentication)) and answers without touching config or the engine.

On success, `data` is `{ "ok": true }`.

#### `GET /api/v1/meta`

Returns this instance's identity and capability map. Most fields are frozen at boot; `experimental_flags` and `features` are resolved per request, so a flag flip or a failed feature shows up in the next response.

On success, `data` carries:

| Field | Type | Description |
| --- | --- | --- |
| `server_version` | string | Server version |
| `capabilities` | object | Capability map — `websocket`, `file_upload`, `fs_query`, `mcp`, `tasks`, `terminal`, all always `true` |
| `server_id` | string | Unique id of this server instance |
| `started_at` | string | Boot time, ISO 8601 |
| `open_in_apps` | array | Host apps usable as `open-in` targets (`finder` / `cursor` / `vscode` / `iterm` / `terminal`); currently always empty |
| `dangerous_bypass_auth` | boolean | Whether the server was started with `--dangerous-bypass-auth` (clients may skip the token prompt) |
| `backend` | string | Engine backend, `v1` or `v2`; always `v2` for this server |
| `web_title` | string | Custom browser tab title from `--web-title`; omitted when unset |
| `experimental_flags` | object | Experimental flag id → enabled, resolved at request time |
| `features` | array | Engine features as `{ name, state, meta }`; `state` is `Pending` / `Activating` / `Active` / `Unloading` / `Failed` |

#### `POST /api/v1/shutdown`

Asks the server to shut down gracefully. The reply is sent first and the shutdown runs immediately after, so the caller can trust the response it received. The route is mounted only on loopback binds — on a non-loopback bind it is not registered at all (requests hit a 404) unless the server was started with `--allow-remote-shutdown`.

On success, `data` is `{ "ok": true }`.

### Login and usage

These endpoints drive the managed Kimi OAuth login lifecycle and expose account-level information. The managed provider is named `managed:kimi-code`; the optional `provider` parameter on every endpoint below defaults to it.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/auth` | Auth snapshot |
| `POST /api/v1/oauth/login` | Start the OAuth device-code login flow |
| `GET /api/v1/oauth/login` | Poll the login flow state |
| `DELETE /api/v1/oauth/login` | Cancel a pending login flow |
| `POST /api/v1/oauth/logout` | Log out the managed provider |
| `GET /api/v1/oauth/usage` | Plan quota and booster wallet |
| `GET /api/v1/oauth/userinfo` | Account profile |
| `GET /api/v1/oauth/region` | Resolve the client region (`mainland-cn` / `global`) |

#### `GET /api/v1/auth`

Auth snapshot: whether the default model resolves to a usable provider configuration, plus the managed provider's login state. `models_ready` is `true` when the global `default_model` alias exists in the model table and resolves to a configured provider — including providerless flat models carrying their own `base_url` and models injected through `KIMI_MODEL_*` environment variables. It does not verify credentials, so a prompt can still fail afterwards with `40111` / `40112`.

On success, `data` carries `models_ready` (boolean), `providers_count` (number of configured providers), and `managed_provider` (`null`, or `{ name, status }` with `status` one of `authenticated` / `expired` / `revoked` / `unauthenticated`). The global default model alias itself is read from `GET /api/v1/config` (`default_model`), not from this endpoint.

#### `POST /api/v1/oauth/login`

Starts an OAuth device-code login flow for the managed provider; starting a new flow aborts any pending flow for the same provider. When the account is already authenticated, no user interaction is needed and the response reports `authenticated` immediately.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider` | body | string | Managed provider name. Default `managed:kimi-code` |
| `region` | body | string | `mainland-cn` or `global`; overrides the region resolution described under `GET /api/v1/oauth/region` for this flow |

On success, `data` has one of two shapes. A pending flow — `{ flow_id, provider, status: "pending", verification_uri, verification_uri_complete, user_code, expires_in, interval, expires_at }`: open `verification_uri_complete` (or `verification_uri` and enter `user_code`), then poll `GET /api/v1/oauth/login` every `interval` seconds until the flow resolves or `expires_at` passes (`expires_in` is the same deadline in seconds). The already-authenticated fast path — `{ flow_id, provider, status: "authenticated" }`.

#### `GET /api/v1/oauth/login`

Polls the login flow state for a provider. Returns `null` when no flow has been started.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider` | query | string | Managed provider name. Default `managed:kimi-code` |

On success, `data` is `null` or a flow snapshot: `{ flow_id, provider, status, verification_uri, verification_uri_complete, user_code, expires_in, expires_at, interval }`, where `status` is `pending` / `authenticated` / `denied` / `expired` / `cancelled`. Once the flow leaves `pending`, `resolved_at` records when it reached its terminal state and `error_message` describes a failed flow.

#### `DELETE /api/v1/oauth/login`

Cancels the pending login flow for a provider. When no flow is pending, the call is a no-op that reports the last known state.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider` | query | string | Managed provider name. Default `managed:kimi-code` |

On success, `data` is `{ cancelled, status }`: `cancelled` is `true` only when a `pending` flow was actually aborted, and `status` is the flow state after the call.

#### `POST /api/v1/oauth/logout`

Logs out the managed provider: discards the stored OAuth credential, aborts any pending login flow, and removes the managed provider from the configuration. OAuth-managed providers reject manual edit and delete (see `PUT` / `DELETE /api/v1/providers/{provider_id}` below), so log out first to remove one.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider` | body | string | Managed provider name. Default `managed:kimi-code` |

On success, `data` is `{ logged_out: true, provider }`.

#### `GET /api/v1/oauth/usage`

Plan quota and booster wallet of the managed account, fetched live from the account service. An upstream failure does not fail the envelope — it comes back in-band with `kind: "error"`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider` | query | string | Managed provider name. Default `managed:kimi-code` |

On success, `data` is `{ kind: "ok", quota }` or `{ kind: "error", message, status? }`, where `status` is the upstream HTTP status when one exists. In the `ok` shape, `quota` is `{ usages, extraUsage }`: `usages` carries one `{ usedRatio, resetAt? }` entry per quota window the account has — `limit5h`, `limit7d`, `monthTotal`, `monthCode` — with `usedRatio` as a 0–1 float and `resetAt` as an RFC3339 reset timestamp, and clients render whichever entries are present; `extraUsage` (nullable) is the pay-as-you-go wallet: `{ balanceCents, totalCents, monthlyChargeLimitEnabled, monthlyChargeLimitCents, monthlyUsedCents, currency }`.

#### `GET /api/v1/oauth/userinfo`

Profile of the managed account, with the same in-band `kind: "error"` convention as `GET /api/v1/oauth/usage`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider` | query | string | Managed provider name. Default `managed:kimi-code` |

On success, `data` is `{ kind: "ok", userInfo }` or `{ kind: "error", message, status? }`. `userInfo` always carries `userId`, `nickname`, `status`, `region`, `userLevel`, `userLevelName`, `domain`, and `domainName`, and may add `globalId`, `bio`, `avatar`, `username`, `email`, `phone` (`{ countryCode, number }`), `createdTime`, and `lastLoginTime`.

#### `GET /api/v1/oauth/region`

Resolves which Kimi region this client belongs to. The answer is derived locally, not probed over the network: an OAuth host pinned by environment or config wins first, then the configured OAuth key, then the region marker file in the home directory; the default is `mainland-cn`.

On success, `data` is `{ region }` with `region` one of `mainland-cn` / `global`.

### Config

| Method and path | Description |
| --- | --- |
| `GET /api/v1/config` | Read the global config (secret fields redacted) |
| `POST /api/v1/config` | Merge-patch the config; broadcasts `event.config.changed` |

#### `GET /api/v1/config`

Returns the resolved global configuration — the effective result of `config.toml` plus overlays. Secrets are redacted: each provider reports only `has_api_key`, never the stored key.

On success, `data` is the config object; its fields mirror the top-level domains documented under [Top-level fields](../configuration/config-files.md#top-level-fields):

| Field | Type | Description |
| --- | --- | --- |
| `providers` | object | Map of provider id → `{ type, base_url?, default_model?, has_api_key }` |
| `default_provider` | string | Global default provider id |
| `default_model` | string | Global default model alias |
| `models` | object | Map of model alias → model record |
| `thinking` | object | Default parameters for Thinking mode |
| `plan_mode` | boolean | Plan mode flag |
| `yolo` | boolean | Derived: `true` when `default_permission_mode` is `yolo` |
| `default_permission_mode` | string | Default permission mode for new sessions |
| `default_plan_mode` | boolean | Whether new sessions start in Plan mode |
| `permission` | object | Initial permission rules |
| `hooks` | array | Lifecycle hooks |
| `services` | object | Built-in external service configuration |
| `merge_all_available_skills` | boolean | Whether to merge Agent Skills from all available directories |
| `extra_skill_dirs` | array | Extra skill search directories |
| `loop_control` | object | Agent loop control parameters |
| `background` | object | Background task runtime parameters |
| `subagent` | object | Subagent configuration |
| `secondary_model` | object | Secondary model pool for subagents |
| `experimental` | object | Experimental flag id → enabled |
| `telemetry` | boolean | Whether anonymous telemetry is enabled |
| `raw` | object | Raw parsed `config.toml` content, unmodeled fields included |

#### `POST /api/v1/config`

Merge-patches the global configuration: each top-level domain in the body is deep-merged into that domain, and domains absent from the body are left untouched. Setting `yolo` to `true` is shorthand for `default_permission_mode: "yolo"`; a rejected patch (invalid value or persistence failure) returns `40001` with the underlying message.

Every config change — a successful update through this endpoint, an external edit of `config.toml`, or a server-side write such as an OAuth login refresh — is broadcast as the global `event.config.changed` event. Changes inside a short window are merged into one event carrying the affected domain names in `changedFields` (camelCase config domains, for example `defaultModel`) and the full current config projection in `config` (same shape as the `GET /api/v1/config` response).

The body is a partial config object — any subset of the response domains above except `raw`, all optional:

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `providers` | body | object | Map of provider id → provider table |
| `default_provider` | body | string | Global default provider id |
| `default_model` | body | string | Global default model alias |
| `models` | body | object | Map of model alias → model record |
| `thinking` | body | object | Default parameters for Thinking mode |
| `plan_mode` | body | boolean | Plan mode flag |
| `yolo` | body | boolean | `true` maps to `default_permission_mode: "yolo"`; `false` is ignored |
| `default_permission_mode` | body | string | `manual` / `yolo` / `auto` |
| `default_plan_mode` | body | boolean | Whether new sessions start in Plan mode |
| `permission` | body | object | Initial permission rules |
| `hooks` | body | array | Lifecycle hooks |
| `services` | body | object | Built-in external service configuration |
| `merge_all_available_skills` | body | boolean | Whether to merge Agent Skills from all available directories |
| `extra_skill_dirs` | body | array | Extra skill search directories |
| `loop_control` | body | object | Agent loop control parameters |
| `background` | body | object | Background task runtime parameters |
| `subagent` | body | object | Subagent configuration |
| `secondary_model` | body | object | Secondary model pool for subagents |
| `experimental` | body | object | Experimental flag id → enabled |
| `telemetry` | body | boolean | Whether anonymous telemetry is enabled |

On success, `data` is the full updated config in the same shape as `GET /api/v1/config`.

### Models and providers

These endpoints manage the two halves of model configuration — the [providers](../configuration/providers.md) table and the model-alias table of `config.toml` — plus a server-proxied models.dev directory for one-shot imports. A model alias id is the exact configured alias key: aliases created through the provider-management endpoints take the form `provider_id/model` (for example `my-provider/kimi-for-coding`), while a bare model-table key such as `turbo` is used as-is; anywhere the API takes a `model_id`, including the global `default_model`, it means this alias id. An unsupported action on a `:{action}` route returns `40001`.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/models` | List configured model aliases |
| `POST /api/v1/models/{model_id}:set_default` | Set the global default model |
| `GET /api/v1/providers` | List providers |
| `POST /api/v1/providers` | Create a provider (201) |
| `GET /api/v1/providers/{provider_id}` | Read a provider (reveals the stored key) |
| `PUT /api/v1/providers/{provider_id}` | Replace a provider |
| `DELETE /api/v1/providers/{provider_id}` | Delete a provider (204) |
| `POST /api/v1/providers/{provider_id}:refresh` | Refresh one provider's model metadata |
| `POST /api/v1/providers:{action}` | Collection actions: `refresh` / `refresh_oauth` / `import_catalog` / `import_registry` |
| `GET /api/v1/catalog/providers` | Browse the models.dev directory (server-proxied) |
| `GET /api/v1/catalog/providers/{catalog_id}` | Read one directory entry |

#### `GET /api/v1/models`

Lists every configured model alias across all providers.

On success, `data.items` is an array of `{ provider, model, display_name?, max_context_size, capabilities?, support_efforts?, default_effort? }`: `model` is the alias id (`provider_id/model` for provider-managed aliases, otherwise the bare key), `provider` the owning provider id, `max_context_size` the context window in tokens, and `capabilities` / `support_efforts` / `default_effort` describe capability flags and Thinking-mode effort support.

#### `POST /api/v1/models/{model_id}:set_default`

Sets the global `default_model` to an existing alias. `model_id` is the exact configured alias key — for a bare key like `turbo` the call is `POST /api/v1/models/turbo:set_default`; URL-encode the id when it contains `/`, as in `POST /api/v1/models/my-provider%2Fkimi-for-coding:set_default`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `model_id` | path | string | **Required.** The exact configured model alias key; URL-encode it when it contains `/` |

On success, `data` is `{ default_model, model }` — the alias now in effect and its catalog item (same shape as a `GET /api/v1/models` item).

- `40001`: malformed or unsupported action suffix in the path
- `40413`: no model alias with that id

#### `GET /api/v1/providers`

Lists every configured provider with its credential and model-discovery state, without revealing any key. This is the provider item shape referenced by the other provider endpoints.

On success, `data.items` is an array of:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Provider id |
| `type` | string | Wire protocol: `kimi` / `openai` / `openai_responses` / `anthropic` / `google-genai` / `vertexai` |
| `base_url` | string | API base URL, when set |
| `default_model` | string | The provider's default model alias, when set |
| `has_api_key` | boolean | Whether a credential is stored |
| `status` | string | `connected` when an API key or cached OAuth token exists, `unconfigured` otherwise (`error` is reserved in the schema) |
| `models` | array | The provider's model alias ids |

#### `POST /api/v1/providers`

Creates a provider and its model aliases in one save; the reply is HTTP 201 with the standard envelope. When no global `default_model` is configured at all (fresh setup), it is seeded with the new provider's `default_model` (or first model); an existing default is never modified.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | body | string | **Required.** Provider id — letters, digits, `-`, `_`, and spaces; must start with a letter or digit |
| `type` | body | string | **Required.** Wire protocol: `kimi` / `openai` / `openai_responses` / `anthropic` / `google-genai` / `vertexai` |
| `api_key` | body | string | API key, stored in `config.toml` |
| `base_url` | body | string | API base URL; must not contain an environment variable placeholder (`${...}`) |
| `default_model` | body | string | The provider's default model; must be one of `models[].model` |
| `models` | body | array | **Required.** At least one entry, no duplicate `model` values; entry shape below |

Each `models[]` entry declares one alias whose id becomes `id/model`:

| Field | Type | Description |
| --- | --- | --- |
| `model` | string | **Required.** Upstream model name |
| `max_context_size` | integer | **Required.** Context window in tokens, ≥ 1 |
| `display_name` | string | Display name |
| `capabilities` | array | Capability flags such as `thinking` or `image_in` |
| `max_output_size` | integer | Max output tokens, ≥ 1 |
| `support_efforts` | array | Supported Thinking-mode effort levels |
| `adaptive_thinking` | boolean | Adaptive thinking toggle |

On success, `data` is the created provider item (same shape as a `GET /api/v1/providers` item).

- `40921`: a provider with this `id` already exists

#### `GET /api/v1/providers/{provider_id}`

Reads one provider. Unlike the list route, the response reveals the stored `api_key` when one is set, so a local edit form can prefill — keep this in mind when exposing the port.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider_id` | path | string | **Required.** Provider id |

On success, `data` is the provider item plus `api_key` when a key is stored.

- `40412`: provider not found

#### `PUT /api/v1/providers/{provider_id}`

Replaces a provider in one save: `type`, `base_url`, and the model list are rewritten, and the provider's aliases are rebuilt from `models` — aliases no longer listed disappear from `config.toml`, while other providers' aliases are untouched. `api_key` is tri-state: omitted keeps the stored key, `""` clears it, any other value replaces it. Beyond the `new_id` rename migration, the global default pointers are never modified.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider_id` | path | string | **Required.** Current provider id |
| `new_id` | body | string | Rename the provider; the providers key, model aliases, `default_provider`, a `default_model` pointing at an old alias, and the subagent secondary-model pool all migrate. Same id rules as `POST /api/v1/providers` |
| `type` | body | string | **Required.** Wire protocol: `kimi` / `openai` / `openai_responses` / `anthropic` / `google-genai` / `vertexai` |
| `api_key` | body | string | Tri-state, see above |
| `base_url` | body | string | API base URL; must not contain an environment variable placeholder (`${...}`) |
| `default_model` | body | string | The provider's default model; must be one of `models[].model` |
| `models` | body | array | **Required.** At least one entry, no duplicate `model` values; same entry shape as `POST /api/v1/providers` |

On success, `data` is `{ provider }` with the saved provider item.

- `40001`: a renamed alias id would collide with another provider's alias
- `40003`: provider is OAuth-managed — log out via `POST /api/v1/oauth/logout` instead
- `40412`: provider not found
- `40921`: `new_id` is already taken

#### `DELETE /api/v1/providers/{provider_id}`

Deletes a provider and all of its model aliases; the subagent secondary-model pool is cascaded. The global `default_provider` / `default_model` pointers are left untouched, even when they point at the deleted provider — they are the user's settings, not this endpoint's to garbage-collect.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider_id` | path | string | **Required.** Provider id |

On success the server answers 204 with no body — the status line itself reports the delete (see [Response envelope](#response-envelope)).

- `40003`: provider is OAuth-managed — log out via `POST /api/v1/oauth/logout` instead
- `40412`: provider not found

#### `POST /api/v1/providers/{provider_id}:refresh`

Re-discovers one provider's model metadata from its upstream source and rewrites the provider's aliases. Providers with a static model source are reported `unchanged` without any network call. When at least one provider's aliases change, the server broadcasts the global `event.model_catalog.changed` event.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `provider_id` | path | string | **Required.** Provider id |

On success, `data` is a refresh report: `changed` is an array of `{ provider_id, provider_name, added, removed }` (added/removed alias counts), `unchanged` is an array of provider ids with no diff, and `failed` is an array of `{ provider, reason }`.

- `40001`: malformed or unsupported action suffix in the path
- `40412`: provider not found

#### `POST /api/v1/providers:refresh`

Refreshes model metadata for every provider. The body is optional and ignored.

On success, `data` is the same refresh report as `POST /api/v1/providers/{provider_id}:refresh` (`changed` / `unchanged` / `failed`).

#### `POST /api/v1/providers:refresh_oauth`

Same refresh as `POST /api/v1/providers:refresh`, limited to OAuth-backed providers. The body is optional and ignored.

On success, `data` is the refresh report (`changed` / `unchanged` / `failed`).

#### `POST /api/v1/providers:import_catalog`

Imports one models.dev directory entry as a configured provider; the reply is HTTP 201 with the standard envelope. The wire protocol and endpoint come from the catalog resolution, and every catalogued model is written as an alias. Importing an id that already exists is a refresh — the provider entry and its aliases are rewritten from the catalog, and an omitted `api_key` keeps the stored key. The global default pointers are never modified, except that `default_model` is seeded from the first imported model when none is configured at all.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `catalog_id` | body | string | **Required.** Directory entry id from `GET /api/v1/catalog/providers` |
| `id` | body | string | Override the catalog id as the local provider id. Same id rules as `POST /api/v1/providers` |
| `api_key` | body | string | API key for the imported provider |
| `base_url` | body | string | Override the catalog-resolved endpoint; required when the entry's `needs_base_url` is `true` |

On success, `data` is `{ provider, models_imported }` — the provider item and the number of aliases written.

- `40001`: `catalog_id` missing or another body validation failure
- `40003`: the target provider exists and is OAuth-managed
- `40004`: the entry cannot be imported (rejected, requires a `base_url`, has no importable models, or its id is unusable as a provider id)
- `40417`: no directory entry with that `catalog_id`
- `50004`: the models.dev directory is unavailable

#### `POST /api/v1/providers:import_registry`

Imports a models.dev-shaped private registry — an `api.json` URL plus an optional Bearer key — as configured providers; the reply is HTTP 201 with the standard envelope. Every listed provider is written with a `source` record so scheduled refreshes rediscover it. Re-importing the same URL removes providers that disappeared upstream — the URL is the registry's stable identity, so rotating the key is safe. The global default pointers follow the same rules as `:import_catalog`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `url` | body | string | **Required.** URL of the registry's `api.json` |
| `api_key` | body | string | Bearer key for the registry; when omitted, the key from the previous import of the same URL is reused |

On success, `data` is `{ providers, models_imported }` — an array of provider items and the total number of aliases written.

- `40001`: `url` missing or another body validation failure
- `40003`: a listed provider exists and is OAuth-managed
- `40005`: the registry cannot be fetched or parsed, or lists no importable providers

#### `GET /api/v1/catalog/providers`

Browses the models.dev directory, proxied by the server with a 10-minute in-memory cache and a built-in snapshot fallback. Items keep the upstream directory order. Entries the server cannot import carry `rejected: true` with a machine-readable `reject_reason`; entries with `needs_base_url: true` require a base URL at import time.

On success, `data.items` is an array of `{ id, name, wire_type, guessed, needs_base_url, rejected, reject_reason, env_key, models }`: `wire_type` is the resolved protocol (nullable, same enum as a provider `type`), `guessed` marks a heuristic resolution, `env_key` is the upstream's conventional API-key environment variable (nullable), and `models` is an array of `{ id, name?, max_context_size, capabilities?, reasoning }`.

- `50004`: the directory is unavailable (both the live fetch and the built-in snapshot failed)

#### `GET /api/v1/catalog/providers/{catalog_id}`

Reads one models.dev directory entry by catalog id — the same item shape as `GET /api/v1/catalog/providers`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `catalog_id` | path | string | **Required.** Directory entry id |

On success, `data` is the directory entry (same shape as a `GET /api/v1/catalog/providers` item).

- `40417`: no directory entry with that `catalog_id`
- `50004`: the directory is unavailable

### Sessions

These endpoints create, list, and inspect sessions, drive session-level actions (fork, compact, undo, and friends), and read per-session rollups. Most of them return a session in the wire shape documented once under [The session object](#the-session-object); non-CRUD operations use the `:{action}` convention described above.

| Method and path | Description |
| --- | --- |
| `POST /api/v1/sessions` | Create a session (requires `workspace_id` or `metadata.cwd`) |
| `GET /api/v1/sessions` | List sessions; cursor pagination with filters such as `busy` and `archived_only` |
| `GET /api/v1/sessions/{session_id}` | Read one session |
| `GET /api/v1/sessions/{session_id}/profile` | Read the session profile |
| `POST /api/v1/sessions/{session_id}/profile` | Update title, metadata, agent config |
| `POST /api/v1/sessions/{session_id}/title/generate` | Generate a title via the managed `chat_title` tool |
| `POST /api/v1/sessions/{session_id}:{action}` | Session actions: `fork` / `compact` / `undo` / `abort` / `btw` / `archive` / `restore` |
| `GET /api/v1/sessions/{session_id}/children` | List child sessions |
| `POST /api/v1/sessions/{session_id}/children` | Create a child session (fork with a tag) |
| `GET /api/v1/sessions/{session_id}/status` | Realtime status rollup |
| `GET /api/v1/sessions/{session_id}/goal` | Current goal snapshot (`null` when none) |
| `GET /api/v1/sessions/{session_id}/warnings` | Session-level warnings |
| `GET /api/v1/sessions/{session_id}/runtime` | Read the main agent's runtime binding |
| `POST /api/v1/sessions/{session_id}/runtime` | Switch the main agent's runtime binding |
| `POST /api/v1/sessions/{session_id}/export` | Export the session with diagnostics (zip stream, not enveloped) |
| `GET /api/v1/sessions/{session_id}/snapshot` | Full snapshot for client rebuilds (with `as_of_seq` and `epoch`) |
| `GET /api/v1/sessions/{session_id}/media/{file_id}` | Download prompt media by file id (binary) |

#### The session object

Every endpoint that returns a session uses this wire shape. The live facts (`busy`, `main_turn_active`, `pending_interaction`, `last_turn_reason`) are resolved from the session's activity aggregate: a session that is not loaded in this server process (a cold session) always reports not-busy with no pending interaction. A few fields are placeholders in the current projection — this is noted per field.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Session id (`session_...`) |
| `workspace_id` | string | Owning workspace id |
| `title` | string | Session title; `""` when untitled |
| `created_at` / `updated_at` | string | Creation and last-update times, ISO 8601 |
| `archived` | boolean | Whether the session is archived (hidden from the default session list) |
| `archived_at` | string | Archive time, ISO 8601; present only when archived |
| `busy` | boolean | Any agent has an active turn or background task |
| `main_turn_active` | boolean | The main agent has an active turn |
| `pending_interaction` | string | `none` / `approval` / `question` — an unanswered interaction is waiting |
| `last_turn_reason` | string | Main agent's latest turn outcome: `completed` / `cancelled` / `failed` |
| `last_prompt` | string | Most recent user prompt text, when present |
| `metadata` | object | Custom metadata; always carries `cwd` (the session's working directory) |
| `agent_config` | object | Projected as `{ model }`; `model` is `""` in most responses and only filled with the live model by `GET /api/v1/sessions/{session_id}/snapshot` |
| `usage` | object | Token rollup `{ input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, context_tokens, context_limit?, total_cost_usd?, turn_count? }`; all zeros outside the snapshot endpoint |
| `permission_rules` | array | Session permission rules; currently always `[]` |
| `message_count` | integer | Message count; currently always `0` |
| `last_seq` | integer | Last event sequence number; currently always `0` |

#### `POST /api/v1/sessions`

Creates a session and returns it. The target directory comes from `workspace_id` (an already-registered workspace) or from `metadata.cwd` (the workspace is registered on first use); passing both requires them to agree. Creation broadcasts the global `event.session.created` event.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | body | string | **Required** when `metadata.cwd` is absent. Registered workspace id; the session is created at that workspace's root |
| `metadata` | body | object | Custom metadata. `metadata.cwd` is the working directory and is **required** when `workspace_id` is absent; with both given, it must equal the workspace root |
| `title` | body | string | Initial title (at least 1 character); the session is untitled otherwise |
| `agent_config` | body | object | Accepted by the schema but currently not applied — set the model and modes through `POST /api/v1/sessions/{session_id}/profile` |

On success, `data` is [the session object](#the-session-object) of the new session.

- `40001`: neither `workspace_id` nor `metadata.cwd` given, or `metadata.cwd` does not match the workspace root (`details` lists the field)
- `40409`: the working directory does not exist or is not a directory
- `40410`: no registered workspace with that `workspace_id`

#### `GET /api/v1/sessions`

Lists sessions across workspaces, newest `updated_at` first. Cursor pagination follows [Pagination](#pagination), with one twist: without `page_size` (and without `archived_only`) the response is a single unpaginated window whose `has_more` is always `false`, so pass `page_size` to actually page.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `before_id` | query | string | Only sessions older than this id; mutually exclusive with `after_id` |
| `after_id` | query | string | Only sessions newer than this id; mutually exclusive with `before_id` |
| `page_size` | query | integer | 1–100. When paging applies, the default is `20`; see the note above for the unpaginated default behavior |
| `busy` | query | boolean | Keep only busy (or only idle) sessions |
| `include_archive` | query | boolean | Include archived sessions alongside live ones. Default `false` |
| `archived_only` | query | boolean | Keep only archived sessions; mutually exclusive with `include_archive`; implies cursor paging even without `page_size` |
| `exclude_empty` | query | boolean | Drop sessions that carry no user prompt |
| `workspace_id` | query | string | Restrict to one workspace (aliases are resolved) |

On success, `data` is `{ items, has_more }` where each item is [the session object](#the-session-object).

- `40001`: validation failure — for example `before_id` combined with `after_id`, or `archived_only` combined with `include_archive`
- `40410`: unknown `workspace_id`

#### `GET /api/v1/sessions/{session_id}`

Reads one session from the index. Live facts are included when the session is loaded in this process; a cold session reports not-busy with its last persisted turn outcome.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is [the session object](#the-session-object).

- `40401`: session not found, or its workspace can no longer be resolved

#### `GET /api/v1/sessions/{session_id}/profile`

Reads the session profile — the same wire payload as `GET /api/v1/sessions/{session_id}`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is [the session object](#the-session-object).

- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/profile`

Updates the session's profile: title, custom metadata, and the main agent's config. A title set here becomes a custom title, which wins over generated titles; setting one broadcasts the global `session.meta.updated` event.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `title` | body | string | New title (at least 1 character); becomes a custom title |
| `metadata` | body | object | Keys merged into the session's custom metadata |
| `agent_config` | body | object | Partial main-agent config; fields below, all optional |

Each `agent_config` field is applied immediately to the main agent:

| Field | Type | Description |
| --- | --- | --- |
| `model` | string | Model alias id; an empty string is ignored |
| `thinking` | string | Thinking-mode effort level |
| `permission_mode` | string | `manual` / `yolo` / `auto` |
| `plan_mode` | boolean | Enter or exit Plan mode |
| `swarm_mode` | boolean | Enter or exit swarm mode |
| `goal_objective` | string | Create a goal with this objective |
| `goal_control` | string | `pause` / `resume` / `cancel` the current goal |

The schema also accepts `system_prompt`, `tools`, `mcp_servers` inside `agent_config`, and a top-level `permission_rules` array, but the update route currently does not apply them.

On success, `data` is the updated [session object](#the-session-object).

- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/title/generate`

Generates a title from the session's prompts through the managed provider's `chat_title` tool and applies it, broadcasting `session.meta.updated`. Generation requires the managed OAuth login; without `force`, a session that already has a custom or generated title is reported unavailable instead of being overwritten.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `force` | body | boolean | Regenerate even when a custom or generated title exists. Default `false` |
| `source` | body | string | Title input: `user_prompts` (default) / `first_turn` / `digest` |

On success, `data` is `{ title }` — the title now applied to the session.

- `40401`: session not found
- `40923`: generation unavailable — the flag is off, there is no managed OAuth login or no prompt content yet, an existing title without `force`, or the backend request failed

#### `POST /api/v1/sessions/{session_id}:{action}`

Session actions are dispatched through one route: the path tail is parsed as `{session_id}:{action}`, the body is validated against the action's schema, and a missing or unknown action fails `40001` (`unsupported action: ...`). Every action resolves the session first, so all of them can return `40401` for an unknown session. The supported actions are documented one by one below.

#### `POST /api/v1/sessions/{session_id}:fork`

Copies the session — its transcript, agent state, and files — into a new session in the same workspace, and broadcasts `event.session.created`. Forking is rejected while any of the session's agents has an active turn.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `title` | body | string | Title for the fork (at least 1 character). Default `Fork: <source title>` |
| `metadata` | body | object | Custom metadata for the fork |

On success, `data` is [the session object](#the-session-object) of the new session.

- `40901`: the session has an active turn and cannot be forked

#### `POST /api/v1/sessions/{session_id}:compact`

Starts a manual full compaction of the main agent's context. The call returns immediately; progress and completion are delivered as the `compaction.*` WebSocket events.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `instruction` | body | string | Extra guidance for the compaction summary; a blank value is ignored |

On success, `data` is an empty object.

- `40910`: a turn or another context change is active, or the history has nothing to compact

#### `POST /api/v1/sessions/{session_id}:undo`

Rewinds the main agent's conversation by `count` turns and reconciles the derived session state (including the session's `last_prompt`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `count` | body | integer | Number of turns to undo; positive integer. Default `1` |
| `page_size` | body | integer | Size of the returned history window, 1–100. Default `50` |

On success, `data` is `{ messages, status }`: `messages` is a `{ items, has_more }` page of the remaining context messages, newest first, and `status` is the same rollup as `GET /api/v1/sessions/{session_id}/status`.

- `40901`: a turn is active or a compaction is running — wait for it to finish, then retry
- `40911`: that many turns cannot be undone (a compaction boundary or lost checkpoints); `data` carries `{ reason, requestedCount, undoableCount }`

#### `POST /api/v1/sessions/{session_id}:abort`

Cancels the main agent's running turn — the programmatic equivalent of the user aborting the turn in the TUI.

On success, `data` is `{ aborted: true }`.

#### `POST /api/v1/sessions/{session_id}:btw`

Starts a "by the way" side conversation: forks the main agent into a child agent whose tool calls are limited to the read-only tools `Read`, `Grep`, and `Glob`, so quick side questions run in isolation without touching the working context. Requires a usable model configuration.

On success, `data` is `{ agent_id }` — the id of the new child agent.

#### `POST /api/v1/sessions/{session_id}:archive`

Marks the session archived: it disappears from the default session list (it stays listed with `include_archive` or `archived_only`), and the server broadcasts the global `event.session.archived` event.

On success, `data` is `{ archived: true }`.

#### `POST /api/v1/sessions/{session_id}:restore`

Un-archives the session and resumes it.

On success, `data` is [the session object](#the-session-object) with `archived: false`.

#### `GET /api/v1/sessions/{session_id}/children`

Lists the session's children — the sessions created through `POST /api/v1/sessions/{session_id}/children`. Cursor pagination follows [Pagination](#pagination).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `before_id` | query | string | Only children older than this id; mutually exclusive with `after_id` |
| `after_id` | query | string | Only children newer than this id; mutually exclusive with `before_id` |
| `page_size` | query | integer | 1–100. Default `100` |
| `busy` | query | boolean | Keep only busy (or only idle) children |

On success, `data` is `{ items, has_more }` where each item is [the session object](#the-session-object).

- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/children`

Creates a child session: a fork of this session recorded as its child, so it shows up under `GET /api/v1/sessions/{session_id}/children`. The same active-turn restriction as `:fork` applies.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `title` | body | string | Title for the child (at least 1 character). Default `Child: <source title>` |
| `metadata` | body | object | Custom metadata for the child |

On success, `data` is [the session object](#the-session-object) of the new session, and the server broadcasts `event.session.created`.

- `40901`: the session has an active turn and cannot be forked

#### `GET /api/v1/sessions/{session_id}/status`

Realtime status rollup of the main agent; reading it resumes the session if it is cold.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ busy, model?, thinking_level, permission, plan_mode, swarm_mode, context_tokens, max_context_tokens?, context_usage? }`: `busy` reports an active turn, `model` / `thinking_level` / `permission` are the effective agent settings, `plan_mode` / `swarm_mode` are the mode flags, and `context_tokens` with `max_context_tokens` and `context_usage` (0–1) describe context-window consumption.

- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/goal`

Reads the session's current goal snapshot, or `null` when no goal is active. Note that this payload uses camelCase keys, unlike most of this API.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `null` or `{ goalId, objective, completionCriterion?, status, turnsUsed, tokensUsed, wallClockMs, budget, terminalReason? }`, where `status` is `active` / `paused` / `blocked` / `complete` and `budget` reports the token, turn, and wall-clock budgets together with the remaining amounts and per-budget reached flags (each nullable when no such budget is set).

- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/warnings`

Reads session-level warnings. The current producer is the oversized `AGENTS.md` check (`agents-md-oversized`), so the list is empty for most sessions.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ warnings }`, each entry `{ code, message, severity }` with `severity` one of `info` / `warning` / `error`.

- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/runtime`

Reads the main agent's runtime binding — which runtime the session's agent loop runs on.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ workspace_id, runtime_id }`.

- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/runtime`

Switches the main agent's runtime binding.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `runtime_id` | body | string | **Required.** Target runtime id |

On success, `data` is the new binding `{ workspace_id, runtime_id }`.

- `40420`: no runtime with that `runtime_id`
- `40926`: the runtime exists but is unavailable

#### `POST /api/v1/sessions/{session_id}/export`

Exports the session together with diagnostic logs as a zip attachment (`kimi-session-<id>.zip`). The response is a binary stream, not a JSON envelope — capabilities and failure semantics are covered under [Binary and streaming endpoints](#binary-and-streaming-endpoints).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `web_log` | body | string | Client log text to include in the archive, at most 256 KB UTF-8 |
| `desktop` | body | boolean | Also include the desktop host's log. Default `false` |

#### `GET /api/v1/sessions/{session_id}/snapshot`

Assembles an atomic snapshot for rebuilding a client after a resync: the session, recent messages, the in-flight turn, live subagents, and pending interactions, all stamped with the `as_of_seq` watermark and `epoch` used to resubscribe — see [Reconnect and recovery](#reconnect-and-recovery). Unlike the plain session endpoints, the embedded session carries the live `agent_config.model` and real `usage` totals.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ as_of_seq, epoch, session, messages, in_flight_turn, subagents?, pending_approvals, pending_questions }`: `session` is [the session object](#the-session-object), `messages` is the newest 100 messages as `{ items, has_more }`, `in_flight_turn` is the partially streamed turn (`null` when idle, with `current_prompt_id` when known), `subagents` lists live subagent tasks, and `pending_approvals` / `pending_questions` carry the unanswered interactions.

- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/media/{file_id}`

Downloads a prompt media file (an image or other attachment referenced by the session's prompts) by file id; an id not yet committed to the session falls back to the staged uploads. The response is binary with `Range` support (206 on ranged requests) — see [Binary and streaming endpoints](#binary-and-streaming-endpoints) for the shared conventions; unlike the enveloped endpoints there, a missing session or file answers with a real 404 status carrying an envelope body.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `file_id` | path | string | **Required.** Media file id |

### Messages and transcript

The `messages` endpoints page the main agent's flattened message history, while the `transcript` endpoints serve the structured per-agent transcript — turns, tasks, interactions, attachments — that the WebSocket [Transcript protocol](#transcript-protocol) streams live. Use these endpoints for history paging and catch-up, and the WebSocket subscription for the live tail.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/sessions/{session_id}/messages` | Page messages (`before_id` / `after_id` / `role`) |
| `GET /api/v1/sessions/{session_id}/messages/{message_id}` | Read one message |
| `GET /api/v1/sessions/{session_id}/transcript` | Turn-paged transcript (requires `agent_id`); global state rides along unpaginated |
| `GET /api/v1/sessions/{session_id}/transcript/ops` | Op-batch catch-up (`since_seq`); `complete: false` means a full refresh is needed |
| `GET /api/v1/sessions/{session_id}/transcript/user-messages` | Turn-opening user inputs, unpaginated |
| `GET /api/v1/sessions/{session_id}/transcript/plan` | ExitPlanMode plan content, path, and review outcome |

#### `GET /api/v1/sessions/{session_id}/messages`

Pages the main agent's message history — the flattened context transcript shared with the session snapshot — newest first. Cursor pagination follows [Pagination](#pagination); reading the history resumes the session when it is cold.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `before_id` | query | string | Only messages older than this message id; mutually exclusive with `after_id` |
| `after_id` | query | string | Only messages newer than this message id; mutually exclusive with `before_id` |
| `page_size` | query | integer | 1–100. Default `50` |
| `role` | query | string | Keep only one role: `user` / `assistant` / `tool` / `system`. The filter applies after the page is sliced, so a filtered page can hold fewer than `page_size` items while `has_more` is still `true` — keep paging until `has_more` is `false` |

On success, `data` is `{ items, has_more }` where each item is a message object `{ id, session_id, role, content, created_at, prompt_id?, parent_message_id?, metadata? }`; `content` is an array of content parts in the wire format documented under [Prompts](#prompts) (`text`, `tool_use`, `tool_result`, `image`, `video`, `file`, `thinking`).

- `40001`: validation failure — for example `before_id` combined with `after_id`
- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/messages/{message_id}`

Reads one message from the same history by id.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `message_id` | path | string | **Required.** Message id |

On success, `data` is the message object in the item shape documented under `GET /api/v1/sessions/{session_id}/messages` above.

- `40401`: session not found
- `40403`: no message with that id in this session

#### `GET /api/v1/sessions/{session_id}/transcript`

Returns one page of an agent's structured transcript: turns (with their steps and frames) plus the markers and task references between them. Live sessions answer from the in-memory store (the requested agent's persisted history is backfilled first); cold sessions rebuild the agent from the persisted wire records. This is the history half of the transcript surface — the live streaming half is the [Transcript protocol](#transcript-protocol) subscription.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `agent_id` | query | string | **Required.** Agent whose transcript to read; must be a plain agent id (letters, digits, `.`, `_`, `-` — no path separators) |
| `before_turn` | query | string | Only turns older than this turn id; mutually exclusive with `after_turn` |
| `after_turn` | query | string | Only turns newer than this turn id; mutually exclusive with `before_turn` |
| `page_size` | query | integer | 1–100 turns. Default `20` |

The page unit is the turn: without a cursor the newest page is returned, and `has_more` reports that older turns remain. On success, `data` is `{ agent_id, items, has_more, tasks, interactions, attachments, todos, meta, agents, pending_interactions, seq? }` — `items` is the paged turn slice, `tasks` / `interactions` / `attachments` / `todos` / `meta` / `agents` / `pending_interactions` are global agent state that ships unpaginated with every response, and `seq` is the agent's op-batch watermark for resuming the stream (live sessions only).

- `40001`: validation failure — `before_turn` combined with `after_turn`, or a non-plain `agent_id`
- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/transcript/ops`

Serves point-to-point catch-up from the server's op journal: the journaled op batches with `seq > since_seq` for one agent, oldest first. It is the REST counterpart of the `transcript_since` resume cursor described in [Transcript protocol](#transcript-protocol) and shares the same bounded journal, so the same fallback rule applies.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `agent_id` | query | string | **Required.** Agent id (plain id, same constraint as the transcript endpoint) |
| `since_seq` | query | integer | **Required.** The caller's last applied op-batch seq, minimum `0`; batches above it are returned |

On success, `data` is `{ agent_id, batches, latest_seq, complete }`, each batch `{ seq, ops }`. `complete: true` means every batch up to `latest_seq` is present; `complete: false` means the journal no longer reaches back to `since_seq` (or the session is not live at all), and the caller must fall back to a full `GET .../transcript` refresh.

- `40001`: validation failure
- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/transcript/user-messages`

Lists every turn-opening input of the session, grouped per agent and unpaginated: real user text, user-slash skill and plugin commands, and cron prompts — distinguishable via `origin` — plus attachment-only prompts projected with an empty `prompt`. Attachment entities referenced by the listed messages ride along (metadata only, never bytes).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `agent_id` | query | string | Read one agent only (plain id). Default reads every rostered agent |

On success, `data` is `{ agents }` where each entry is `{ agent_id, messages, attachments }`; a message is `{ turn_id, ordinal, state, origin, prompt, attachment_ids?, started_at? }` with `state` the turn state (`queued` / `running` / `completed` / `failed` / `cancelled`).

- `40001`: validation failure — a non-plain `agent_id`
- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/transcript/plan`

Reads the plan information of an agent's `ExitPlanMode` tool calls — plan content, plan file path, offered options, and the review outcome — in timeline order. Content is projected from the first available fact: the linked approval interaction (interactive reviews), the live tool frame's display (auto mode), or the tool result output text; each entry records which one in `source`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `agent_id` | query | string | **Required.** Agent id (plain id) |
| `tool_call_id` | query | string | Narrow the read to one `ExitPlanMode` call; absent lists every call with recoverable plan content |

On success, `data` is `{ agent_id, plans }` where each plan is `{ tool_call_id, turn_id, source, plan, path?, options?, review? }`: `source` is `interaction` / `display` / `output`, `options` are the review choices as `{ label, description? }`, and `review` (present only for interactive reviews) is `{ state, selected_option?, feedback? }` with `state` one of `pending` / `approved` / `rejected` / `cancelled`.

- `40001`: validation failure
- `40401`: session not found
- `40416`: `tool_call_id` given, but no `ExitPlanMode` call with that id exists

### Prompts

A prompt is one unit of user input: submitting one enqueues it on the session's main agent (or a named agent), a queued prompt can be steered into the active turn, and a running prompt can be aborted. Turn progress itself streams over the WebSocket [events](#events), not these endpoints.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/sessions/{session_id}/prompts` | Active and queued prompts |
| `POST /api/v1/sessions/{session_id}/prompts` | Submit a prompt (content-part array, optional model / permission-mode overrides) |
| `POST /api/v1/sessions/{session_id}/prompts:steer` | Steer queued prompts into the active turn |
| `POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:abort` | Abort a running prompt |
| `POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:steer` | Steer one queued prompt |

#### `GET /api/v1/sessions/{session_id}/prompts`

Reads the main agent's prompt queue snapshot.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ active, queued }`: `active` is the running prompt (`null` when idle) and `queued` lists the pending prompts in order. A prompt is `{ prompt_id, user_message_id, status, content, created_at }` with `status` one of `running` / `queued` / `blocked` and `content` in the content-part format accepted by `POST /api/v1/sessions/{session_id}/prompts`.

- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/prompts`

Submits a user prompt to the session. Media references are validated first, then the optional overrides are applied to the target agent — `profile` (bound together with `model` / `thinking`), then `model`, `thinking`, `permission_mode`, and `disabled_tools` — and the prompt is enqueued; the response returns as soon as the prompt is accepted, without waiting for the turn. With `skills`, the prompt runs as a bundled skill activation instead of a plain user prompt.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `content` | body | array | **Required.** Non-empty array of content parts; variants below |
| `agent_id` | body | string | Target agent. Default the main agent |
| `prompt_id` | body | string | Client-chosen prompt id for idempotent submission; an id already reserved by an in-flight prompt fails `40927`, one that has already completed fails `40903`. Cannot be combined with `skills` |
| `skills` | body | array | Bundled skill activations, at least 1 entry of `{ name, args? }`; every skill must exist and be user-activatable |
| `profile` | body | string | Agent profile to bind before submitting |
| `model` | body | string | Model alias to switch the agent to |
| `thinking` | body | string | Thinking-mode effort level |
| `permission_mode` | body | string | `manual` / `yolo` / `auto` |
| `disabled_tools` | body | array | Tool names to disable for the session |

The schema also accepts `metadata`, `plan_mode`, `swarm_mode`, `goal_objective`, and `goal_control`, but the submit route currently does not apply them. Each `content` part is an object discriminated by `type`:

| Part | Fields | Description |
| --- | --- | --- |
| `text` | `text` | Plain text |
| `image` / `video` | `source` | Media input; `source` is one of `{ kind: "url", url, id? }`, `{ kind: "base64", media_type, data }`, `{ kind: "file", file_id }` (an upload from `POST /api/v1/files`), or `{ kind: "session_media", file_id }` (media already committed to this session) |
| `file` | `file_id`, `name`, `media_type`, `size` | A file attachment uploaded through `POST /api/v1/files` |

The schema also accepts the `tool_use`, `tool_result`, and `thinking` parts of the shared message format, but they are not meaningful in a user prompt. Unknown or mis-kinded `file_id` references are rejected before the prompt is created and before any override is applied.

On success, `data` is the accepted prompt `{ prompt_id, user_message_id, status, content, created_at }`.

- `40001`: validation failure — for example `prompt_id` combined with `skills`, or an unknown `profile`
- `40110`: no provider configured yet — finish login first
- `40111`: the resolved provider has no credential (`details.provider_id`)
- `40112`: the provider's credential was rejected (`details.provider_id`)
- `40113`: the model could not be resolved (`details.model_id` / `details.provider_id` when known)
- `40401`: session not found
- `40407`: a referenced `file_id` does not exist (or does not match the part's media kind)
- `40415`: a `skills` entry names an unknown skill
- `40903`: `prompt_id` belongs to an already-completed prompt; `data` carries `{ aborted: false }`
- `40912`: the skill exists but cannot be activated by the user
- `40927`: `prompt_id` is already reserved by an in-flight prompt

#### `POST /api/v1/sessions/{session_id}/prompts:steer`

Steers queued prompts into the active turn, so the running turn consumes them immediately instead of finishing first.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `prompt_ids` | body | array | **Required.** Non-empty array of queued prompt ids |

On success, `data` is `{ steered: true, prompt_ids }`.

- `40001`: validation failure
- `40401`: session not found
- `40402`: a listed prompt id is not in the queue

#### `POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:abort`

Aborts a running prompt. This endpoint and `:steer` below dispatch through one route, `POST /api/v1/sessions/{session_id}/prompts/{tail}`: the tail is parsed as `{prompt_id}:{action}`, and a missing or unknown action fails `40001` (`unsupported action: ...`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `prompt_id` | path | string | **Required.** Prompt id |

On success, `data` is `{ aborted: true }`.

- `40401`: session not found
- `40402`: no prompt with that id
- `40903`: the prompt already completed; `data` carries `{ aborted: false }`

#### `POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:steer`

Steers one queued prompt into the active turn — the single-prompt form of `POST /api/v1/sessions/{session_id}/prompts:steer`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `prompt_id` | path | string | **Required.** Queued prompt id |

On success, `data` is `{ steered: true, prompt_ids: [prompt_id] }`.

- `40401`: session not found
- `40402`: no queued prompt with that id

### Approvals and questions

Approvals and questions are the session's two pending-interaction kinds: an approval asks permission for a tool call, a question asks for structured input with labeled options. These endpoints list and resolve them; new requests arrive over the WebSocket as `event.approval.requested` and `event.question.requested`.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/sessions/{session_id}/approvals` | List pending approval requests (`status=pending` is required) |
| `POST /api/v1/sessions/{session_id}/approvals/{approval_id}` | Resolve an approval |
| `GET /api/v1/sessions/{session_id}/questions` | List pending questions (`status=pending` is required) |
| `POST /api/v1/sessions/{session_id}/questions/{question_id}` | Answer a question |
| `POST /api/v1/sessions/{session_id}/questions/{question_id}:dismiss` | Dismiss a question |

#### `GET /api/v1/sessions/{session_id}/approvals`

Lists the session's pending approval requests — the permission prompts raised by tool calls. Reading the list resumes the session when it is cold.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `status` | query | string | **Required.** Must be `pending` |

On success, `data` is `{ items }` where each item is `{ approval_id, session_id, turn_id?, tool_call_id, tool_name, action, tool_input_display, created_at, expires_at }`: `tool_name` / `action` / `tool_input_display` describe the call waiting for permission, and `expires_at` is 24 hours after `created_at`.

- `40001`: `status` missing or not `pending`
- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/approvals/{approval_id}`

Resolves a pending approval request, letting the waiting tool call proceed (or not).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `approval_id` | path | string | **Required.** Approval request id |
| `decision` | body | string | **Required.** `approved` / `rejected` / `cancelled` |
| `scope` | body | string | With `approved`, `session` (the only value) also remembers the approval rule for the rest of the session |
| `feedback` | body | string | Free-form feedback handed back to the agent |
| `selected_label` | body | string | The label of the chosen option, when the request offered labeled choices (for example a plan review) |

On success, `data` is `{ resolved: true, resolved_at }`.

- `40001`: validation failure
- `40401`: session not found
- `40404`: no pending approval with that id
- `40902`: the approval was already resolved; `data` carries `{ resolved: false }`

#### `GET /api/v1/sessions/{session_id}/questions`

Lists the session's pending questions.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `status` | query | string | **Required.** Must be `pending` |

On success, `data` is `{ items }` where each item is `{ question_id, session_id, turn_id?, tool_call_id?, questions, created_at }`. `questions` holds 1–4 items `{ id, question, header?, body?, options, multi_select?, allow_other?, other_label?, other_description? }`, each with 2–4 `options` of `{ id, label, description? }`; `multi_select` allows several options, `allow_other` a free-text answer.

- `40001`: `status` missing or not `pending`
- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/questions/{question_id}`

Answers a pending question. Both question endpoints dispatch through one route, `POST /api/v1/sessions/{session_id}/questions/{tail}`: a bare question id answers the question, a `{question_id}:dismiss` tail dismisses it, and anything else fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `question_id` | path | string | **Required.** Question id |
| `answers` | body | object | **Required.** Map of question item id (`q_0`, …) to an answer object; variants below |
| `method` | body | string | How the answer was produced: `enter` / `space` / `number_key` / `click` |
| `note` | body | string | Free-form note attached to the response |

Each answer is an object discriminated by `kind`:

| Kind | Fields | Description |
| --- | --- | --- |
| `single` | `option_id` | One chosen option |
| `multi` | `option_ids` | Several chosen options (at least 1) |
| `other` | `text` | A free-text answer |
| `multi_with_other` | `option_ids`, `other_text` | Options plus free text |
| `skipped` | — | The item was skipped |

On success, `data` is `{ resolved: true, resolved_at }`.

- `40001`: validation failure (`details` lists each field)
- `40401`: session not found
- `40405`: no pending question with that id
- `40902`: the question was already resolved; `data` carries `{ resolved: false }`

#### `POST /api/v1/sessions/{session_id}/questions/{question_id}:dismiss`

Dismisses a pending question without answering it.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `question_id` | path | string | **Required.** Question id |

On success the envelope `code` is `40909` (`question dismissed`) rather than `0`, with `data` `{ dismissed: true, dismissed_at }` — clients must special-case this endpoint's success code.

- `40401`: session not found
- `40405`: no pending question with that id
- `40902`: the question was already resolved; `data` carries `{ resolved: false }`

### Background tasks

Background tasks are the session's asynchronous units — background shells, subagents, and long-running tool tasks. The registry is live-only: a session not loaded in this server process reports an empty list.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/sessions/{session_id}/tasks` | List background tasks |
| `GET /api/v1/sessions/{session_id}/tasks/{task_id}` | Read a task (optional output preview) |
| `POST /api/v1/sessions/{session_id}/tasks/{task_id}:cancel` | Cancel a task |
| `POST /api/v1/sessions/{session_id}/tasks/{task_id}:detach` | Move a foreground task to the background |

#### `GET /api/v1/sessions/{session_id}/tasks`

Lists the session's background tasks.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `status` | query | string | Keep only one status: `running` / `completed` / `failed` / `cancelled` |

On success, `data` is `{ items }` where each item is a task object `{ id, session_id, kind, description, status, created_at, started_at?, completed_at?, command?, model?, thinking_effort?, agent_id?, subagent_type?, parent_tool_call_id?, output_preview?, output_bytes? }`. `kind` is `bash` / `subagent` / `tool`; `command` is set for `bash` tasks, the model and agent fields for `subagent` tasks, and the output fields only when a task is read with `with_output`. Timed-out and lost tasks report `failed`; killed tasks report `cancelled`.

- `40001`: validation failure — an unknown `status`
- `40401`: session not found

#### `GET /api/v1/sessions/{session_id}/tasks/{task_id}`

Reads one background task, optionally with a tail of its output.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `task_id` | path | string | **Required.** Task id |
| `with_output` | query | boolean | Include an output tail in the response. Default `false` |
| `output_bytes` | query | integer | Size of the requested output tail in bytes, minimum `0`. Default `32768` |

On success, `data` is the task object documented under `GET /api/v1/sessions/{session_id}/tasks` above; with `with_output=true` and non-empty output, `output_preview` carries the tail text and `output_bytes` its byte length.

- `40001`: validation failure
- `40401`: session not found
- `40406`: no task with that id (a cold session has no live tasks at all)

#### `POST /api/v1/sessions/{session_id}/tasks/{task_id}:cancel`

Cancels a running task. It dispatches through `POST /api/v1/sessions/{session_id}/tasks/{tail}` with `cancel` / `detach` as the supported actions — a bare task id or an unknown action fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `task_id` | path | string | **Required.** Task id |

On success, `data` is `{ cancelled: true }`.

- `40001`: missing or unknown action suffix
- `40401`: session not found
- `40406`: no task with that id
- `40904`: the task already finished; `data` carries `{ cancelled: false }` and `details.current_status` the terminal status

#### `POST /api/v1/sessions/{session_id}/tasks/{task_id}:detach`

Moves a running foreground task to the background without stopping it: the tool call waiting on the task returns immediately with a background-task result, the turn continues, and the task keeps running under the background task registry (its output is persisted, and its completion arrives as a task notification). Already-background or finished tasks are an idempotent no-op. It dispatches through `POST /api/v1/sessions/{session_id}/tasks/{tail}` with `cancel` / `detach` as the supported actions — a bare task id or an unknown action fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `task_id` | path | string | **Required.** Task id |

On success, `data` is `{ detached, status }`: `detached` is `true` when the call moved a running foreground task to the background and `false` for the idempotent no-op; `status` is the task's status after the call.

- `40001`: missing or unknown action suffix
- `40401`: session not found
- `40406`: no task with that id

### Skills, tools, and MCP

These endpoints expose the skill catalogs a session or workspace sees, the effective agent's tool list, and its MCP servers. Skill activation and MCP restart use the `:{action}` convention; activation is the REST analogue of the `/<skill>` slash command.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/sessions/{session_id}/skills` | Per-session skill catalog |
| `GET /api/v1/workspaces/{workspace_id}/skills` | Session-less skill catalog for a workspace |
| `POST /api/v1/sessions/{session_id}/skills/{skill_name}:activate` | Activate a skill (starts a turn) |
| `GET /api/v1/tools` | List tools of the effective agent |
| `GET /api/v1/mcp/servers` | List MCP servers |
| `POST /api/v1/mcp/servers/{mcp_server_id}:restart` | Restart an MCP server |

#### `GET /api/v1/sessions/{session_id}/skills`

Lists the skills available to one session, merged from every source (built-in, plugin, extra, user, project) with the session's precedence applied. Reading the catalog resumes the session when it is cold.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ skills }` where each item is a skill descriptor `{ name, description, path, source, type?, disable_model_invocation? }`: `source` is `project` / `user` / `extra` / `builtin`, `type` classifies the skill (only user-activatable types can be activated), and `disable_model_invocation` hides the skill from the model.

- `40401`: session not found (or not activated)

#### `GET /api/v1/workspaces/{workspace_id}/skills`

Lists the skill catalog a session in this workspace would see, without creating or resuming a session — the same merge of built-in, plugin, extra, user, and project sources computed for the workspace root.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Registered workspace id |

On success, `data` is `{ skills }` with the skill descriptor documented under `GET /api/v1/sessions/{session_id}/skills` above.

- `40410`: workspace not found

#### `POST /api/v1/sessions/{session_id}/skills/{skill_name}:activate`

Activates a skill in the session — the REST analogue of the `/<skill>` slash command — starting a turn on the main agent with the skill's content plus `args` and attachments. The endpoint dispatches through one route, `POST /api/v1/sessions/{session_id}/skills/{tail}`: the tail is parsed as `{skill_name}:{action}`, `activate` is the only action, and a bare name or an unknown action fails `40001` (`unsupported action: ...`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `skill_name` | path | string | **Required.** Name of the skill to activate |
| `args` | body | string | Free-form arguments handed to the skill, like the text after a slash command |
| `attachments` | body | array | Media parts attached to the activation. Image and video parts carry a `source` object whose `kind` is `url` / `base64` / `file` / `session_media` (same shapes as the prompt content parts); file parts carry the top-level `file_id`, `name`, `media_type`, and `size` |

On success, `data` is `{ activated: true, skill_name }`.

- `40001`: validation failure or unsupported action suffix
- `40401`: session not found (or not activated)
- `40407`: a referenced attachment file does not exist
- `40415`: no skill with that name
- `40912`: the skill exists but its type cannot be activated by the user

#### `GET /api/v1/tools`

Lists the tools of the effective agent — the main agent of the session given by `session_id`, or of the most recently created session when the parameter is omitted. When no such session is live in this server process, the list is empty.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | query | string | Session whose main agent to inspect. Default the most recently created session |

On success, `data` is `{ tools }` where each item is `{ name, description, input_schema, source, mcp_server_id?, active? }`: `source` is `builtin` / `skill` / `mcp`, `mcp_server_id` is set on MCP tools (parsed from the `mcp__<server>__<tool>` name), and `active` reports the tool policy's verdict. `input_schema` is currently always `null`.

#### `GET /api/v1/mcp/servers`

Lists the MCP servers configured for the effective agent (the most recently created live session's main agent, as in `GET /api/v1/tools`). With no live session, the list is empty.

On success, `data` is `{ servers }` where each item is `{ id, name, transport, status, last_error?, tool_count }`: `transport` is `stdio` / `http` / `sse`, `status` is `connected` / `connecting` / `disconnected` / `error`, and `last_error` carries the failure text when the server is in `error`.

#### `POST /api/v1/mcp/servers/{mcp_server_id}:restart`

Reconnects one MCP server of the effective agent. The endpoint dispatches through `POST /api/v1/mcp/servers/{tail}` with `restart` as the only action — a bare server id or an unknown action fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `mcp_server_id` | path | string | **Required.** MCP server id (its configured name) |

On success, `data` is `{ restarting: true }`.

- `40001`: missing or unknown action suffix
- `40408`: no MCP server with that id (also reported when no session is live)

### Capabilities and plugins

Capabilities are built-in features with layered readiness — detection steps plus a background install; the current build registers `kimi-cu` (Kimi Computer Use) and `kimi-webbridge` (Kimi Browser Extension). Plugins are installed packages of skills, MCP servers, hooks, and commands. These endpoints report capability status and drive capability installs, and manage the plugin lifecycle from marketplace listing to removal.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/capabilities` | List built-in capabilities with readiness status |
| `GET /api/v1/capabilities/{capability_id}` | Read one capability's status |
| `POST /api/v1/capabilities/{capability_id}:install` | Start a capability install (background; poll GET for progress) |
| `GET /api/v1/plugins` | List installed plugins |
| `POST /api/v1/plugins` | Install a plugin from a local path, zip URL, or GitHub repo |
| `GET /api/v1/plugins/marketplace` | Marketplace catalog merged with live install state |
| `POST /api/v1/plugins/{plugin_id}:{action}` | Plugin actions: `enable` / `disable` / `remove` |

#### `GET /api/v1/capabilities`

Lists every registered capability with its readiness status.

On success, `data` is `{ capabilities }` where each item is a capability status object `{ id, pluginId?, displayName, description, supported, state, version?, steps, install }`. `state` is `ready` (every required detection step `ok`) / `partial` (some step `ok`) / `not_installed` / `unsupported` (not available on this platform/architecture); `steps` lists the detection steps as `{ id, state, detail?, optional? }` with `state` one of `ok` / `missing` / `failed`; `install` is the install progress `{ running, step?, percent?, error?, note? }` with `percent` between 0 and 100.

#### `GET /api/v1/capabilities/{capability_id}`

Reads one capability's readiness status — the polling counterpart of the `:install` action.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `capability_id` | path | string | **Required.** Capability id |

On success, `data` is the capability status object documented under `GET /api/v1/capabilities` above.

- `40418`: no capability with that id

#### `POST /api/v1/capabilities/{capability_id}:install`

Starts installing a capability in the background and returns immediately with the current status (`install.running` is `true`); poll `GET /api/v1/capabilities/{capability_id}` for progress. The endpoint dispatches through `POST /api/v1/capabilities/{tail}` with `install` as the only action — a bare id or an unknown action fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `capability_id` | path | string | **Required.** Capability id |

On success, `data` is the capability status object documented under `GET /api/v1/capabilities` above.

- `40001`: missing or unknown action suffix
- `40418`: no capability with that id
- `40924`: an install of this capability is already running
- `40925`: the capability is not supported on this platform/architecture

#### `GET /api/v1/plugins`

Lists installed plugins.

On success, `data` is `{ plugins }` where each item is `{ id, displayName, version?, enabled, state, skillCount, mcpServerCount, enabledMcpServerCount, hookCount, commandCount, hasErrors, source, originalSource?, github? }`: `state` is `ok` / `error` (load failures also set `hasErrors`), `source` is `local-path` / `zip-url` / `github`, and `github` carries the provenance `{ owner, repo, ref, installedSha? }` with `ref` `{ kind: branch|tag|sha, value }` for GitHub-sourced plugins.

#### `POST /api/v1/plugins`

Installs a plugin and returns its summary.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `source` | body | string | **Required.** Where to install from: an absolute local path, an `http(s)` URL to a zip archive, or a GitHub URL — `https://github.com/<owner>/<repo>`, optionally pinned with `/tree/<branch-or-sha>`, `/releases/tag/<tag>`, or `/commit/<sha>` |

On success, `data` is the plugin summary documented under `GET /api/v1/plugins` above.

- `40001`: validation failure — for example `source` is neither a URL nor an absolute path, or the plugin failed to load
- `40409`: the local path does not exist

#### `GET /api/v1/plugins/marketplace`

Lists the plugin marketplace catalog merged with live install state. The catalog is fetched per request (10-second timeout) from the configured marketplace URL; with the default catalog, built-in capabilities missing from the catalog are merged in as rows (with `capabilityId` set) and rows whose capability is unsupported on this platform are dropped.

On success, `data` is `{ entries }` where each item is `{ id, tier, displayName, description?, homepage?, keywords?, version?, source, installed?, updateAvailable?, capabilityId? }`: `tier` is `official` / `curated` / `third-party`, `installed` is `{ version?, enabled }` when the plugin is installed, and `updateAvailable` marks rows whose catalog version is newer than the installed one. An entry's `source` feeds the `source` field of `POST /api/v1/plugins`.

- `50001`: the marketplace is unreachable or returned an invalid catalog

#### `POST /api/v1/plugins/{plugin_id}:enable`

Enables an installed plugin. Plugin actions dispatch through one route, `POST /api/v1/plugins/{tail}`: the tail is parsed as `{plugin_id}:{action}` with `enable` / `disable` / `remove` as the actions, and a bare id or an unknown action fails `40001` (`unsupported action: ...`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `plugin_id` | path | string | **Required.** Installed plugin id |

On success, `data` is `{ ok: true }`.

- `40001`: missing or unknown action suffix
- `40419`: no installed plugin with that id

#### `POST /api/v1/plugins/{plugin_id}:disable`

Disables an installed plugin without removing it; the dispatch contract matches `:enable` above.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `plugin_id` | path | string | **Required.** Installed plugin id |

On success, `data` is `{ ok: true }`.

- `40001`: missing or unknown action suffix
- `40419`: no installed plugin with that id

#### `POST /api/v1/plugins/{plugin_id}:remove`

Removes an installed plugin; the dispatch contract matches `:enable` above.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `plugin_id` | path | string | **Required.** Installed plugin id |

On success, `data` is `{ ok: true }`.

- `40001`: missing or unknown action suffix
- `40419`: no installed plugin with that id

### Terminals

PTY terminal endpoints; mounted only on loopback binds (a non-loopback bind skips them unless `--allow-remote-terminals` is passed). Terminal input, output, and resize flow over WebSocket `terminal_*` frames — the REST surface manages the terminal lifecycle only.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/sessions/{session_id}/terminals` | List terminals |
| `POST /api/v1/sessions/{session_id}/terminals` | Create a terminal |
| `GET /api/v1/sessions/{session_id}/terminals/{terminal_id}` | Read a terminal |
| `POST /api/v1/sessions/{session_id}/terminals/{terminal_id}:close` | Close a terminal |

#### `GET /api/v1/sessions/{session_id}/terminals`

Lists the session's terminals. Reading the list resumes the session when it is cold.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |

On success, `data` is `{ items }` where each item is a terminal object `{ id, session_id, cwd, shell, cols, rows, status, created_at, exited_at?, exit_code? }`: `status` is `running` / `exited`, and an exited terminal carries `exited_at` plus `exit_code` (`null` when the process reported none, for example after a signal). Scrollback is not part of the object — output replays and streams over the WebSocket.

- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/terminals`

Creates a PTY terminal for the session.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `runtime_id` | body | string | Runtime to spawn in. Default `local` |
| `cwd` | body | string | Working directory, relative to the session workspace (an absolute path fails validation). Default the workspace root |
| `shell` | body | string | Shell executable. Default the runtime's shell |
| `cols` | body | integer | Terminal width, positive. Default `80` |
| `rows` | body | integer | Terminal height, positive. Default `24` |

On success, `data` is the terminal object documented under `GET /api/v1/sessions/{session_id}/terminals` above.

- `40001`: validation failure (`details` lists each field)
- `40401`: session not found
- `41304`: `cwd` resolves outside the session workspace

#### `GET /api/v1/sessions/{session_id}/terminals/{terminal_id}`

Reads one terminal.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `terminal_id` | path | string | **Required.** Terminal id |

On success, `data` is the terminal object documented under `GET /api/v1/sessions/{session_id}/terminals` above.

- `40401`: session not found
- `40414`: no terminal with that id

#### `POST /api/v1/sessions/{session_id}/terminals/{terminal_id}:close`

Closes a terminal, killing its process. The endpoint dispatches through `POST /api/v1/sessions/{session_id}/terminals/{tail}` with `close` as the only action — a bare id or an unknown action fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `terminal_id` | path | string | **Required.** Terminal id |

On success, `data` is `{ closed: true }`.

- `40001`: missing or unknown action suffix
- `40401`: session not found
- `40414`: no terminal with that id

### Workspaces

Workspaces are the registered project directories sessions live in. These endpoints manage the registry — list, register, rename, unregister — plus the per-workspace trust state that gates project-level MCP config. Every endpoint that returns a workspace uses the wire shape documented once under [The workspace object](#the-workspace-object).

| Method and path | Description |
| --- | --- |
| `GET /api/v1/workspaces` | List registered workspaces |
| `POST /api/v1/workspaces` | Register a workspace (idempotent on the root path) |
| `PATCH /api/v1/workspaces/{workspace_id}` | Rename |
| `DELETE /api/v1/workspaces/{workspace_id}` | Unregister (keeps on-disk content) |
| `GET /api/v1/workspaces/{workspace_id}/trust` | Read the trust state |
| `POST /api/v1/workspaces/{workspace_id}/trust` | Grant trust |
| `POST /api/v1/workspaces/{workspace_id}/untrust` | Revoke trust |
| `POST /api/v1/workspaces/{workspace_id}/add-dir` | Add an additional directory |

#### The workspace object

Every endpoint that returns a workspace uses this wire shape. Registration and rename broadcast the global `event.workspace.created` / `event.workspace.updated` events.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Workspace id, a `wd_<slug>_<hash12>` string derived from the root path |
| `root` | string | Absolute path of the project directory |
| `name` | string | Display name, 1–100 characters; defaults to the root's base name |
| `created_at` | string | Registration time, ISO 8601 |
| `last_opened_at` | string | Last time the workspace was opened or re-registered, ISO 8601 |
| `session_count` | integer | Number of sessions in the workspace |

#### `GET /api/v1/workspaces`

Lists every registered workspace.

On success, `data` is `{ items }` where each item is [the workspace object](#the-workspace-object).

#### `POST /api/v1/workspaces`

Registers a workspace and returns it. Registration is idempotent on the root path: registering an already-registered root returns the existing workspace with only `last_opened_at` refreshed (the stored name is kept), broadcasting `event.workspace.updated` instead of `event.workspace.created`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `root` | body | string | **Required.** Absolute path of an existing directory |
| `name` | body | string | Display name, 1–100 characters. Default the root's base name |

On success, `data` is [the workspace object](#the-workspace-object).

- `40001`: `root` is missing or not an absolute path (`details` lists the field)
- `40409`: `root` does not exist or is not a directory

#### `PATCH /api/v1/workspaces/{workspace_id}`

Renames a workspace — the display name only; the root path never changes.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Workspace id |
| `name` | body | string | **Required.** New display name, 1–100 characters |

On success, `data` is [the workspace object](#the-workspace-object).

- `40001`: validation failure (`details` lists each field)
- `40410`: workspace not found

#### `DELETE /api/v1/workspaces/{workspace_id}`

Unregisters a workspace. Only the registry entry is removed — the on-disk directory is untouched.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Workspace id |

On success, `data` is `{ deleted: true }`.

- `40410`: workspace not found

#### `GET /api/v1/workspaces/{workspace_id}/trust`

Reads the workspace trust state. Trust gates whether project-level MCP config loads for the workspace.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Workspace id |

On success, `data` is `{ trusted }`.

- `40410`: workspace not found

#### `POST /api/v1/workspaces/{workspace_id}/trust`

Marks the workspace trusted, loading its project-level MCP config.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Workspace id |

On success, `data` is `{ trusted: true }`.

- `40410`: workspace not found

#### `POST /api/v1/workspaces/{workspace_id}/untrust`

Revokes workspace trust, unloading its project-level MCP config.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Workspace id |

On success, `data` is `{ trusted: false }`.

- `40410`: workspace not found

#### `POST /api/v1/workspaces/{workspace_id}/add-dir`

Adds an additional directory to the workspace, with the same semantics as the CLI `--add-dir` flag and the TUI `/add-dir` command. The path accepts absolute paths, relative paths (resolved against the workspace root), and `~` expansion.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace_id` | path | string | **Required.** Workspace id |
| `path` | body | string | **Required.** Directory to add |
| `persist` | body | boolean | Defaults to `true`: appends to `workspace.additional_dir` in `<project root>/.kimi-code/local.toml`. With `false`, the directory only joins the in-memory ephemeral set shared by all sessions of the workspace |

On success, `data` is `{ project_root, config_path, additional_dirs, persisted }`, where `additional_dirs` lists every additional directory (existing ones included) and `persisted` reports whether this call wrote to disk.

- `40001`: validation failure (`details` lists each field), or an engine-side config validation error such as a corrupted project local config
- `40409`: `path` does not exist or is not a directory
- `40410`: workspace not found

### File system

In-session file operations go through `POST /api/v1/sessions/{session_id}/fs:{action}` with JSON bodies; actions are `list` / `read` / `list_many` / `stat` / `stat_many` / `mkdir` / `search` / `grep` / `git_status` / `diff` / `open` / `open-in` / `reveal`. Every action body also accepts an optional `runtime_id` (string, default `local`) selecting the runtime that executes the operation; `open`, `open-in`, and `reveal` only work on the `local` runtime. In addition:

| Method and path | Description |
| --- | --- |
| `POST /api/v1/workspace/fs:search` | Session-less workspace search (the body carries the workspace reference) |
| `POST /api/v1/workspace/fs:suggest` | Session-less file-completion candidates (for `@` file mentions) |
| `GET /api/v1/sessions/{session_id}/fs/{path}:download` | Download a session file (binary, see below) |
| `GET /api/v1/fs:browse` | List host directories (folder picker) |
| `GET /api/v1/fs:home` | The user's home directory and recent workspaces |
| `GET /api/v1/fs:content` | Raw bytes of any host file (gated only by the token — be careful when exposing the port) |
| `POST /api/v1/fs:mkdir` | Create a directory by absolute path |

#### `POST /api/v1/sessions/{session_id}/fs:list`

Lists the entries of a session workspace directory, optionally recursing into subdirectories.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | Directory to list, relative to the session work directory. Default `.` |
| `depth` | body | integer | Recursion depth, 1–10. Default `1` |
| `limit` | body | integer | Maximum entries, 1–1000. Default `200` |
| `show_hidden` | body | boolean | Include dotfiles. Default `false` |
| `follow_gitignore` | body | boolean | Skip gitignored paths. Default `true` |
| `exclude_globs` | body | string[] | Additional globs to skip |
| `sort` | body | string | `type_first` (default) / `name_asc` / `name_desc` / `mtime_desc` / `size_desc` |
| `include_git_status` | body | boolean | Attach each entry's git status. Default `false` |

On success, `data` is `{ items, truncated }` — plus `children_by_path` (a path → entries map) when `depth` is greater than 1. Each item is an entry object `{ path, name, kind, size?, modified_at, etag?, mime?, language_id?, is_binary?, is_symlink_to?, git_status?, child_count? }`, where `kind` is `file` / `directory` / `symlink` and `git_status` (present only with `include_git_status: true`) is one of `clean` / `modified` / `added` / `deleted` / `renamed` / `untracked` / `ignored` / `conflicted`; `truncated` reports that `limit` cut the listing short.

- `40001`: body validation failure
- `40401`: session not found
- `40409`: path not found (including a `path` that is not a directory)
- `41304`: path escapes the session workspace

#### `POST /api/v1/sessions/{session_id}/fs:read`

Reads a slice of a session file as text or base64.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | **Required.** File path, relative to the session work directory |
| `offset` | body | integer | Byte offset to start at. Default `0` |
| `length` | body | integer | Bytes to read, 1–10485760 (10 MiB). Default `1048576` (1 MiB) |
| `encoding` | body | string | `auto` (default) / `utf-8` / `base64` |

On success, `data` is `{ path, content, encoding, size, truncated, etag, mime, language_id?, line_count?, is_binary }`, where `encoding` reports the encoding actually used (`utf-8` or `base64`) and `size` is the full file size. With `encoding: "auto"`, text comes back as `utf-8` (non-UTF-8 text is transcoded) and binary content as `base64`; `encoding: "utf-8"` forces text and rejects binary files.

- `40001`: body validation failure
- `40401`: session not found
- `40409`: path not found
- `40906`: path is a directory
- `40907`: binary file requested with `encoding: "utf-8"`
- `41302`: file exceeds the 10 MiB read ceiling
- `41304`: path escapes the session workspace

#### `POST /api/v1/sessions/{session_id}/fs:list_many`

Lists several session directories in one call; a failing path folds into the response instead of failing the whole request.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `paths` | body | string[] | **Required.** Directories to list, 1–100 entries |

The remaining body fields (`depth`, `limit`, `show_hidden`, `follow_gitignore`, `exclude_globs`, `sort`, `include_git_status`) have the same types, ranges, and defaults as `fs:list`. On success, `data` is `{ results }`, a map from each requested path to its entry array (entry objects as described under `fs:list`), plus `truncated_paths` (paths whose listing hit `limit`) and `partial_errors`, a map from a failed path to its `{ code, msg }` error.

- `40001`: body validation failure
- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/fs:stat`

Stats one path in the session workspace.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | **Required.** Path to stat, relative to the session work directory |

On success, `data` is the entry object described under `fs:list`.

- `40001`: body validation failure
- `40401`: session not found
- `40409`: path not found
- `41304`: path escapes the session workspace

#### `POST /api/v1/sessions/{session_id}/fs:stat_many`

Stats many session paths in one call; missing paths report `null` instead of failing the request.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `paths` | body | string[] | **Required.** Paths to stat, 1–1000 entries |

On success, `data` is `{ entries }`, a map from each requested path to its entry object (as described under `fs:list`) or `null` when the path does not exist.

- `40001`: body validation failure
- `40401`: session not found

#### `POST /api/v1/sessions/{session_id}/fs:mkdir`

Creates a directory inside the session workspace.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | **Required.** Directory to create, relative to the session work directory |
| `recursive` | body | boolean | Create missing parent directories. Default `false` |

On success, `data` is the created directory's entry object (as described under `fs:list`).

- `40001`: body validation failure
- `40401`: session not found
- `40409`: parent directory not found (non-recursive create)
- `40919`: path already exists (non-recursive create)
- `41304`: path escapes the session workspace

#### `POST /api/v1/sessions/{session_id}/fs:search`

Fuzzy-searches file and directory names across the session workspace. An empty `query` lists the top-level entries instead. When the `{session_id}` slot carries a workspace reference (a registered workspace id or an absolute root) rather than a session id, the search runs against that workspace — the session-less form for a not-yet-created draft session; the first-class session-less endpoint is `POST /api/v1/workspace/fs:search`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id, or a workspace reference |
| `query` | body | string | **Required.** Search text; `""` lists the top level |
| `limit` | body | integer | Maximum hits, 1–200. Default `50` |
| `include_globs` | body | string[] | Only paths matching one of these globs |
| `exclude_globs` | body | string[] | Skip paths matching these globs |
| `follow_gitignore` | body | boolean | Skip gitignored paths. Default `true` |

On success, `data` is `{ items, truncated }` where each item is `{ path, name, kind, score, match_positions }` — `kind` is `file` / `directory` / `symlink`, `score` is the fuzzy-match score between 0 and 1, and `match_positions` lists the matched character offsets. Hits sort by score (ties by path), and `truncated` reports that hits beyond `limit` were dropped.

- `40001`: body validation failure
- `40401`: neither a session nor a resolvable workspace with that reference

#### `POST /api/v1/sessions/{session_id}/fs:grep`

Searches file contents across the session workspace — a literal string by default, a regular expression with `regex: true`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `pattern` | body | string | **Required.** Text or regex to search for |
| `regex` | body | boolean | Treat `pattern` as a regular expression. Default `false` |
| `case_sensitive` | body | boolean | Default `true` |
| `include_globs` | body | string[] | Only files matching one of these globs |
| `exclude_globs` | body | string[] | Skip files matching these globs |
| `follow_gitignore` | body | boolean | Skip gitignored paths. Default `true` |
| `max_files` | body | integer | Files to scan at most, 1–10000. Default `200` |
| `max_matches_per_file` | body | integer | Matches kept per file, 1–10000. Default `50` |
| `max_total_matches` | body | integer | Matches kept overall, 1–100000. Default `5000` |
| `context_lines` | body | integer | Context lines around each match, 0–10. Default `2` |

On success, `data` is `{ files, files_scanned, truncated, elapsed_ms }` where each entry of `files` is `{ path, matches }` and each match is `{ line, col, text, before, after }` (`before` / `after` carry up to `context_lines` surrounding lines); `truncated` reports that one of the match budgets cut the results short.

- `40001`: body validation failure
- `40401`: session not found
- `41305`: the search timed out

#### `POST /api/v1/sessions/{session_id}/fs:git_status`

Reads the git status of the session workspace, optionally restricted to a set of paths.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `paths` | body | string[] | Restrict the status to these paths; omitted means the whole workspace |

On success, `data` is `{ branch, ahead, behind, entries, additions, deletions, pullRequest }` where `entries` maps each changed path to its status (`clean` / `modified` / `added` / `deleted` / `renamed` / `untracked` / `ignored` / `conflicted`) and `pullRequest` is `{ number, state, url }` (`state` is `open` / `merged` / `closed` / `draft`) or `null`.

- `40001`: body validation failure
- `40401`: session not found
- `40908`: git is unavailable (not a repository, or no git binary)

#### `POST /api/v1/sessions/{session_id}/fs:diff`

Returns the unified git diff of one file in the session workspace.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | **Required.** File to diff, relative to the session work directory |

On success, `data` is `{ path, diff, truncated }` where `diff` is the unified diff text and `truncated` reports an over-long diff cut short.

- `40001`: body validation failure
- `40401`: session not found
- `40908`: git is unavailable (not a repository, or no git binary)
- `41304`: path escapes the session workspace

#### `POST /api/v1/sessions/{session_id}/fs:open`

Opens a session file with the host operating system's default handler. Local runtime only.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | **Required.** File to open, relative to the session work directory |
| `line` | body | integer | Line number to jump to where the handler supports it (positive integer) |

On success, `data` is `{ opened: true }`.

- `40001`: body validation failure
- `40401`: session not found
- `40409`: path not found
- `41304`: path escapes the session workspace

#### `POST /api/v1/sessions/{session_id}/fs:open-in`

Opens a session file or directory in a specific host application. Local runtime only.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `app_id` | body | string | **Required.** Target application: `finder` / `cursor` / `vscode` / `iterm` / `terminal` |
| `path` | body | string | **Required.** File or directory to open, relative to the session work directory |
| `line` | body | integer | Line number to jump to where the application supports it (positive integer) |

On success, `data` is `{ opened: true }`.

- `40001`: body validation failure
- `40401`: session not found
- `40409`: path not found
- `41304`: path escapes the session workspace
- `50001`: the application failed to launch

#### `POST /api/v1/sessions/{session_id}/fs:reveal`

Reveals a session file in the host operating system's file manager. Local runtime only.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | body | string | **Required.** File to reveal, relative to the session work directory |

On success, `data` is `{ revealed: true }`.

- `40001`: body validation failure
- `40401`: session not found
- `40409`: path not found
- `41304`: path escapes the session workspace

#### `GET /api/v1/sessions/{session_id}/fs/{path}:download`

Downloads a file from the session workspace; `{path}` is the workspace-relative file path with the literal `:download` suffix. The response is a binary stream with range and ETag support — see [Binary and streaming endpoints](#binary-and-streaming-endpoints).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `session_id` | path | string | **Required.** Session id |
| `path` | path | string | **Required.** Workspace-relative file path plus the `:download` suffix |
| `runtime_id` | query | string | Runtime to read from. Default `local` |

- `40001`: missing or empty path
- `40401`: session not found
- `40409`: path not found
- `41304`: path escapes the session workspace

#### `POST /api/v1/workspace/fs:search`

The session-less form of `fs:search`: the workspace travels in the body instead of the URL.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace` | body | string | **Required.** Registered workspace id or absolute root (registered on the spot) |
| `query` | body | string | **Required.** Search text; `""` lists the top level |
| `limit` | body | integer | Maximum hits, 1–200. Default `50` |
| `include_globs` | body | string[] | Only paths matching one of these globs |
| `exclude_globs` | body | string[] | Skip paths matching these globs |
| `follow_gitignore` | body | boolean | Skip gitignored paths. Default `true` |
| `runtime_id` | body | string | Runtime to search on. Default `local` |

On success, `data` is `{ items, truncated }` with the same hit shape and ordering as `fs:search`.

- `40001`: body validation failure
- `40410`: workspace not found and not a usable absolute path

#### `POST /api/v1/workspace/fs:suggest`

Suggests file and directory completion candidates in a workspace without a session — the backend for `@` file mentions in the composer.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `workspace` | body | string | **Required.** Registered workspace id or absolute root (registered on the spot) |
| `query` | body | string | **Required.** Partial path text to complete |
| `limit` | body | integer | Maximum candidates, 1–200. Default `50` |
| `follow_gitignore` | body | boolean | Skip gitignored paths. Default `true` |
| `show_hidden` | body | boolean | Include dotfiles. Default `false` |
| `include_globs` | body | string[] | Only paths matching one of these globs |
| `exclude_globs` | body | string[] | Skip paths matching these globs |
| `runtime_id` | body | string | Runtime to complete on. Default `local` |

On success, `data` is `{ items, truncated }` where each item is `{ path, name, kind, score, match_positions }`, the same hit shape as `fs:search`.

- `40001`: body validation failure
- `40410`: workspace not found and not a usable absolute path

#### `GET /api/v1/fs:browse`

Lists the subdirectories of one host directory — the backend of the folder picker.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `path` | query | string | Absolute directory path. Default the user's home directory |

On success, `data` is `{ path, parent, entries }` where `path` is the resolved directory, `parent` its parent (`null` at the filesystem root), and each entry is `{ name, path, is_dir: true }`.

- `40001`: `path` is not absolute
- `40409`: path not found
- `40411`: permission denied

#### `GET /api/v1/fs:home`

Returns the folder picker's landing payload. No parameters.

On success, `data` is `{ home, recent_roots }` where `home` is the user's home directory and `recent_roots` lists the roots of the registered workspaces.

#### `GET /api/v1/fs:content`

Streams the raw bytes of any file on the host filesystem — gated only by the API token, so be careful when exposing the port. Range requests and ETag caching are supported; see [Binary and streaming endpoints](#binary-and-streaming-endpoints).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `path` | query | string | **Required.** Absolute file path |

- `40001`: `path` is not absolute, or not a regular file
- `40409`: path not found
- `40411`: permission denied
- `40906`: path is a directory

#### `POST /api/v1/fs:mkdir`

Creates one directory on the host filesystem by absolute path — the folder picker's "new folder" backend. Non-recursive: the parent directory must already exist.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `path` | body | string | **Required.** Absolute directory path |

On success, `data` is `{ path }`.

- `40001`: `path` is not absolute
- `40409`: parent path not found
- `40411`: permission denied
- `40919`: path already exists

### File uploads

| Method and path | Description |
| --- | --- |
| `POST /api/v1/files` | Multipart upload (`file` field, optional `name` and `expires_in_sec`); returns file metadata |
| `GET /api/v1/files/{file_id}` | Download (binary; errors use real HTTP statuses) |
| `DELETE /api/v1/files/{file_id}` | Delete |

#### `POST /api/v1/files`

Uploads a file as `multipart/form-data` for later reference (for example as a prompt attachment).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `file` | body | binary | **Required.** The multipart file part |
| `name` | body | string | Stored display name. Default the uploaded filename |
| `expires_in_sec` | body | number | Seconds until the file expires (non-negative). Default never expires |

On success, `data` is the file metadata `{ id, name, media_type, size, created_at, expires_at? }` with `media_type` taken from the upload's content type.

- `40001`: the multipart body has no `file` field

#### `GET /api/v1/files/{file_id}`

Downloads an uploaded file. The response is a binary stream that honors range requests but ignores `If-None-Match`; failures use real HTTP statuses — see [Binary and streaming endpoints](#binary-and-streaming-endpoints).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `file_id` | path | string | **Required.** File id from the upload response |

- `40407` (HTTP 404): no file with that id (including an expired file)

#### `DELETE /api/v1/files/{file_id}`

Deletes an uploaded file.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `file_id` | path | string | **Required.** File id from the upload response |

On success, `data` is `{ deleted: true }`.

- `40407` (HTTP 404): no file with that id

### GUI store

A server-backed key/value store that mirrors the browser `localStorage` interface, persisted under the server's home directory; the web UI keeps cross-client UI state here. Values are opaque strings — serialization is the caller's job.

| Method and path | Description |
| --- | --- |
| `GET /api/v1/gui/store/length` | Number of stored keys |
| `GET /api/v1/gui/store/getItem` | Read a value by key |
| `POST /api/v1/gui/store/setItem` | Write a value by key |
| `POST /api/v1/gui/store/removeItem` | Delete a value by key |
| `POST /api/v1/gui/store/clear` | Delete all values |

#### `GET /api/v1/gui/store/length`

Returns the number of stored keys (mirrors `localStorage.length`). No parameters.

On success, `data` is `{ length }`.

#### `GET /api/v1/gui/store/getItem`

Reads one value (mirrors `localStorage.getItem`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `key` | query | string | **Required.** Key to read, 1–256 characters |

On success, `data` is `{ value }`, the stored string or `null` when the key does not exist.

#### `POST /api/v1/gui/store/setItem`

Writes one value (mirrors `localStorage.setItem`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `key` | body | string | **Required.** Key to write, 1–256 characters |
| `value` | body | string | **Required.** Value to store |

On success, `data` is `null`.

#### `POST /api/v1/gui/store/removeItem`

Deletes one value (mirrors `localStorage.removeItem`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `key` | body | string | **Required.** Key to delete, 1–256 characters |

On success, `data` is `null`.

#### `POST /api/v1/gui/store/clear`

Deletes every stored value (mirrors `localStorage.clear`). No parameters.

On success, `data` is `null`.

### Global search and misc

| Method and path | Description |
| --- | --- |
| `POST /api/v1/search` | Cross-session full-text search; `mode` is `terms` (default) or `literal` (exact substring); `page_token` pagination |
| `GET /api/v1/connections` | List live WebSocket connections |
| `GET /api/v2/sessions` | Next-generation session list, see below |
| `POST /api/v2/sessions:archive` | Batch-archive sessions, see below |
| `POST /api/v2/sessions:restore` | Batch-restore archived sessions, see below |
| `/api/v2/mcp/*` | Unified MCP management plane, see below |
| `/api/v1/debug/*` | Reflection debug RPC; mounted only with `--debug-endpoints` on loopback, not a stable protocol |

#### `POST /api/v1/search`

Cross-session full-text search over user messages, assistant replies, and session titles, backed by the server's persistent search index. When `container.session_id` names a session live in this server process, the search instead scans that session's in-memory transcript directly, and the response's `source` field (`index` or `live`) reports which path served the page.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `query` | body | string | **Required.** Search text |
| `mode` | body | string | `terms` (default) / `literal` |
| `op` | body | string | Term combiner in `terms` mode: `AND` (default) / `OR` |
| `container` | body | object | Restrict the search to `{ session_id?, agent_id? }` |
| `role` | body | string | Restrict to `user` / `assistant` / `title` hits |
| `start_time` | body | integer | Only hits at or after this time (epoch milliseconds) |
| `end_time` | body | integer | Only hits at or before this time (epoch milliseconds) |
| `sort` | body | string | `score` (default) / `time_desc` / `time_asc`; ignored by `literal` mode, which always returns newest-first |
| `page_size` | body | integer | Hits per page, 1–50. Default `20` |
| `page_token` | body | string | Token from the previous page's response |

In `terms` mode the query is tokenized (ASCII words plus CJK n-grams), deduplicated, and matched against the inverted index with at most 32 terms; `literal` mode is an exact substring search with zero false positives. On success, `data` is `{ items, has_more, page_token?, index_state, source }` where each item is `{ session_id, workspace_id, session_title, agent_id, role, snippet, time, turn?, step_id?, score }`. `index_state` is `{ state, indexed_sessions, total_sessions, documents, stale?, degraded? }` with `state` one of `building` / `ready` / `readonly`; `stale` marks a behind view still catching up, and `degraded` carries the last refresh failure. An over-budget page additionally carries `incomplete`, one of `candidate_cap` / `postings_budget` / `deadline`. Page tokens pin the index generation and the query conditions — a rebuild or a changed query invalidates them.

- `40001`: body validation failure, an unusable query (empty, or more than 32 terms), or an invalid page token

#### `GET /api/v1/connections`

Lists the WebSocket clients currently connected to this server, oldest connection first. No parameters.

On success, `data` is `{ connections }` where each item is `{ id, connected_at, remote_address, user_agent, has_client_hello, subscriptions }`: `connected_at` is an ISO 8601 timestamp, `remote_address` and `user_agent` are `null` when unknown, `has_client_hello` reports whether the client sent its handshake frame, and `subscriptions` lists the session ids the connection is subscribed to.

### `GET /api/v2/sessions`

A next-generation session query for list views — filtering, sorting, and field groups all travel in query parameters:

| Parameter | Description |
| --- | --- |
| `workspace.id` | Filter by workspace; repeatable |
| `activity.status` | Filter by activity status: `running` / `approval` / `question` / `failed` / `idle`; repeatable |
| `meta.updated_after` | Only sessions updated after this time (epoch milliseconds) |
| `meta.updated_before` | Only sessions updated before this time (epoch milliseconds) |
| `meta.archived` | `true` / `false` (default) / `all` |
| `meta.has_prompt` | `true` keeps only sessions that carry a user prompt, `false` keeps only empty ones (the `exclude_empty` equivalent of `GET /api/v1/sessions`) |
| `view` | `flat` (default) / `by_workspace`, see below |
| `group.page_size` | Sessions returned per workspace under `view=by_workspace`: 1–100, default 5 (up to 10000 with the `id,archived` projection); rejected without the grouped view (`40001`) |
| `sort` | `meta.updated_at_desc` (default) / `meta.updated_at_asc` / `meta.created_at_desc` |
| `include` | Comma-separated extra field groups; currently only `git` (branch and PR info, deduplicated per directory and cached for 60 seconds) |
| `fields` | Comma-separated item projection; currently only `id,archived`, trimming each item to `{ id, archived }` (select-all-matching flows). Not combinable with `include=git` (`40001`) |
| `page_size` | 1–100, default 50; up to 10000 with the `id,archived` projection. Under `view=by_workspace` it counts groups per page |
| `page_token` | Pagination token from the previous page |
| `page` | Stateless 1-based page number; mutually exclusive with `page_token` (`40001` when combined) |

Every response item carries the `workspace`, `meta`, and `activity` groups, plus `git` when `include=git` — or just `{ id, archived }` under `fields=id,archived`. The `activity` group also reports `model`: the session's bound model alias while it is live in this process, `null` for cold (not currently loaded) sessions. Every page additionally carries `total`, the size of the filtered set. The page token binds the first page's query conditions (including the projection); changing them mid-pagination returns `40922`. `page` mode is a stateless alternative for jumping to arbitrary pages: every request is an independent snapshot, no token is minted, and `next_page_token` is always `null`.

With `view=by_workspace` the same filtered, sorted set is re-projected into per-workspace groups, so an overview client replaces one polling loop per workspace with a single request:

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "groups": [
      {
        "workspace": { "id": "wd_my-app_a1b2c3d4e5f6", "cwd": "/Users/dev/my-app" },
        "sessions": [ { "id": "session_...", "workspace": { "id": "wd_my-app_a1b2c3d4e5f6", "cwd": "/Users/dev/my-app" }, "meta": { "title": "Fix the login page", "last_prompt": "adjust the button spacing", "created_at": 1787000000000, "updated_at": 1787000100000, "archived": false, "archived_at": null }, "activity": { "status": "idle", "model": "kimi-for-coding" } } ],
        "total": 42
      }
    ],
    "total": 7,
    "has_more": true,
    "next_page_token": "eyJ2IjoxLCJmIjoi..."
  },
  "request_id": "req_..."
}
```

Each group carries the workspace's first `group.page_size` sessions under the requested `sort` plus `total`, the workspace's full matching-session count (for a "view all" entry). Only workspaces with at least one matching session appear; groups order by their first session's sort key, ties broken by workspace id. `page` and `page_token` paginate over groups (the outer `total` is the group count), with the same fingerprint binding: the token also covers `view` and the grouping parameters, so flipping them mid-pagination returns `40922`.

### `POST /api/v2/sessions:archive` and `POST /api/v2/sessions:restore`

Batch archive/restore for session-management views. The body is `{ "ids": ["session_..."] }` — non-empty, at most 5000 unique ids (duplicates collapse). Live sessions go through the full lifecycle; cold sessions are patched on disk without being loaded.

Only a body validation failure fails the whole request (`40001`). Otherwise the response is per-item: `data.results` keeps the input order with `{ id, ok }` or `{ id, ok: false, error }` (an unknown id reports `40401` in its own item), plus `succeeded` / `failed` counts.

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "results": [
      { "id": "session_a", "ok": true },
      { "id": "session_b", "ok": false, "error": { "code": 40401, "message": "session session_b does not exist" } }
    ],
    "succeeded": 1,
    "failed": 1
  },
  "request_id": "req_..."
}
```

### MCP management (`/api/v2/mcp`)

The `/api/v2/mcp/*` routes are the server's unified MCP management plane: they manage the MCP server registry itself, independent of any session — global (user-level) CRUD with per-entry validation, connection-test probes, a locator-addressed inspection catalog, per-server auth-status listing, and the full OAuth flow lifecycle.

| Method and path | Description |
| --- | --- |
| `GET /api/v2/mcp/servers` | List every known MCP server |
| `GET /api/v2/mcp/servers/{name}` | Get one server by runtime name |
| `POST /api/v2/mcp/servers` | Add a server to the user-level `mcp.json` |
| `PUT /api/v2/mcp/servers/{name}` | Replace a user-level entry |
| `DELETE /api/v2/mcp/servers/{name}` | Remove a user-level entry |
| `POST /api/v2/mcp/servers:test` | Probe a real connection to one server |
| `POST /api/v2/mcp/servers:inspect` | Locator-addressed catalog with a batched connection probe |
| `GET /api/v2/mcp/auth-statuses` | Per-server OAuth state over the catalog |
| `POST /api/v2/mcp/auth:begin` | Begin an interactive OAuth flow |
| `POST /api/v2/mcp/auth:complete` | Await the browser callback and finish the code exchange |
| `POST /api/v2/mcp/auth:cancel` | Tear down a begun OAuth flow |
| `POST /api/v2/mcp/auth:reset` | Clear a server's stored credentials |

Two addressing schemes appear on this plane. The CRUD routes and `servers:test` take a plain runtime `name`; the inspection and OAuth routes take a **locator** — `{ "source": "global", "name" }` for a file-layer entry or `{ "source": "plugin", "pluginId", "serverName" }` for a plugin-manifest entry — because a plugin entry and a file entry can share one runtime name. Inspection items additionally carry a stable `serverId` wire id: `global:<name>` or `plugin:<pluginId>:<serverName>` (URL-encoded).

Most routes accept an optional `cwd` (a query parameter, or a body field on the `:`-action routes). Without it the catalog covers the user-level file and plugin manifests only; with it, the project-root and project-local layers of that directory join in — but only when the workspace is trusted, otherwise the project layers are skipped. For `servers:test` on a stdio server, `cwd` is also the child process's working directory. Connection probes and OAuth calls wait for the server's configuration to finish loading before acting.

#### `GET /api/v2/mcp/servers` and `GET /api/v2/mcp/servers/{name}`

Lists every MCP server the management plane knows about; the second route returns the single entry with that runtime name.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `name` | path | string | **Required (get only).** Runtime name of the server |
| `cwd` | query | string | Include the project layers of this (trusted) directory |

On success, `data` is an array of managed servers (a single object for the get route), each `{ name, config, source, origin, mutable, plugin? }`:

- `source`: `global` (a config-file layer) or `plugin` (a plugin manifest)
- `origin`: where the entry is defined — a file path or a plugin id
- `mutable`: only user-level entries are mutable; plugin and project-layer entries are read-only
- `config`: mutable entries carry the full config so edit UIs can prefill it; read-only entries are redacted to sorted key lists (`envKeys` / `headerKeys`) and never disclose secret values
- `plugin`: `{ id, name }`, present on plugin entries

- `40001`: validation failure
- `40408`: no server with that name

#### `POST` / `PUT` / `DELETE /api/v2/mcp/servers`

Global CRUD against the user-level `mcp.json`. The add body is a full server config including `name` — `transport` (`stdio` / `http` / `sse`) discriminates the shape, and each entry is validated before it is written. The update body carries the same config without `name` (the path names the entry); delete takes no body. All three return the refreshed server list in `data`. A write whose name collides with a project-layer entry is rejected as read-only — edit the defining file instead; a same-named plugin entry does not block the write, and the new file entry shadows it.

- `40001`: validation failure, or the target entry is read-only
- `40408`: (update/delete) no server with that name

#### `POST /api/v2/mcp/servers:test`

Probes a real connection to one server and never persists anything. Pass either `name` to test a registry entry (plugin and trusted project layers included) or `server` (a full inline config, `name` included) to probe it as-is; passing both or neither fails `40001`.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `name` | body | string | Runtime name of a registry entry |
| `server` | body | object | Inline server config to probe as-is |
| `cwd` | body | string | Project layers join the resolution; also the stdio working directory |

On success, `data` is `{ success, output }`: when the connection succeeds, `output` lists the server's available tools; otherwise it carries the failure text.

- `40001`: both or neither target form passed, an invalid inline config, or a runtime name shared by multiple enabled servers
- `40408`: no server with that name

#### `POST /api/v2/mcp/servers:inspect`

The locator-addressed catalog (redacted configs) plus a batched real-connection probe of every OAuth candidate.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `targets` | body | array | Locators narrowing the catalog; omitted inspects all servers |
| `cwd` | body | string | Include the project layers of this (trusted) directory |

On success, `data` is an array of inspections, each `{ serverId, locator, runtimeName, canonicalUrl?, origin, config, enabled, editable, authStatus, checkedAt?, error? }`: `canonicalUrl` is the credential URL of a remote server, `config` is the redacted view, and `authStatus` is one of `not-applicable` / `bearer-token` / `oauth-required` / `oauth-authorized` / `oauth-expired` / `unavailable`. A runtime name shared by multiple enabled servers cannot be probed unambiguously and reports `unavailable` with an explanatory `error`. A probe that hits an expired grant may refresh or invalidate the stored credentials.

- `40001`: validation failure
- `40408`: a `targets` locator matches nothing

#### `GET /api/v2/mcp/auth-statuses`

Per-server OAuth state over the registry catalog — the lightweight alternative to `servers:inspect` when only the auth dimension is needed.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `cwd` | query | string | Include the project layers of this (trusted) directory |
| `verify` | query | string | `true` probes every OAuth candidate through a real connection; `false` is fully offline (config and stored tokens only); omitted preserves implicit OAuth detection, probing only unpinned remote servers without stored credentials |

On success, `data` is an array of `{ name, authStatus }` with the same `authStatus` enum as `servers:inspect`. Verification probes may refresh or invalidate stored credentials.

#### `POST /api/v2/mcp/auth:begin` / `:complete` / `:cancel` / `:reset`

The OAuth flow lifecycle for remote servers. `auth:begin` takes a locator body (plus the optional `cwd` query) and answers `data` `{ status: "authorization-required", flowId, authorizationUrl }` — open the URL in a browser to grant access — or `{ status: "already-authorized" }` when a grant already exists. The target server must use a remote transport (`http` / `sse`) and must not carry a static bearer token; static headers are allowed only when the config explicitly sets `auth: "oauth"`.

`auth:complete` waits for the browser callback of a begun flow and finishes the code exchange. Its body is `{ flowId, timeoutMs? }`: the wait defaults to 15 minutes (`timeoutMs` overrides it), an idle flow expires after 15 minutes regardless, and closing the HTTP connection aborts the wait. `data` is `null` on success.

`auth:cancel` tears down a begun flow (`{ flowId }`) without finishing it; unknown flows are ignored. `auth:reset` takes a locator body and clears the server's stored credentials — the invalidation event reaches live sessions.

- `40001`: validation failure — including an unknown `flowId` on `:complete`, or a server that cannot do OAuth (stdio transport, a static bearer token, or static headers without `auth: "oauth"`) on `:begin`
- `40408`: (`:begin` / `:reset`) the locator matches nothing
- `40929`: the OAuth flow itself failed

## WebSocket protocol

### Connect

The only endpoint is `ws://<host>:<port>/api/v1/ws`; authentication happens at the upgrade request (see [Authentication](#authentication) above). Once connected, the server immediately sends `server_hello`:

```json
{
  "type": "server_hello",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "ws_connection_id": "conn_01JZX4...",
    "protocol_version": 2,
    "max_event_buffer_size": 1000,
    "capabilities": { "event_batching": false, "compression": false }
  }
}
```

Note that the server never sends heartbeats and never disconnects an idle connection — keepalive and reconnection are the client's job.

### Control frames

Clients send JSON frames `{ "type", "id"?, "payload" }`; every request frame gets an acknowledgement `{ "type": "ack", "id", "code", "msg", "payload" }`, where `code` 0 means success.

| Frame | payload | Description |
| --- | --- | --- |
| `subscribe` | `{ session_ids, cursors?, agent_filter? }` | Subscribe to session events; with `cursors` (per-session `{seq, epoch}`) the server replays missed durable events |
| `unsubscribe` | `{ session_ids }` | Drop session subscriptions |
| `subscribe_v2` | `{ session_id, transcript, transcript_since? }` | Subscribe to transcript streams (the only transcript channel); `transcript` sets per-agent grades |
| `unsubscribe_v2` | `{ session_id, agent_ids? }` | Detach transcript streams; omitting `agent_ids` means the whole session |
| `client_hello` | `{ client_id }` | Handshake frame; the remaining fields are legacy compatibility |

### Events

Event frames look like `{ "type", "seq", "epoch"?, "volatile"?, "offset"?, "session_id"?, "timestamp", "payload" }`, where `type` is the event type itself. Two delivery scopes:

- **Global events**: sent to every established connection, no subscription needed — `session.meta.updated`, `event.session.created`, `event.session.archived`, `event.session.work_changed`, `event.session.status_changed`, `event.workspace.*`, `event.config.*`, `event.model_catalog.*`.
- **Session events**: sent only to connections subscribed to that session, subject to `agent_filter`. Main families:

| Family | Main events |
| --- | --- |
| Turns | `turn.started`, `turn.ended`, `turn.step.started` / `completed` / `interrupted` / `retrying` |
| Streaming text | `assistant.delta`, `thinking.delta` (carry `offset` for alignment) |
| Tool calls | `tool.call.started`, `tool.call.delta`, `tool.progress`, `tool.result` |
| Interactions | `event.approval.requested` / `resolved`, `event.question.requested` / `answered` / `dismissed` |
| Subagents | `subagent.spawned` / `started` / `suspended` / `completed` / `failed` |
| Background | `task.started` / `terminated`, `shell.started` / `output` / `completed` |
| Misc | `compaction.*`, `skill.activated`, `goal.updated`, `prompt.*`, `error`, `warning` |

Three global lifecycle events keep a cross-workspace overview fresh without polling per workspace. `event.session.archived` fires on both the live and the cold archive path; its envelope `session_id` is the global watermark `__global__` and the real session id rides in the payload: `{ "type": "event.session.archived", "workspace_id": "wd_...", "sessionId": "session_..." }` (payload keys `workspace_id` / `sessionId`). `event.workspace.created` / `updated` carry the full workspace object (`{ id, root, name, created_at, last_opened_at, session_count }` — an `updated` also fires when a session creation touches the workspace), and `event.workspace.deleted` carries `{ "workspace_id", "root" }`. These events only cover changes made inside this server process; changes from other processes (for example a CLI writing to the same home) surface through the index reconciliation (about a minute), so overview clients should keep a low-frequency fallback poll. There is no session-deleted event.

Events also split into durable and volatile: durable events carry a strictly increasing `seq`, are journaled, and can be replayed; volatile events (the `*.delta` family, `tool.progress`, `shell.*`, and similar) are marked `volatile: true` and never replayed. When consuming a volatile text stream, compare `offset` (the cumulative character offset within the turn) against your locally accumulated text: below the local length means a duplicate frame; above means a gap that needs snapshot recovery.

### Reconnect and recovery

After reconnecting, pass each session's last applied `{seq, epoch}` in `subscribe`'s `cursors`; the server replays the gap. If you fall more than the buffer (1000 events) behind, or the cursor is no longer valid, you get `resync_required` instead. In that case, call `GET /api/v1/sessions/{session_id}/snapshot` for a full snapshot (with `as_of_seq` and `epoch`), then subscribe again with the fresh cursor.

### Transcript protocol

`subscribe_v2`'s `transcript` field sets a per-agent grade: `off` / `turn` / `block` / `delta` (the `"*"` key sets the default grade), with higher grades pushing finer detail. An agent with a non-`off` grade receives two frame types: `transcript.reset` (a baseline snapshot; history pages in over REST) and `transcript.ops` (incremental op batches with a per-agent strictly increasing `seq`). The agent's legacy events are suppressed on that connection and carried by transcript frames instead. After a disconnect, resume with `transcript_since`; when the server's op journal cannot cover the gap (REST catch-up returns `complete: false`), do a full refresh. The REST counterparts are `GET .../transcript` (turn-paged) and `GET .../transcript/ops?since_seq=` (op-batch catch-up).

## Binary and streaming endpoints

The following endpoints stream binary bodies instead of a JSON payload. Their HTTP capabilities differ per endpoint:

| Method and path | Description | Range (206) | ETag / 304 |
| --- | --- | --- | --- |
| `GET /api/v1/files/{file_id}` | Download an uploaded file | Yes | No (sends an `etag` header but ignores `If-None-Match`) |
| `GET /api/v1/sessions/{session_id}/fs/{path}:download` | Download a session workspace file | Yes | Yes |
| `GET /api/v1/fs:content` | Raw bytes of any host file (gated only by the token — be careful when exposing the port) | Yes | Yes |
| `POST /api/v1/sessions/{session_id}/export` | Export the session with diagnostics (zip stream) | No | No |

Error semantics differ as well: `GET /api/v1/files/{file_id}` answers lookup and storage failures with real 404 / 500 statuses (parameter validation still uses the HTTP 200 envelope), while the other three report every failure through the standard [response envelope](#response-envelope) — clients must keep checking the envelope `code` on those endpoints.

## Next steps

- [Using Kimi Code in the browser](../guides/web.md) — start the server and use Kimi Code in a browser
- [kimi command](./kimi-command.md#kimi-web) — all `kimi web` command-line options