服务 API

kimi web 启动的本地服务暴露两组程序化接口：REST API（/api/v1，另有 /api/v2/sessions 和 /api/v2/mcp）和 WebSocket 事件流（/api/v1/ws）。本页是这两组接口的协议参考。如何启动服务及其命令行选项见 kimi 命令参考；端到端的上手流程见下文「用 API 驱动一个会话」。

本页是一份经过整理、面向人阅读的参考：下文逐一记录每个端点的参数、请求体与响应结构。每个端点精确的机器可读 schema 以服务的在线规范文档为准：GET /openapi.json（OpenAPI）与 GET /asyncapi.json（AsyncAPI），两者都由服务运行时实际执行的校验 schema 生成。两者都需要鉴权；当本页与在线规范不一致时，以在线规范为准。

注意

本页描述的 REST 与 WebSocket API 为实验性特性：不保证接口稳定性，端点、字段与事件类型可能随任何版本更改。集成时请以你所用版本服务的 /openapi.json 与 /asyncapi.json 文档为准。

基础约定

地址

默认地址为 http://127.0.0.1:58627。端口被占用时，服务会用下一个端口重试（至多 100 次）；可用 --port / --host 修改绑定。同一 home 目录下可并存多个实例，运行中的实例登记在 ~/.kimi-code/server/instances/。

鉴权

除以下例外，所有 /api/* 路径（含 /openapi.json 与 /asyncapi.json）都要求 bearer token：

OPTIONS 预检请求
GET /api/v1/healthz（探活）
静态 web 资源（非 /api/ 路径）

携带方式：REST 用 Authorization: Bearer <token> 请求头；WebSocket 升级请求接受同一请求头，或子协议 kimi-code.bearer.<token>。token 的生成与轮换见在网页中使用：开始使用。

鉴权失败返回 HTTP 401，信封 code 为 40101。在非 loopback 绑定上，同一来源 60 秒内鉴权失败 10 次会被封禁 60 秒，期间每个请求都返回 HTTP 429（code 为 42901）。

响应信封

所有 JSON 响应统一包在信封里：

json

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

code：业务结果，0 表示成功；错误码分段见下文。
data：成功时的业务数据。注意部分「错误」信封也携带非空 data——例如重复解决审批返回 40902 且 data.resolved 为 false——客户端应先判 code 再看 data。
request_id：本次请求的 ULID；客户端可用 X-Request-Id 请求头指定，非法值会被服务端重新生成。

HTTP 状态码几乎总是 200，业务结果以 code 为准。例外情况：

场景	HTTP 状态
鉴权失败 / 触发限流	401 / 429
创建供应商、导入供应商目录成功	201
删除供应商成功	204
二进制与流式端点	支持时返回 206（Range 分段）/ 304（ETag 未变），各端点能力不同，详见「二进制与流式端点」
`GET /api/v1/files/{file_id}` 下载错误	真实 404 / 500（响应体仍为信封）

其中 201 的响应体仍是标准信封（code 为 0），只是状态行遵循 REST 的资源创建惯例；204 按定义没有响应体，删除成功以状态码本身为准。

错误码

错误码按段位分组：

段位	含义	示例
`0`	成功
`400xx`	请求参数错误	`40001` 校验失败（`details` 逐字段说明）、`40003` 供应商由 OAuth 托管
`401xx`	鉴权与就绪状态	`40101` 未授权、`40110` 未配置供应商、`40113` 模型未解析
`404xx`	资源不存在	`40401` 会话、`40408` MCP 服务、`40409` 文件路径
`409xx`	状态冲突	`40901` 会话忙、`40902` 审批已解决、`40922` 分页条件与 `page_token` 不符
`410xx`	资源已过期	`41001` 审批超时、`41002` 提问超时、`41003` 临时文件过期
`413xx`	体积或边界超限	`41302` 读取文件超 10 MB、`41304` 路径越出会话目录
`429xx`	限流	`42901` 鉴权失败封禁、`42902` 文件监听数超限
`500xx`	服务端内部错误	`50001` 未捕获异常、`50003` 持久化失败
`6xxxx` / `7xxxx` / `8xxxx`	工具运行时 / LLM 供应商 / MCP 透传错误，`msg` 保留上游原文

分页

列表端点有两种分页风格：

游标式：before_id / after_id（互斥）加 page_size（1–100），响应为 { items, has_more }。用于会话列表、消息列表、转录等。
page_token：不透明令牌（绑定了查询条件的指纹），用于 POST /api/v1/search 与 GET /api/v2/sessions。翻页途中改变任何查询条件会使令牌失效：v2 返回 40922，search 返回 40001。GET /api/v2/sessions 另提供无状态的 page 页码模式作为替代。

用 API 驱动一个会话

下面用 curl 走一遍最小流程：确认服务状态 → 创建会话 → 订阅事件 → 提交提示词 → 回读历史。示例假设服务跑在默认地址，token 已存入 shell 变量 TOKEN。

确认服务状态：

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

所有 JSON 响应都包在统一信封里——{ "code": 0, "msg": "success", "data": ..., "request_id": "..." }，业务结果以 code 为准（0 表示成功），HTTP 状态码只表达传输层结果。

创建会话，metadata.cwd 指定工作目录：

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"}}'

返回的 data.id（形如 session_...）就是后续所有请求要用的会话 id。

连接 WebSocket 并订阅会话事件。任何 WebSocket 客户端都可以；下面是一个零依赖的 Node.js 脚本（Node.js 22+ 内置 WebSocket 客户端）：

// subscribe.mjs —— 用法：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]] },
    }),
  );

提交提示词：

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": "用一句话介绍这个仓库"}]}'

订阅端会依次看到 turn.started（轮次开始）→ assistant.delta（流式文本增量）→ 发生工具调用时的 tool.call.started / tool.result → turn.ended（轮次结束）。

随时可以用 REST 回读历史消息：

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

REST 端点

下文按资源分组列出端点。路径里的 :{action} 后缀是动作约定——对单个资源 POST 到 路径:动作 执行非 CRUD 操作（如会话的 :fork、:archive）。

服务与元信息

方法与路径	说明
`GET /api/v1/healthz`	探活，免鉴权
`GET /api/v1/meta`	服务版本、能力集、`server_id`、实验开关
`POST /api/v1/shutdown`	优雅退出（先回 200 再关闭）；仅 loopback 绑定时挂载

`GET /api/v1/healthz`

供脚本与进程管理器使用的探活端点。它是唯一豁免 bearer token 的 /api 端点（见鉴权），应答时不触碰配置与引擎。

成功时 data 为 { "ok": true }。

`GET /api/v1/meta`

返回本实例的身份信息与能力集。大多数字段在启动时即固定；experimental_flags 与 features 按请求实时解析，因此开关翻转或某个 feature 失败会体现在下一次响应中。

成功时 data 携带：

字段	类型	说明
`server_version`	string	服务版本
`capabilities`	object	能力集——`websocket`、`file_upload`、`fs_query`、`mcp`、`tasks`、`terminal`，均恒为 `true`
`server_id`	string	本服务实例的唯一 id
`started_at`	string	启动时间，ISO 8601 格式
`open_in_apps`	array	可作为 `open-in` 目标的宿主应用（`finder` / `cursor` / `vscode` / `iterm` / `terminal`）；目前恒为空
`dangerous_bypass_auth`	boolean	服务是否以 `--dangerous-bypass-auth` 启动（客户端可跳过 token 提示）
`backend`	string	引擎后端，`v1` 或 `v2`；本服务恒为 `v2`
`web_title`	string	来自 `--web-title` 的自定义浏览器标签页标题；未设置时省略
`experimental_flags`	object	实验开关 id → 是否启用，按请求时解析
`features`	array	引擎 feature，形如 `{ name, state, meta }`；`state` 为 `Pending` / `Activating` / `Active` / `Unloading` / `Failed`

`POST /api/v1/shutdown`

请求服务优雅退出。响应先发出，随后立即执行关闭，因此调用方可以信任收到的响应。该路由仅在 loopback 绑定时挂载——非 loopback 绑定时它根本不会被注册（请求得到 404），除非服务以 --allow-remote-shutdown 启动。

成功时 data 为 { "ok": true }。

登录与用量

这组端点驱动托管 Kimi OAuth 登录的生命周期，并暴露账号级信息。托管供应商名为 managed:kimi-code；下面每个端点上可选的 provider 参数都默认取它。

方法与路径	说明
`GET /api/v1/auth`	鉴权状态快照
`POST /api/v1/oauth/login`	发起 OAuth device-code 登录流程
`GET /api/v1/oauth/login`	轮询登录流程状态
`DELETE /api/v1/oauth/login`	取消进行中的登录流程
`POST /api/v1/oauth/logout`	登出托管供应商
`GET /api/v1/oauth/usage`	套餐用量与限额
`GET /api/v1/oauth/userinfo`	账号资料
`GET /api/v1/oauth/region`	解析客户端所属区域（`mainland-cn` / `global`）

`GET /api/v1/auth`

鉴权状态快照：默认模型能否解析到可用的供应商配置，以及托管供应商的登录状态。当全局 default_model 别名存在于模型表中且能解析到已配置的供应商时，models_ready 为 true——包括自带 base_url 的平铺（providerless）模型，以及通过 KIMI_MODEL_* 环境变量注入的模型。它不做凭据校验，因此此后的对话请求仍可能以 40111 / 40112 失败。

成功时 data 携带 models_ready（布尔值）、providers_count（已配置供应商数量）与 managed_provider（null，或 { name, status }，其中 status 为 authenticated / expired / revoked / unauthenticated 之一）。全局默认模型别名本身改从 GET /api/v1/config 的 default_model 读取，本端点不再携带。

`POST /api/v1/oauth/login`

为托管供应商发起 OAuth device-code 登录流程；发起新流程会中止同一供应商进行中的流程。账号已登录时无需用户交互，响应会立即报告 authenticated。

参数	位置	类型	说明
`provider`	body	string	托管供应商名称。默认 `managed:kimi-code`
`region`	body	string	`mainland-cn` 或 `global`；覆盖 `GET /api/v1/oauth/region` 一节描述的区域解析结果，仅对本次流程生效

成功时 data 有两种形态。进行中的流程——{ flow_id, provider, status: "pending", verification_uri, verification_uri_complete, user_code, expires_in, interval, expires_at }：打开 verification_uri_complete（或打开 verification_uri 并输入 user_code），然后每隔 interval 秒轮询 GET /api/v1/oauth/login，直到流程完结或超过 expires_at（expires_in 是以秒表示的同一时限）。已登录的快速路径——{ flow_id, provider, status: "authenticated" }。

`GET /api/v1/oauth/login`

轮询某供应商的登录流程状态。尚未发起过流程时返回 null。

参数	位置	类型	说明
`provider`	query	string	托管供应商名称。默认 `managed:kimi-code`

成功时 data 为 null 或流程快照：{ flow_id, provider, status, verification_uri, verification_uri_complete, user_code, expires_in, expires_at, interval }，其中 status 为 pending / authenticated / denied / expired / cancelled。流程离开 pending 后，resolved_at 记录其到达终态的时间，error_message 描述失败的流程。

`DELETE /api/v1/oauth/login`

取消某供应商进行中的登录流程。没有进行中的流程时，该调用为空操作，返回最近一次已知状态。

参数	位置	类型	说明
`provider`	query	string	托管供应商名称。默认 `managed:kimi-code`

成功时 data 为 { cancelled, status }：只有确实中止了一个 pending 流程时 cancelled 才为 true，status 为调用后的流程状态。

`POST /api/v1/oauth/logout`

登出托管供应商：丢弃已存储的 OAuth 凭据、中止进行中的登录流程，并把托管供应商从配置中移除。OAuth 托管的供应商拒绝手动编辑与删除（见下文 PUT / DELETE /api/v1/providers/{provider_id}），因此要移除它需先登出。

参数	位置	类型	说明
`provider`	body	string	托管供应商名称。默认 `managed:kimi-code`

成功时 data 为 { logged_out: true, provider }。

`GET /api/v1/oauth/usage`

托管账号的套餐用量与限额，实时取自账号服务。上游失败不会让信封失败——它以 kind: "error" 的形式带内返回。

参数	位置	类型	说明
`provider`	query	string	托管供应商名称。默认 `managed:kimi-code`

成功时 data 为 { kind: "ok", summary, limits, extra_usage } 或 { kind: "error", message, status? }，其中 status 为上游 HTTP 状态码（如存在）。在 ok 形态中，summary（可空）是主配额行，limits 列出每个配额窗口；一行的结构为 { name?, window?, used, limit, reset_at? }，其中 window 为 { duration, unit }，unit 为 minute / hour / day / week 之一。extra_usage（可空）是按量付费钱包：{ balance_cents, total_cents, monthly_charge_limit_enabled, monthly_charge_limit_cents, monthly_used_cents, currency }。

`GET /api/v1/oauth/userinfo`

托管账号的资料，带内 kind: "error" 约定与 GET /api/v1/oauth/usage 相同。

参数	位置	类型	说明
`provider`	query	string	托管供应商名称。默认 `managed:kimi-code`

成功时 data 为 { kind: "ok", userInfo } 或 { kind: "error", message, status? }。userInfo 始终携带 userId、nickname、status、region、userLevel、userLevelName、domain、domainName，并可能附加 globalId、bio、avatar、username、email、phone（{ countryCode, number }）、createdTime 与 lastLoginTime。

`GET /api/v1/oauth/region`

解析该客户端所属的 Kimi 区域。结果在本地推导，不经网络探测：优先取环境变量或配置固定的 OAuth host，其次是已配置的 OAuth key，再次是 home 目录中的区域标记文件；默认为 mainland-cn。

成功时 data 为 { region }，region 为 mainland-cn / global 之一。

配置

方法与路径	说明
`GET /api/v1/config`	读取全局配置（密钥字段脱敏）
`POST /api/v1/config`	合并式更新配置，并广播 `event.config.changed`

`GET /api/v1/config`

返回解析后的全局配置——config.toml 叠加覆盖层后的生效结果。密钥已脱敏：每个供应商只报告 has_api_key，绝不返回存储的密钥。

成功时 data 为配置对象；其字段与顶层字段记录的顶层域一一对应：

字段	类型	说明
`providers`	object	供应商 id → `{ type, base_url?, default_model?, has_api_key }` 的映射
`default_provider`	string	全局默认供应商 id
`default_model`	string	全局默认模型别名
`models`	object	模型别名 → 模型记录的映射
`thinking`	object	Thinking 模式的默认参数
`plan_mode`	boolean	Plan 模式开关
`yolo`	boolean	派生值：`default_permission_mode` 为 `yolo` 时为 `true`
`default_permission_mode`	string	新会话的默认权限模式
`default_plan_mode`	boolean	新会话是否以 Plan 模式启动
`permission`	object	初始权限规则
`hooks`	array	生命周期钩子
`services`	object	内置外部服务配置
`merge_all_available_skills`	boolean	是否合并所有可用目录中的 Agent Skills
`extra_skill_dirs`	array	额外的 Skill 搜索目录
`loop_control`	object	Agent 循环控制参数
`background`	object	后台任务运行参数
`subagent`	object	subagent 配置
`secondary_model`	object	subagent 的次级模型池
`experimental`	object	实验开关 id → 是否启用
`telemetry`	boolean	是否启用匿名遥测
`raw`	object	原始解析的 `config.toml` 内容，包含未建模字段

`POST /api/v1/config`

合并式更新全局配置：请求体中的每个顶层域被深合并进对应域，未出现在请求体中的域保持不动。把 yolo 设为 true 是 default_permission_mode: "yolo" 的简写；被拒绝的补丁（值非法或持久化失败）返回 40001 与底层错误信息。

每一次配置变更——经本端点成功更新、在进程外编辑 config.toml，或服务端内部写入（如 OAuth 登录刷新）——都会广播全局 event.config.changed 事件。短时间窗内的多次变更会合并为一个事件，其 changedFields 携带受影响的域名（camelCase 配置域，例如 defaultModel），config 携带当前完整的配置投影（与 GET /api/v1/config 响应同形状）。

请求体是部分配置对象——上述响应域中除 raw 外的任意子集，均为可选：

参数	位置	类型	说明
`providers`	body	object	供应商 id → 供应商表的映射
`default_provider`	body	string	全局默认供应商 id
`default_model`	body	string	全局默认模型别名
`models`	body	object	模型别名 → 模型记录的映射
`thinking`	body	object	Thinking 模式的默认参数
`plan_mode`	body	boolean	Plan 模式开关
`yolo`	body	boolean	`true` 映射为 `default_permission_mode: "yolo"`；`false` 被忽略
`default_permission_mode`	body	string	`manual` / `yolo` / `auto`
`default_plan_mode`	body	boolean	新会话是否以 Plan 模式启动
`permission`	body	object	初始权限规则
`hooks`	body	array	生命周期钩子
`services`	body	object	内置外部服务配置
`merge_all_available_skills`	body	boolean	是否合并所有可用目录中的 Agent Skills
`extra_skill_dirs`	body	array	额外的 Skill 搜索目录
`loop_control`	body	object	Agent 循环控制参数
`background`	body	object	后台任务运行参数
`subagent`	body	object	subagent 配置
`secondary_model`	body	object	subagent 的次级模型池
`experimental`	body	object	实验开关 id → 是否启用
`telemetry`	body	boolean	是否启用匿名遥测

成功时 data 为完整的更新后配置，形态与 GET /api/v1/config 相同。

模型与供应商

这组端点管理模型配置的两半——config.toml 的供应商表与模型别名表——外加一个由服务端代理的 models.dev 目录，用于一次性导入。模型别名 id 就是配置中的别名键：通过供应商管理端点创建的别名形如 provider_id/model（例如 my-provider/kimi-for-coding），而模型别名表中的裸键（如 turbo）原样使用；API 中任何接收 model_id 的地方（包括全局 default_model）指的都是这个别名 id。:{action} 路由上不支持的动作返回 40001。

方法与路径	说明
`GET /api/v1/models`	列出已配置的模型别名
`POST /api/v1/models/{model_id}:set_default`	设置全局默认模型
`GET /api/v1/providers`	列出供应商
`POST /api/v1/providers`	创建供应商（201）
`GET /api/v1/providers/{provider_id}`	读取供应商（含已存密钥）
`PUT /api/v1/providers/{provider_id}`	整体替换供应商配置
`DELETE /api/v1/providers/{provider_id}`	删除供应商（204）
`POST /api/v1/providers/{provider_id}:refresh`	刷新该供应商的模型元数据
`POST /api/v1/providers:{action}`	集合级动作：`refresh` / `refresh_oauth` / `import_catalog` / `import_registry`
`GET /api/v1/catalog/providers`	浏览 models.dev 目录（服务端代理）
`GET /api/v1/catalog/providers/{catalog_id}`	读取目录中单个条目

`GET /api/v1/models`

列出所有供应商下已配置的模型别名。

成功时 data.items 为 { provider, model, display_name?, max_context_size, capabilities?, support_efforts?, default_effort? } 数组：model 是别名 id（供应商管理的别名为 provider_id/model，否则为裸键），provider 是所属供应商 id，max_context_size 是以 token 计的上下文窗口，capabilities / support_efforts / default_effort 描述能力标志与 Thinking 模式的 effort 支持。

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

把全局 default_model 设为一个已存在的别名。model_id 是配置中的别名键原样——裸键如 POST /api/v1/models/turbo:set_default；当 id 含 / 时需做 URL 编码，如 POST /api/v1/models/my-provider%2Fkimi-for-coding:set_default。

参数	位置	类型	说明
`model_id`	path	string	必填。配置中的模型别名键原样；含 `/` 时需 URL 编码

成功时 data 为 { default_model, model }——当前生效的别名及其目录项（形态与 GET /api/v1/models 的单项相同）。

40001：路径中的动作后缀非法或不支持
40413：不存在该 id 的模型别名

`GET /api/v1/providers`

列出每个已配置供应商及其凭据与模型发现状态，不泄露任何密钥。这也是其他供应商端点引用的供应商条目形态。

成功时 data.items 为如下结构的数组：

字段	类型	说明
`id`	string	供应商 id
`type`	string	通信协议：`kimi` / `openai` / `openai_responses` / `anthropic` / `google-genai` / `vertexai`
`base_url`	string	API 基础 URL，如已设置
`default_model`	string	该供应商的默认模型别名，如已设置
`has_api_key`	boolean	是否已存储凭据
`status`	string	存在 API 密钥或缓存的 OAuth token 时为 `connected`，否则为 `unconfigured`（`error` 在 schema 中保留）
`models`	array	该供应商的模型别名 id

`POST /api/v1/providers`

一次保存创建供应商及其模型别名；响应为 HTTP 201 加标准信封。当全局 default_model 完全未配置时（全新安装），会以新供应商的 default_model（或第一个模型）播种；已有默认值绝不被修改。

参数	位置	类型	说明
`id`	body	string	必填。供应商 id——字母、数字、`-`、`_` 与空格；必须以字母或数字开头
`type`	body	string	必填。通信协议：`kimi` / `openai` / `openai_responses` / `anthropic` / `google-genai` / `vertexai`
`api_key`	body	string	API 密钥，存储于 `config.toml`
`base_url`	body	string	API 基础 URL；不得包含环境变量占位符（`${...}`）
`default_model`	body	string	该供应商的默认模型；必须是 `models[].model` 之一
`models`	body	array	必填。至少一条，不允许重复的 `model` 值；条目结构见下文

每个 models[] 条目声明一个别名，其 id 为 id/model：

字段	类型	说明
`model`	string	必填。上游模型名
`max_context_size`	integer	必填。以 token 计的上下文窗口，≥ 1
`display_name`	string	显示名
`capabilities`	array	能力标志，如 `thinking` 或 `image_in`
`max_output_size`	integer	最大输出 token 数，≥ 1
`support_efforts`	array	支持的 Thinking 模式 effort 档位
`adaptive_thinking`	boolean	自适应 thinking 开关

成功时 data 为创建好的供应商条目（形态与 GET /api/v1/providers 的单项相同）。

40921：已存在该 id 的供应商

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

读取单个供应商。与列表路由不同，设置了密钥时响应会暴露存储的 api_key，以便本地编辑表单预填——暴露端口时请牢记这一点。

参数	位置	类型	说明
`provider_id`	path	string	必填。供应商 id

成功时 data 为供应商条目，存有密钥时附带 api_key。

40412：供应商不存在

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

一次保存整体替换供应商：type、base_url 与模型列表被重写，该供应商的别名按 models 重建——不再列出的别名从 config.toml 中消失，其他供应商的别名不受影响。api_key 是三态的：省略表示保留已存密钥，"" 表示清除，其他值表示替换。除 new_id 重命名迁移外，全局默认指针绝不被修改。

参数	位置	类型	说明
`provider_id`	path	string	必填。当前供应商 id
`new_id`	body	string	重命名供应商；providers 键、模型别名、`default_provider`、指向旧别名的 `default_model` 以及 subagent 次级模型池都会随之迁移。id 规则与 `POST /api/v1/providers` 相同
`type`	body	string	必填。通信协议：`kimi` / `openai` / `openai_responses` / `anthropic` / `google-genai` / `vertexai`
`api_key`	body	string	三态，见上文
`base_url`	body	string	API 基础 URL；不得包含环境变量占位符（`${...}`）
`default_model`	body	string	该供应商的默认模型；必须是 `models[].model` 之一
`models`	body	array	必填。至少一条，不允许重复的 `model` 值；条目结构与 `POST /api/v1/providers` 相同

成功时 data 为 { provider }，即保存后的供应商条目。

40001：重命名后的别名 id 会与其他供应商的别名冲突
40003：供应商由 OAuth 托管——请改用 POST /api/v1/oauth/logout 登出
40412：供应商不存在
40921：new_id 已被占用

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

删除供应商及其全部模型别名；subagent 次级模型池会级联清理。全局 default_provider / default_model 指针保持不动，即使它们指向被删的供应商——那是用户的设置，不由本端点代为回收。

参数	位置	类型	说明
`provider_id`	path	string	必填。供应商 id

成功时服务应答 204 且无响应体——状态行本身即表示删除成功（见响应信封）。

40003：供应商由 OAuth 托管——请改用 POST /api/v1/oauth/logout 登出
40412：供应商不存在

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

从上游来源重新发现单个供应商的模型元数据，并重写该供应商的别名。模型来源为静态的供应商不经任何网络调用直接报告 unchanged。至少一个供应商的别名发生变化时，服务会广播全局 event.model_catalog.changed 事件。

参数	位置	类型	说明
`provider_id`	path	string	必填。供应商 id

成功时 data 为刷新报告：changed 是 { provider_id, provider_name, added, removed }（新增 / 移除的别名数）的数组，unchanged 是无差异的供应商 id 数组，failed 是 { provider, reason } 的数组。

40001：路径中的动作后缀非法或不支持
40412：供应商不存在

`POST /api/v1/providers:refresh`

刷新每个供应商的模型元数据。请求体可选且被忽略。

成功时 data 为与 POST /api/v1/providers/{provider_id}:refresh 相同的刷新报告（changed / unchanged / failed）。

`POST /api/v1/providers:refresh_oauth`

与 POST /api/v1/providers:refresh 相同的刷新，仅限 OAuth 凭据的供应商。请求体可选且被忽略。

成功时 data 为刷新报告（changed / unchanged / failed）。

`POST /api/v1/providers:import_catalog`

把一个 models.dev 目录条目导入为已配置供应商；响应为 HTTP 201 加标准信封。通信协议与端点来自目录解析，目录中的每个模型都写为一个别名。导入已存在的 id 等同于刷新——供应商条目及其别名按目录重写，省略 api_key 表示保留已存密钥。全局默认指针绝不被修改，仅在完全未配置默认模型时，以第一个导入的模型播种 default_model。

参数	位置	类型	说明
`catalog_id`	body	string	必填。来自 `GET /api/v1/catalog/providers` 的目录条目 id
`id`	body	string	覆盖目录 id 作为本地供应商 id。id 规则与 `POST /api/v1/providers` 相同
`api_key`	body	string	导入供应商的 API 密钥
`base_url`	body	string	覆盖目录解析出的端点；条目的 `needs_base_url` 为 `true` 时必填

成功时 data 为 { provider, models_imported }——供应商条目与写入的别名数量。

40001：缺少 catalog_id 或其他请求体校验失败
40003：目标供应商已存在且由 OAuth 托管
40004：条目无法导入（被拒绝、要求 base_url、没有可导入的模型，或其 id 不能用作供应商 id）
40417：不存在该 catalog_id 的目录条目
50004：models.dev 目录不可用

`POST /api/v1/providers:import_registry`

把一个 models.dev 形态的私有注册表——一个 api.json URL 加可选的 Bearer key——导入为已配置供应商；响应为 HTTP 201 加标准信封。每个列出的供应商都带 source 记录写入，以便定时刷新重新发现。重复导入同一 URL 会移除上游已消失的供应商——URL 是注册表的稳定身份，因此轮换 key 是安全的。全局默认指针遵循与 :import_catalog 相同的规则。

参数	位置	类型	说明
`url`	body	string	必填。注册表 `api.json` 的 URL
`api_key`	body	string	注册表的 Bearer key；省略时复用上一次导入同一 URL 所用的 key

成功时 data 为 { providers, models_imported }——供应商条目数组与写入的别名总数。

40001：缺少 url 或其他请求体校验失败
40003：某个列出的供应商已存在且由 OAuth 托管
40005：注册表无法获取或解析，或未列出可导入的供应商

`GET /api/v1/catalog/providers`

浏览 models.dev 目录，由服务端代理，带 10 分钟内存缓存与内置快照兜底。条目保持上游目录顺序。服务无法导入的条目携带 rejected: true 与机器可读的 reject_reason；needs_base_url: true 的条目在导入时要求提供 base URL。

成功时 data.items 为 { id, name, wire_type, guessed, needs_base_url, rejected, reject_reason, env_key, models } 数组：wire_type 是解析出的协议（可空，枚举与供应商 type 相同），guessed 标记启发式解析，env_key 是上游约定的 API 密钥环境变量（可空），models 是 { id, name?, max_context_size, capabilities?, reasoning } 的数组。

50004：目录不可用（在线拉取与内置快照均失败）

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

按 catalog id 读取单个 models.dev 目录条目——条目形态与 GET /api/v1/catalog/providers 相同。

参数	位置	类型	说明
`catalog_id`	path	string	必填。目录条目 id

成功时 data 为该目录条目（形态与 GET /api/v1/catalog/providers 的单项相同）。

40417：不存在该 catalog_id 的目录条目
50004：目录不可用

会话

这些端点用于创建、列出和查看会话，执行会话级动作（fork、compact、undo 等），并读取会话级汇总。其中大多数返回的会话采用 session 对象中统一说明的线上格式；非 CRUD 操作使用上文介绍的 :{action} 约定。

方法与路径	说明
`POST /api/v1/sessions`	创建会话（需 `workspace_id` 或 `metadata.cwd`）
`GET /api/v1/sessions`	列出会话，游标分页，支持 `busy` / `archived_only` 等过滤
`GET /api/v1/sessions/{session_id}`	读取单个会话
`GET /api/v1/sessions/{session_id}/profile`	读取会话档案
`POST /api/v1/sessions/{session_id}/profile`	更新标题、元数据、Agent 配置
`POST /api/v1/sessions/{session_id}/title/generate`	通过托管的 `chat_title` 工具生成标题
`POST /api/v1/sessions/{session_id}:{action}`	会话动作：`fork` / `compact` / `undo` / `abort` / `btw` / `archive` / `restore`
`GET /api/v1/sessions/{session_id}/children`	列出子会话
`POST /api/v1/sessions/{session_id}/children`	创建子会话（fork 并打标）
`GET /api/v1/sessions/{session_id}/status`	实时状态汇总
`GET /api/v1/sessions/{session_id}/goal`	当前目标快照（无则 `null`）
`GET /api/v1/sessions/{session_id}/warnings`	会话级告警
`GET /api/v1/sessions/{session_id}/runtime`	读取 main agent 的运行时绑定
`POST /api/v1/sessions/{session_id}/runtime`	切换 main agent 的运行时绑定
`POST /api/v1/sessions/{session_id}/export`	导出会话与诊断信息（zip 流，不走信封）
`GET /api/v1/sessions/{session_id}/snapshot`	客户端重建用全量快照（含 `as_of_seq` 与 `epoch`）
`GET /api/v1/sessions/{session_id}/media/{file_id}`	按文件 id 下载提示词媒体（二进制）

session 对象

每个返回会话的端点都使用这种线上格式。实时状态字段（busy、main_turn_active、pending_interaction、last_turn_reason）由会话的活动聚合解析得出：未加载到本服务进程中的会话（冷会话）始终上报为不忙碌且无待处理交互。少数字段在当前投影中是占位值——已逐字段注明。

字段	类型	说明
`id`	string	会话 id（`session_...`）
`workspace_id`	string	所属工作区 id
`title`	string	会话标题；无标题时为 `""`
`created_at` / `updated_at`	string	创建时间与最后更新时间，ISO 8601
`archived`	boolean	会话是否已归档（归档后从默认会话列表中隐藏）
`archived_at`	string	归档时间，ISO 8601；仅在已归档时存在
`busy`	boolean	是否有任一 Agent 存在进行中的轮次或后台任务
`main_turn_active`	boolean	main agent 是否有进行中的轮次
`pending_interaction`	string	`none` / `approval` / `question`——有未答复的交互在等待
`last_turn_reason`	string	main agent 最近一次轮次的结果：`completed` / `cancelled` / `failed`
`last_prompt`	string	最近一条用户提示词文本（如有）
`metadata`	object	自定义元数据；始终携带 `cwd`（会话的工作目录）
`agent_config`	object	投影为 `{ model }`；`model` 在大多数响应中为 `""`，仅由 `GET /api/v1/sessions/{session_id}/snapshot` 填入实时模型
`usage`	object	token 汇总 `{ input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, context_tokens, context_limit?, total_cost_usd?, turn_count? }`；在 snapshot 端点之外全为零
`permission_rules`	array	会话权限规则；当前始终为 `[]`
`message_count`	integer	消息数；当前始终为 `0`
`last_seq`	integer	最后的事件序列号；当前始终为 `0`

`POST /api/v1/sessions`

创建会话并返回。目标目录来自 workspace_id（已注册的工作区）或 metadata.cwd（首次使用时注册该工作区）；两者同时提供时必须一致。创建时会广播全局 event.session.created 事件。

参数	位置	类型	说明
`workspace_id`	body	string	未提供 `metadata.cwd` 时必填。已注册的工作区 id；会话创建于该工作区的根目录
`metadata`	body	object	自定义元数据。`metadata.cwd` 为工作目录，未提供 `workspace_id` 时必填；两者同时提供时必须等于工作区根目录
`title`	body	string	初始标题（至少 1 个字符）；否则会话无标题
`agent_config`	body	object	schema 接受该字段但当前不会应用——模型与各模式请通过 `POST /api/v1/sessions/{session_id}/profile` 设置

成功时，data 为新会话的 session 对象。

40001：workspace_id 与 metadata.cwd 都未提供，或 metadata.cwd 与工作区根目录不一致（details 会列出该字段）
40409：工作目录不存在或不是目录
40410：没有以该 workspace_id 注册的工作区

`GET /api/v1/sessions`

跨工作区列出会话，按 updated_at 最新在前。游标分页遵循分页，但有一个特例：不提供 page_size（且不提供 archived_only）时，响应是单个不分页的窗口，其 has_more 恒为 false，因此要真正翻页请传入 page_size。

参数	位置	类型	说明
`before_id`	query	string	只保留早于该 id 的会话；与 `after_id` 互斥
`after_id`	query	string	只保留晚于该 id 的会话；与 `before_id` 互斥
`page_size`	query	integer	1–100。分页生效时默认为 `20`；不分页的默认行为见上文说明
`busy`	query	boolean	只保留忙碌（或只保留空闲）的会话
`include_archive`	query	boolean	在活跃会话之外同时包含已归档会话。默认 `false`
`archived_only`	query	boolean	只保留已归档会话；与 `include_archive` 互斥；即使不提供 `page_size` 也会启用游标分页
`exclude_empty`	query	boolean	去掉没有任何用户提示词的会话
`workspace_id`	query	string	限定到单个工作区（别名会被解析）

成功时，data 为 { items, has_more }，其中每个元素为 session 对象。

40001：校验失败——例如 before_id 与 after_id 同用，或 archived_only 与 include_archive 同用
40410：未知的 workspace_id

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

从索引中读取单个会话。会话已加载到本进程时会包含实时状态字段；冷会话上报为不忙碌，并携带其最后持久化的轮次结果。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 session 对象。

40401：会话不存在，或其工作区已无法解析

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

读取会话档案——与 GET /api/v1/sessions/{session_id} 相同的线上载荷。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 session 对象。

40401：会话不存在

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

更新会话档案：标题、自定义元数据以及 main agent 的配置。在这里设置的标题会成为自定义标题，优先级高于生成的标题；设置标题会广播全局 session.meta.updated 事件。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`title`	body	string	新标题（至少 1 个字符）；会成为自定义标题
`metadata`	body	object	合并进会话自定义元数据的键
`agent_config`	body	object	main agent 的部分配置；字段如下，均为可选

每个 agent_config 字段都会立即应用到 main agent：

字段	类型	说明
`model`	string	模型别名 id；空字符串会被忽略
`thinking`	string	Thinking 强度等级
`permission_mode`	string	`manual` / `yolo` / `auto`
`plan_mode`	boolean	进入或退出 Plan 模式
`swarm_mode`	boolean	进入或退出 swarm 模式
`goal_objective`	string	以该文本为内容创建一个目标
`goal_control`	string	`pause` / `resume` / `cancel` 当前目标

schema 还接受 agent_config 内的 system_prompt、tools、mcp_servers，以及顶层的 permission_rules 数组，但更新路由当前不会应用它们。

成功时，data 为更新后的 session 对象。

40401：会话不存在

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

通过托管供应商的 chat_title 工具根据会话的提示词生成标题并应用，同时广播 session.meta.updated。生成需要托管 OAuth 登录；未提供 force 时，已有自定义标题或已生成标题的会话会上报为不可用，而不会被覆盖。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`force`	body	boolean	即使已有自定义或生成的标题也重新生成。默认 `false`
`source`	body	string	标题输入：`user_prompts`（默认）/ `first_turn` / `digest`

成功时，data 为 { title }——当前应用到会话的标题。

40401：会话不存在
40923：生成不可用——开关未开启、没有托管 OAuth 登录或尚无任何提示词内容、已有标题但未提供 force，或后端请求失败

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

会话动作通过同一条路由分发：路径尾部解析为 {session_id}:{action}，请求体按该动作的 schema 校验，动作缺失或未知时返回 40001（unsupported action: ...）。每个动作都会先解析会话，因此会话未知时都可能返回 40401。支持的动作在下面逐一说明。

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

将会话——其转录、Agent 状态与文件——复制到同一工作区中的新会话，并广播 event.session.created。当会话中任一 Agent 有进行中的轮次时，fork 会被拒绝。

参数	位置	类型	说明
`title`	body	string	fork 的标题（至少 1 个字符）。默认 `Fork: <source title>`
`metadata`	body	object	fork 的自定义元数据

成功时，data 为新会话的 session 对象。

40901：会话有进行中的轮次，无法 fork

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

对 main agent 的上下文发起一次手动全量压缩。调用立即返回；进度与完成通过 compaction.* WebSocket 事件投递。

参数	位置	类型	说明
`instruction`	body	string	给压缩摘要的额外指引；空值会被忽略

成功时，data 为空对象。

40910：有轮次或其他上下文变更正在进行，或历史中没有可压缩的内容

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

将 main agent 的对话回退 count 个轮次，并同步修正派生的会话状态（包括会话的 last_prompt）。

参数	位置	类型	说明
`count`	body	integer	要撤销的轮次数；正整数。默认 `1`
`page_size`	body	integer	返回的历史窗口大小，1–100。默认 `50`

成功时，data 为 { messages, status }：messages 是剩余上下文消息按最新在前的 { items, has_more } 分页，status 与 GET /api/v1/sessions/{session_id}/status 的汇总相同。

40901：有轮次正在进行或压缩正在运行——等其结束后重试
40911：无法撤销那么多轮次（遇到压缩边界或检查点丢失）；data 携带 { reason, requestedCount, undoableCount }

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

取消 main agent 正在运行的轮次——等同于用户在 TUI 中中止轮次的程序化版本。

成功时，data 为 { aborted: true }。

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

开启一个 "by the way" 旁路对话：把 main agent fork 成一个仅可使用只读工具（Read、Grep、Glob）的子 Agent，让快速的临时问题在隔离环境中运行，不触碰工作上下文。需要可用的模型配置。

成功时，data 为 { agent_id }——新子 Agent 的 id。

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

将会话标记为已归档：它从默认会话列表中消失（使用 include_archive 或 archived_only 时仍会列出），并且服务端广播全局 event.session.archived 事件。

成功时，data 为 { archived: true }。

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

取消会话的归档状态并恢复它。

成功时，data 为 archived: false 的 session 对象。

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

列出会话的子会话——即通过 POST /api/v1/sessions/{session_id}/children 创建的会话。游标分页遵循分页。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`before_id`	query	string	只保留早于该 id 的子会话；与 `after_id` 互斥
`after_id`	query	string	只保留晚于该 id 的子会话；与 `before_id` 互斥
`page_size`	query	integer	1–100。默认 `100`
`busy`	query	boolean	只保留忙碌（或只保留空闲）的子会话

成功时，data 为 { items, has_more }，其中每个元素为 session 对象。

40401：会话不存在

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

创建子会话：fork 当前会话并记录为其子会话，因此会出现在 GET /api/v1/sessions/{session_id}/children 下。适用与 :fork 相同的进行中轮次限制。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`title`	body	string	子会话的标题（至少 1 个字符）。默认 `Child: <source title>`
`metadata`	body	object	子会话的自定义元数据

成功时，data 为新会话的 session 对象，并且服务端广播 event.session.created。

40901：会话有进行中的轮次，无法 fork

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

main agent 的实时状态汇总；读取它会在会话为冷态时将其恢复。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 { busy, model?, thinking_level, permission, plan_mode, swarm_mode, context_tokens, max_context_tokens?, context_usage? }：busy 表示是否有进行中的轮次，model / thinking_level / permission 为当前生效的 Agent 设置，plan_mode / swarm_mode 为模式标志，context_tokens 与 max_context_tokens、context_usage（0–1）描述上下文窗口的占用情况。

40401：会话不存在

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

读取会话当前的目标快照；没有活跃目标时为 null。注意，与本 API 的大多数载荷不同，该载荷使用 camelCase 键。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 null 或 { goalId, objective, completionCriterion?, status, turnsUsed, tokensUsed, wallClockMs, budget, terminalReason? }，其中 status 为 active / paused / blocked / complete，budget 报告 token、轮次与 wall-clock 三项预算，以及各自的剩余量与每项预算的 reached 标志（未设置对应预算时各项为 null）。

40401：会话不存在

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

读取会话级告警。目前的产生者只有 AGENTS.md 过大检查（agents-md-oversized），因此大多数会话的列表为空。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 { warnings }，每个条目为 { code, message, severity }，其中 severity 为 info / warning / error 之一。

40401：会话不存在

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

读取 main agent 的运行时绑定——即该会话的 Agent 循环运行在哪个运行时上。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 { workspace_id, runtime_id }。

40401：会话不存在

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

切换 main agent 的运行时绑定。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`runtime_id`	body	string	必填。目标运行时 id

成功时，data 为新的绑定 { workspace_id, runtime_id }。

40420：不存在该 runtime_id 的运行时
40926：运行时存在但不可用

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

将会话连同诊断日志一起导出为 zip 附件（kimi-session-<id>.zip）。响应是二进制流，不是 JSON 信封——能力与失败语义见二进制与流式端点。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`web_log`	body	string	要包含在归档中的客户端日志文本，最多 256 KB UTF-8
`desktop`	body	boolean	同时包含桌面宿主的日志。默认 `false`

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

为重新同步后重建客户端组装一份原子快照：会话、最近的消息、进行中的轮次、存活的 subagent 以及待处理交互，全部盖上 as_of_seq 水位与用于重新订阅的 epoch——见断线恢复。与普通的会话端点不同，内嵌的会话携带实时的 agent_config.model 与真实的 usage 总计。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 { as_of_seq, epoch, session, messages, in_flight_turn, subagents?, pending_approvals, pending_questions }：session 为 session 对象，messages 为最新 100 条消息的 { items, has_more }，in_flight_turn 为已部分流式输出的轮次（空闲时为 null，已知时带 current_prompt_id），subagents 列出存活的 subagent 任务，pending_approvals / pending_questions 承载未答复的交互。

40401：会话不存在

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

按文件 id 下载提示词媒体文件（会话提示词引用的图片或其他附件）；尚未提交到会话的 id 会回退到暂存的上传中查找。响应为二进制并支持 Range（范围请求返回 206）——共享约定见二进制与流式端点；与那里走信封的端点不同，会话或文件不存在时会返回真正的 404 状态码并携带信封体。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`file_id`	path	string	必填。媒体文件 id

消息与转录

messages 端点分页返回 main agent 的扁平化消息历史，transcript 端点则提供按 Agent 组织的结构化转录——轮次、任务、交互、附件——即 WebSocket 转录协议实时流式推送的内容。历史分页与补漏用这些端点，实时尾部用 WebSocket 订阅。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/messages`	消息分页（`before_id` / `after_id` / `role`）
`GET /api/v1/sessions/{session_id}/messages/{message_id}`	读取单条消息
`GET /api/v1/sessions/{session_id}/transcript`	按轮次分页的转录（需 `agent_id`）；全局状态不分页随响应返回
`GET /api/v1/sessions/{session_id}/transcript/ops`	op 批次补漏（`since_seq`）；`complete: false` 表示需要全量刷新
`GET /api/v1/sessions/{session_id}/transcript/user-messages`	各轮次起始的用户输入，不分页
`GET /api/v1/sessions/{session_id}/transcript/plan`	ExitPlanMode 计划内容、路径与审阅结果

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

分页返回 main agent 的消息历史——与会话快照共享的扁平化上下文转录——最新在前。游标分页遵循分页；读取历史会在会话为冷态时将其恢复。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`before_id`	query	string	只保留早于该消息 id 的消息；与 `after_id` 互斥
`after_id`	query	string	只保留晚于该消息 id 的消息；与 `before_id` 互斥
`page_size`	query	integer	1–100。默认 `50`
`role`	query	string	只保留单一角色：`user` / `assistant` / `tool` / `system`。过滤在分页切片之后应用，因此过滤后的一页可能少于 `page_size` 条而 `has_more` 仍为 `true`——持续翻页直到 `has_more` 为 `false`

成功时，data 为 { items, has_more }，其中每个元素是消息对象 { id, session_id, role, content, created_at, prompt_id?, parent_message_id?, metadata? }；content 是按提示词中说明的线上格式组成的内容块数组（text、tool_use、tool_result、image、video、file、thinking）。

40001：校验失败——例如 before_id 与 after_id 同用
40401：会话不存在

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

按 id 从同一历史中读取单条消息。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`message_id`	path	string	必填。消息 id

成功时，data 为上文 GET /api/v1/sessions/{session_id}/messages 中说明的元素形态的消息对象。

40401：会话不存在
40403：该会话中不存在此 id 的消息

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

返回某个 Agent 的结构化转录中的一页：轮次（含其步骤与帧）以及轮次之间的标记与任务引用。活跃会话从内存存储应答（先回填所请求 Agent 的持久化历史）；冷会话则从持久化的线上记录重建 Agent。这是转录能力的历史半边——实时流式半边是转录协议订阅。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`agent_id`	query	string	必填。要读取其转录的 Agent；必须是纯文本形式的 agent id（字母、数字、`.`、`_`、`-`——不含路径分隔符）
`before_turn`	query	string	只保留早于该轮次 id 的轮次；与 `after_turn` 互斥
`after_turn`	query	string	只保留晚于该轮次 id 的轮次；与 `before_turn` 互斥
`page_size`	query	integer	1–100 个轮次。默认 `20`

分页单位是轮次：不带游标时返回最新的一页，has_more 表示还有更早的轮次。成功时，data 为 { agent_id, items, has_more, tasks, interactions, attachments, todos, meta, agents, pending_interactions, seq? }——items 是本次分页的轮次切片，tasks / interactions / attachments / todos / meta / agents / pending_interactions 是不分页、随每次响应一起返回的全局 Agent 状态，seq 是该 Agent 用于恢复流的 op 批次水位（仅活跃会话）。

40001：校验失败——before_turn 与 after_turn 同用，或 agent_id 不是纯文本形式
40401：会话不存在

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

从服务端的 op 日志提供点对点的补漏：某个 Agent 的 seq > since_seq 的已记录 op 批次，最旧在前。它是转录协议中 transcript_since 恢复游标的 REST 对应物，共享同一份有界日志，因此适用相同的回退规则。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`agent_id`	query	string	必填。 Agent id（纯文本形式，约束与转录端点相同）
`since_seq`	query	integer	必填。调用方已应用的最后一个 op 批次 seq，最小为 `0`；返回其之后的批次

成功时，data 为 { agent_id, batches, latest_seq, complete }，每个批次为 { seq, ops }。complete: true 表示直到 latest_seq 的每个批次都在；complete: false 表示日志已不再覆盖到 since_seq（或会话根本不是活跃状态），调用方必须回退为一次完整的 GET .../transcript 刷新。

40001：校验失败
40401：会话不存在

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

列出会话中每个开启轮次的输入，按 Agent 分组且不分页：真实用户文本、以斜杠命令形式使用的 Skill 与插件命令、以及 cron 提示词——可通过 origin 区分——另有仅含附件的提示词，其 prompt 投影为空。所列消息引用的附件实体会随响应一起返回（仅元数据，绝不包含字节内容）。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`agent_id`	query	string	只读取一个 Agent（纯文本 id）。默认读取所有在册 Agent

成功时，data 为 { agents }，每个条目为 { agent_id, messages, attachments }；消息为 { turn_id, ordinal, state, origin, prompt, attachment_ids?, started_at? }，其中 state 为轮次状态（queued / running / completed / failed / cancelled）。

40001：校验失败——agent_id 不是纯文本形式
40401：会话不存在

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

按时间线顺序读取某个 Agent 的 ExitPlanMode 工具调用的计划信息——计划内容、计划文件路径、提供的选项以及审阅结果。内容投影自第一个可用的事实来源：关联的审批交互（交互式审阅）、实时工具帧的展示（auto 模式），或工具结果的输出文本；每个条目在 source 中记录了具体来源。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`agent_id`	query	string	必填。 Agent id（纯文本形式）
`tool_call_id`	query	string	将读取范围限定到单次 `ExitPlanMode` 调用；不提供时列出所有可恢复计划内容的调用

成功时，data 为 { agent_id, plans }，每个计划为 { tool_call_id, turn_id, source, plan, path?, options?, review? }：source 为 interaction / display / output，options 是审阅选项，形如 { label, description? }，review（仅交互式审阅时存在）为 { state, selected_option?, feedback? }，其中 state 为 pending / approved / rejected / cancelled 之一。

40001：校验失败
40401：会话不存在
40416：提供了 tool_call_id，但不存在该 id 的 ExitPlanMode 调用

提示词

提示词是一次用户输入的单位：提交一条提示词会把它排入会话的 main agent（或指定 Agent）的队列，排队中的提示词可以插入进行中的轮次，运行中的提示词可以中止。轮次进度本身通过 WebSocket 事件流式推送，不经过这些端点。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/prompts`	进行中与排队中的提示词
`POST /api/v1/sessions/{session_id}/prompts`	提交提示词（内容块数组，可带模型 / 权限模式覆盖）
`POST /api/v1/sessions/{session_id}/prompts:steer`	把排队的提示词插入进行中的轮次
`POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:abort`	中止运行中的提示词
`POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:steer`	插入单条排队的提示词

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

读取 main agent 的提示词队列快照。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时，data 为 { active, queued }：active 是运行中的提示词（空闲时为 null），queued 按顺序列出等待中的提示词。提示词为 { prompt_id, user_message_id, status, content, created_at }，其中 status 为 running / queued / blocked 之一，content 采用 POST /api/v1/sessions/{session_id}/prompts 接受的内容块格式。

40401：会话不存在

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

向会话提交一条用户提示词。先校验媒体引用，然后把可选的覆盖项应用到目标 Agent——profile（与 model / thinking 一起绑定），接着是 model、thinking、permission_mode 和 disabled_tools——随后提示词入队；响应在提示词被接受后立即返回，不等待轮次执行。提供 skills 时，提示词以打包的 Skill 激活方式运行，而不是普通用户提示词。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`content`	body	array	必填。非空的内容块数组；变体见下
`agent_id`	body	string	目标 Agent。默认为 main agent
`prompt_id`	body	string	客户端选定的提示词 id，用于幂等提交；已被进行中提示词占用的 id 返回 `40927`，已完成的返回 `40903`。不能与 `skills` 同用
`skills`	body	array	打包的 Skill 激活，至少 1 个 `{ name, args? }` 条目；每个 Skill 必须存在且可由用户激活
`profile`	body	string	提交前要绑定的 Agent 档案
`model`	body	string	要切换到的模型别名
`thinking`	body	string	Thinking 强度等级
`permission_mode`	body	string	`manual` / `yolo` / `auto`
`disabled_tools`	body	array	要为会话禁用的工具名

schema 还接受 metadata、plan_mode、swarm_mode、goal_objective 和 goal_control，但提交路由当前不会应用它们。每个 content 内容块是按 type 区分的对象：

内容块	字段	说明
`text`	`text`	纯文本
`image` / `video`	`source`	媒体输入；`source` 为 `{ kind: "url", url, id? }`、`{ kind: "base64", media_type, data }`、`{ kind: "file", file_id }`（来自 `POST /api/v1/files` 的上传）或 `{ kind: "session_media", file_id }`（已提交到本会话的媒体）之一
`file`	`file_id`、`name`、`media_type`、`size`	通过 `POST /api/v1/files` 上传的文件附件

schema 还接受共享消息格式中的 tool_use、tool_result 和 thinking 内容块，但它们在用户提示词中没有意义。未知或 kind 不匹配的 file_id 引用会在提示词创建之前、任何覆盖项应用之前被拒绝。

成功时，data 为被接受的提示词 { prompt_id, user_message_id, status, content, created_at }。

40001：校验失败——例如 prompt_id 与 skills 同用，或未知的 profile
40110：尚未配置供应商——请先完成登录
40111：解析出的供应商没有凭据（details.provider_id）
40112：供应商的凭据被拒绝（details.provider_id）
40113：模型无法解析（已知时带 details.model_id / details.provider_id）
40401：会话不存在
40407：引用的 file_id 不存在（或与内容块的媒体 kind 不匹配）
40415：某个 skills 条目指向未知的 Skill
40903：prompt_id 属于已完成的提示词；data 携带 { aborted: false }
40912：Skill 存在但无法由用户激活
40927：prompt_id 已被进行中的提示词占用

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

把排队的提示词插入进行中的轮次，让运行中的轮次立即消费它们，而不是先运行结束。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`prompt_ids`	body	array	必填。非空的排队提示词 id 数组

成功时，data 为 { steered: true, prompt_ids }。

40001：校验失败
40401：会话不存在
40402：所列提示词 id 不在队列中

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

中止运行中的提示词。本端点与下面的 :steer 通过同一条路由 POST /api/v1/sessions/{session_id}/prompts/{tail} 分发：尾部解析为 {prompt_id}:{action}，动作缺失或未知时返回 40001（unsupported action: ...）。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`prompt_id`	path	string	必填。提示词 id

成功时，data 为 { aborted: true }。

40401：会话不存在
40402：不存在该 id 的提示词
40903：提示词已完成；data 携带 { aborted: false }

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

把单条排队的提示词插入进行中的轮次——是 POST /api/v1/sessions/{session_id}/prompts:steer 的单提示词形式。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`prompt_id`	path	string	必填。排队中的提示词 id

成功时，data 为 { steered: true, prompt_ids: [prompt_id] }。

40401：会话不存在
40402：没有该 id 的排队提示词

审批与提问

审批与提问是会话的两类待处理交互：审批是为工具调用请求许可，提问是请求带标签选项的结构化输入。这些端点用于列出和答复它们；新的请求通过 WebSocket 以 event.approval.requested 与 event.question.requested 到达。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/approvals`	列出待处理的审批请求（必须 `status=pending`）
`POST /api/v1/sessions/{session_id}/approvals/{approval_id}`	答复审批
`GET /api/v1/sessions/{session_id}/questions`	列出待处理的提问（必须 `status=pending`）
`POST /api/v1/sessions/{session_id}/questions/{question_id}`	回答提问
`POST /api/v1/sessions/{session_id}/questions/{question_id}:dismiss`	忽略提问

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

列出会话待处理的审批请求——即工具调用发起的权限提示。读取列表会在会话为冷态时将其恢复。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`status`	query	string	必填。必须为 `pending`

成功时，data 为 { items }，每个元素为 { 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 描述等待许可的调用，expires_at 为 created_at 之后 24 小时。

40001：status 缺失或不是 pending
40401：会话不存在

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

答复一个待处理的审批请求，让等待中的工具调用继续执行（或不执行）。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`approval_id`	path	string	必填。审批请求 id
`decision`	body	string	必填。 `approved` / `rejected` / `cancelled`
`scope`	body	string	配合 `approved` 使用，`session`（唯一取值）还会让该审批规则在会话的剩余时间内被记住
`feedback`	body	string	回传给 Agent 的自由文本反馈
`selected_label`	body	string	当请求提供了带标签的选项时（例如计划审阅），所选选项的标签

成功时，data 为 { resolved: true, resolved_at }。

40001：校验失败
40401：会话不存在
40404：没有该 id 的待处理审批
40902：审批已被答复；data 携带 { resolved: false }

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

列出会话待处理的提问。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`status`	query	string	必填。必须为 `pending`

成功时，data 为 { items }，每个元素为 { question_id, session_id, turn_id?, tool_call_id?, questions, created_at }。questions 包含 1–4 个 { id, question, header?, body?, options, multi_select?, allow_other?, other_label?, other_description? } 条目，每个条目带 2–4 个 { id, label, description? } 形式的 options；multi_select 允许选择多个选项，allow_other 允许自由文本回答。

40001：status 缺失或不是 pending
40401：会话不存在

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

回答一个待处理的提问。两个提问端点通过同一条路由 POST /api/v1/sessions/{session_id}/questions/{tail} 分发：单独的提问 id 表示回答问题，{question_id}:dismiss 尾部表示忽略问题，其他情况返回 40001。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`question_id`	path	string	必填。提问 id
`answers`	body	object	必填。提问条目 id（`q_0`……）到答案对象的映射；变体见下
`method`	body	string	答案的产生方式：`enter` / `space` / `number_key` / `click`
`note`	body	string	附在回答上的自由文本备注

每个答案是按 kind 区分的对象：

kind 值	字段	说明
`single`	`option_id`	选中的单个选项
`multi`	`option_ids`	选中的多个选项（至少 1 个）
`other`	`text`	自由文本回答
`multi_with_other`	`option_ids`、`other_text`	选项加自由文本
`skipped`	—	跳过了该条目

成功时，data 为 { resolved: true, resolved_at }。

40001：校验失败（details 列出每个字段）
40401：会话不存在
40405：没有该 id 的待处理提问
40902：提问已被答复；data 携带 { resolved: false }

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

忽略一个待处理的提问，不作回答。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`question_id`	path	string	必填。提问 id

成功时信封的 code 是 40909（question dismissed）而不是 0，data 为 { dismissed: true, dismissed_at }——客户端必须特殊处理该端点的成功码。

40401：会话不存在
40405：没有该 id 的待处理提问
40902：提问已被答复；data 携带 { resolved: false }

后台任务

后台任务是会话的异步单元——后台 Shell、subagent 与长时间运行的工具任务。注册表仅包含实时数据：未加载到本服务进程中的会话会返回空列表。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/tasks`	列出后台任务
`GET /api/v1/sessions/{session_id}/tasks/{task_id}`	读取任务（可选输出预览）
`POST /api/v1/sessions/{session_id}/tasks/{task_id}:cancel`	取消任务
`POST /api/v1/sessions/{session_id}/tasks/{task_id}:detach`	将前台任务转入后台

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

列出会话的后台任务。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`status`	query	string	只保留单一状态：`running` / `completed` / `failed` / `cancelled`

成功时，data 为 { items }，每个元素是任务对象 { 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 为 bash / subagent / tool；command 仅在 bash 任务时设置，模型与 Agent 字段仅在 subagent 任务时设置，输出字段仅在以 with_output 读取任务时设置。超时与丢失的任务上报为 failed；被杀死的任务上报为 cancelled。

40001：校验失败——未知的 status
40401：会话不存在

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

读取单个后台任务，可选携带输出的末尾片段。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`task_id`	path	string	必填。任务 id
`with_output`	query	boolean	在响应中包含输出末尾片段。默认 `false`
`output_bytes`	query	integer	请求的输出末尾片段的字节大小，最小 `0`。默认 `32768`

成功时，data 为上文 GET /api/v1/sessions/{session_id}/tasks 中说明的任务对象；当 with_output=true 且输出非空时，output_preview 携带末尾片段文本，output_bytes 为其字节长度。

40001：校验失败
40401：会话不存在
40406：没有该 id 的任务（冷会话完全没有实时任务）

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

取消运行中的任务。它通过 POST /api/v1/sessions/{session_id}/tasks/{tail} 分发，支持 cancel / detach 两个动作——单独的任务 id 或未知动作返回 40001。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`task_id`	path	string	必填。任务 id

成功时，data 为 { cancelled: true }。

40001：动作后缀缺失或未知
40401：会话不存在
40406：没有该 id 的任务
40904：任务已结束；data 携带 { cancelled: false }，details.current_status 为最终状态

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

将运行中的前台任务转入后台而不终止它：等待该任务的工具调用会立即以后台任务结果返回，轮次继续推进，任务则在后台任务注册表下继续运行（输出持久化，完成时以任务通知投递）。已在后台或已结束的任务为幂等空操作。它通过 POST /api/v1/sessions/{session_id}/tasks/{tail} 分发，支持 cancel / detach 两个动作——单独的任务 id 或未知动作返回 40001。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`task_id`	path	string	必填。任务 id

成功时，data 为 { detached, status }：本次调用确实将运行中的前台任务转入后台时 detached 为 true，幂等空操作时为 false；status 为调用后的任务状态。

40001：动作后缀缺失或未知
40401：会话不存在
40406：没有该 id 的任务

技能、工具与 MCP

这组端点暴露会话或工作区可见的技能目录、当前生效 agent 的工具列表及其 MCP 服务。技能激活与 MCP 重启使用 :{action} 约定；激活即斜杠命令 /<skill> 的 REST 等价形式。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/skills`	会话级技能目录
`GET /api/v1/workspaces/{workspace_id}/skills`	无会话的工作区技能目录
`POST /api/v1/sessions/{session_id}/skills/{skill_name}:activate`	激活技能（开启一个轮次）
`GET /api/v1/tools`	列出当前生效 agent 的工具
`GET /api/v1/mcp/servers`	列出 MCP 服务
`POST /api/v1/mcp/servers/{mcp_server_id}:restart`	重启 MCP 服务

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

列出单个会话可用的技能，按会话的优先级合并所有来源（内置、插件、extra、用户、项目）。会话处于冷态时，读取目录会恢复该会话。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时 data 为 { skills }，每项是一个技能描述符 { name, description, path, source, type?, disable_model_invocation? }：source 为 project / user / extra / builtin；type 标识技能类别（只有用户可激活的类型才能被激活）；disable_model_invocation 会让技能对模型不可见。

40401：会话不存在（或未激活）

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

列出该工作区中的会话将看到的技能目录，但不创建或恢复会话——即针对工作区根目录计算出的同一套内置、插件、extra、用户、项目来源合并结果。

参数	位置	类型	说明
`workspace_id`	path	string	必填。已注册工作区 id

成功时 data 为 { skills }，技能描述符见上文 GET /api/v1/sessions/{session_id}/skills 的说明。

40410：工作区不存在

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

在会话中激活技能——即斜杠命令 /<skill> 的 REST 等价形式——以技能内容加上 args 与附件在 main agent 上开启一个轮次。该端点经单一路由 POST /api/v1/sessions/{session_id}/skills/{tail} 分发：尾部按 {skill_name}:{action} 解析，activate 是唯一动作；只给名称或动作未知时返回 40001（unsupported action: ...）。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`skill_name`	path	string	必填。要激活的技能名
`args`	body	string	传给技能的自由文本参数，相当于斜杠命令后的文本
`attachments`	body	array	随激活携带的媒体块。`image` / `video` 块带 `source` 对象（`kind` 为 `url` / `base64` / `file` / `session_media`，与提示词内容块同形）；`file` 块带顶层 `file_id`、`name`、`media_type`、`size`

成功时 data 为 { activated: true, skill_name }。

40001：校验失败或动作后缀不支持
40401：会话不存在（或未激活）
40407：引用的附件文件不存在
40415：没有该名称的技能
40912：技能存在，但其类型不允许用户激活

`GET /api/v1/tools`

列出当前生效 agent 的工具——即 session_id 指定会话的 main agent；省略参数时取最近创建的会话。若该会话不在本服务进程中存活，列表为空。

参数	位置	类型	说明
`session_id`	query	string	要查看其 main agent 的会话。默认最近创建的会话

成功时 data 为 { tools }，每项为 { name, description, input_schema, source, mcp_server_id?, active? }：source 为 builtin / skill / mcp；mcp_server_id 仅 MCP 工具携带（从 mcp__<server>__<tool> 名称解析）；active 报告工具策略的判定结果。input_schema 目前恒为 null。

`GET /api/v1/mcp/servers`

列出当前生效 agent 配置的 MCP 服务（与 GET /api/v1/tools 相同，取最近创建的存活会话的 main agent）。没有存活会话时列表为空。

成功时 data 为 { servers }，每项为 { id, name, transport, status, last_error?, tool_count }：transport 为 stdio / http / sse；status 为 connected / connecting / disconnected / error；服务处于 error 时 last_error 携带失败信息。

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

重新连接当前生效 agent 的某个 MCP 服务。该端点经 POST /api/v1/mcp/servers/{tail} 分发，restart 是唯一动作——只给服务 id 或动作未知时返回 40001。

参数	位置	类型	说明
`mcp_server_id`	path	string	必填。 MCP 服务 id（即其配置名称）

成功时 data 为 { restarting: true }。

40001：缺少动作后缀或动作未知
40408：没有该 id 的 MCP 服务（无存活会话时同样返回此错误）

能力与插件

能力是带有分层就绪状态的内置特性——由检测步骤加后台安装组成；当前版本注册了 kimi-cu（Kimi Computer Use）与 kimi-webbridge（Kimi WebBridge）。插件是已安装的技能、MCP 服务、hook 与命令的打包集合。这组端点报告能力状态、驱动能力安装，并管理插件从市场列表到移除的整个生命周期。

方法与路径	说明
`GET /api/v1/capabilities`	列出内置能力及其就绪状态
`GET /api/v1/capabilities/{capability_id}`	读取单个能力的状态
`POST /api/v1/capabilities/{capability_id}:install`	开始安装能力（后台进行，轮询 GET 查看进度）
`GET /api/v1/plugins`	列出已安装插件
`POST /api/v1/plugins`	从本地路径、zip URL 或 GitHub 仓库安装插件
`GET /api/v1/plugins/marketplace`	插件市场目录，合并实时安装状态
`POST /api/v1/plugins/{plugin_id}:{action}`	插件动作：`enable` / `disable` / `remove`

`GET /api/v1/capabilities`

列出所有已注册能力及其就绪状态。

成功时 data 为 { capabilities }，每项是一个能力状态对象 { id, pluginId?, displayName, description, supported, state, version?, steps, install }。state 为 ready（所有必需检测步骤均为 ok）/ partial（部分步骤 ok）/ not_installed / unsupported（当前平台/架构不可用）；steps 以 { id, state, detail?, optional? } 列出各检测步骤，其 state 为 ok / missing / failed 之一；install 为安装进度 { running, step?, percent?, error?, note? }，其中 percent 取值 0 到 100。

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

读取单个能力的就绪状态——即 :install 动作的轮询对应端点。

参数	位置	类型	说明
`capability_id`	path	string	必填。能力 id

成功时 data 为上文 GET /api/v1/capabilities 说明的能力状态对象。

40418：没有该 id 的能力

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

在后台开始安装能力并立即返回当前状态（install.running 为 true）；轮询 GET /api/v1/capabilities/{capability_id} 查看进度。该端点经 POST /api/v1/capabilities/{tail} 分发，install 是唯一动作——只给 id 或动作未知时返回 40001。

参数	位置	类型	说明
`capability_id`	path	string	必填。能力 id

成功时 data 为上文 GET /api/v1/capabilities 说明的能力状态对象。

40001：缺少动作后缀或动作未知
40418：没有该 id 的能力
40924：该能力的安装已在进行中
40925：当前平台/架构不支持该能力

`GET /api/v1/plugins`

列出已安装插件。

成功时 data 为 { plugins }，每项为 { id, displayName, version?, enabled, state, skillCount, mcpServerCount, enabledMcpServerCount, hookCount, commandCount, hasErrors, source, originalSource?, github? }：state 为 ok / error（加载失败也会置 hasErrors）；source 为 local-path / zip-url / github；GitHub 来源的插件由 github 携带来源信息 { owner, repo, ref, installedSha? }，其中 ref 为 { kind: branch|tag|sha, value }。

`POST /api/v1/plugins`

安装插件并返回其摘要。

参数	位置	类型	说明
`source`	body	string	必填。安装来源：本地绝对路径、指向 zip 压缩包的 `http(s)` URL，或 GitHub URL——`https://github.com/<owner>/<repo>`，可选地用 `/tree/<branch-or-sha>`、`/releases/tag/<tag>` 或 `/commit/<sha>` 锁定版本

成功时 data 为上文 GET /api/v1/plugins 说明的插件摘要。

40001：校验失败——例如 source 既不是 URL 也不是绝对路径，或插件加载失败
40409：本地路径不存在

`GET /api/v1/plugins/marketplace`

列出插件市场目录并合并实时安装状态。目录按请求从配置的市场 URL 拉取（超时 10 秒）；使用默认目录时，目录中缺少的内置能力会作为条目合并进来（带 capabilityId），而当前平台不支持的能力对应条目会被剔除。

成功时 data 为 { entries }，每项为 { id, tier, displayName, description?, homepage?, keywords?, version?, source, installed?, updateAvailable?, capabilityId? }：tier 为 official / curated / third-party；插件已安装时 installed 为 { version?, enabled }；updateAvailable 标记目录版本新于已安装版本的条目。条目的 source 即 POST /api/v1/plugins 的 source 字段取值。

50001：市场不可达或返回了非法目录

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

启用一个已安装插件。插件动作经单一路由 POST /api/v1/plugins/{tail} 分发：尾部按 {plugin_id}:{action} 解析，动作为 enable / disable / remove；只给 id 或动作未知时返回 40001（unsupported action: ...）。

参数	位置	类型	说明
`plugin_id`	path	string	必填。已安装插件 id

成功时 data 为 { ok: true }。

40001：缺少动作后缀或动作未知
40419：没有该 id 的已安装插件

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

停用一个已安装插件但不移除它；分发约定同上文 :enable。

参数	位置	类型	说明
`plugin_id`	path	string	必填。已安装插件 id

成功时 data 为 { ok: true }。

40001：缺少动作后缀或动作未知
40419：没有该 id 的已安装插件

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

移除一个已安装插件；分发约定同上文 :enable。

参数	位置	类型	说明
`plugin_id`	path	string	必填。已安装插件 id

成功时 data 为 { ok: true }。

40001：缺少动作后缀或动作未知
40419：没有该 id 的已安装插件

终端

PTY 终端接口；仅在 loopback 绑定时挂载（非 loopback 绑定会跳过它们，除非传入 --allow-remote-terminals）。终端的输入、输出与尺寸调整经 WebSocket 的 terminal_* 帧传输——REST 侧只管理终端生命周期。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/terminals`	列出终端
`POST /api/v1/sessions/{session_id}/terminals`	创建终端
`GET /api/v1/sessions/{session_id}/terminals/{terminal_id}`	读取终端
`POST /api/v1/sessions/{session_id}/terminals/{terminal_id}:close`	关闭终端

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

列出会话的终端。会话处于冷态时，读取列表会恢复该会话。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id

成功时 data 为 { items }，每项是一个终端对象 { id, session_id, cwd, shell, cols, rows, status, created_at, exited_at?, exit_code? }：status 为 running / exited；已退出的终端携带 exited_at 与 exit_code（进程未报告退出码时为 null，例如因信号终止）。回滚缓冲不属于该对象——输出经 WebSocket 回放与流式推送。

40401：会话不存在

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

为会话创建一个 PTY 终端。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`runtime_id`	body	string	生成终端进程的运行时。默认 `local`
`cwd`	body	string	工作目录，相对于会话工作区（传绝对路径会校验失败）。默认工作区根目录
`shell`	body	string	Shell 可执行文件。默认该运行时的 shell
`cols`	body	integer	终端宽度，正数。默认 `80`
`rows`	body	integer	终端高度，正数。默认 `24`

成功时 data 为上文 GET /api/v1/sessions/{session_id}/terminals 说明的终端对象。

40001：校验失败（details 逐字段说明）
40401：会话不存在
41304：cwd 解析后越出会话工作区

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

读取单个终端。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`terminal_id`	path	string	必填。终端 id

成功时 data 为上文 GET /api/v1/sessions/{session_id}/terminals 说明的终端对象。

40401：会话不存在
40414：没有该 id 的终端

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

关闭终端并结束其进程。该端点经 POST /api/v1/sessions/{session_id}/terminals/{tail} 分发，close 是唯一动作——只给 id 或动作未知时返回 40001。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`terminal_id`	path	string	必填。终端 id

成功时 data 为 { closed: true }。

40001：缺少动作后缀或动作未知
40401：会话不存在
40414：没有该 id 的终端

工作区

工作区是已注册的项目目录，会话都落在其中。这组端点管理注册表——列出、注册、重命名、注销——以及控制项目级 MCP 配置是否加载的每工作区信任状态。所有返回工作区的端点都使用 workspace 对象中统一说明的传输结构。

方法与路径	说明
`GET /api/v1/workspaces`	列出已注册工作区
`POST /api/v1/workspaces`	注册工作区（按根路径幂等）
`PATCH /api/v1/workspaces/{workspace_id}`	重命名
`DELETE /api/v1/workspaces/{workspace_id}`	注销（保留磁盘内容）
`GET /api/v1/workspaces/{workspace_id}/trust`	读取信任状态
`POST /api/v1/workspaces/{workspace_id}/trust`	授予信任
`POST /api/v1/workspaces/{workspace_id}/untrust`	撤销信任
`POST /api/v1/workspaces/{workspace_id}/add-dir`	添加附加目录

workspace 对象

所有返回工作区的端点都使用此传输结构。注册与重命名会广播全局事件 event.workspace.created / event.workspace.updated。

字段	类型	说明
`id`	string	工作区 id，由根路径派生的 `wd_<slug>_<hash12>` 字符串
`root`	string	项目目录的绝对路径
`name`	string	显示名，1–100 个字符；默认取根目录的基名
`created_at`	string	注册时间，ISO 8601
`last_opened_at`	string	最近一次打开或重新注册工作区的时间，ISO 8601
`session_count`	integer	工作区内的会话数

`GET /api/v1/workspaces`

列出所有已注册工作区。

成功时 data 为 { items }，每项是一个 workspace 对象。

`POST /api/v1/workspaces`

注册工作区并返回它。注册按根路径幂等：重复注册同一根路径会返回已存在的工作区，仅刷新 last_opened_at（保留已存名称），并广播 event.workspace.updated 而非 event.workspace.created。

参数	位置	类型	说明
`root`	body	string	必填。已存在目录的绝对路径
`name`	body	string	显示名，1–100 个字符。默认根目录的基名

成功时 data 为 workspace 对象。

40001：root 缺失或不是绝对路径（details 会列出该字段）
40409：root 不存在或不是目录

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

重命名工作区——仅修改显示名，根路径不变。

参数	位置	类型	说明
`workspace_id`	path	string	必填。工作区 id
`name`	body	string	必填。新的显示名，1–100 个字符

成功时 data 为 workspace 对象。

40001：校验失败（details 逐字段说明）
40410：工作区不存在

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

注销工作区。只移除注册表条目——磁盘上的目录不受影响。

参数	位置	类型	说明
`workspace_id`	path	string	必填。工作区 id

成功时 data 为 { deleted: true }。

40410：工作区不存在

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

读取工作区信任状态。信任状态决定是否为该工作区加载项目级 MCP 配置。

参数	位置	类型	说明
`workspace_id`	path	string	必填。工作区 id

成功时 data 为 { trusted }。

40410：工作区不存在

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

将工作区标记为信任，并加载其项目级 MCP 配置。

参数	位置	类型	说明
`workspace_id`	path	string	必填。工作区 id

成功时 data 为 { trusted: true }。

40410：工作区不存在

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

撤销工作区信任，并卸载其项目级 MCP 配置。

参数	位置	类型	说明
`workspace_id`	path	string	必填。工作区 id

成功时 data 为 { trusted: false }。

40410：工作区不存在

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

为工作区添加附加目录，语义与 CLI --add-dir 及 TUI /add-dir 一致。路径支持绝对路径、相对路径（相对工作区根目录解析）与 ~ 展开。

参数	位置	类型	说明
`workspace_id`	path	string	必填。工作区 id
`path`	body	string	必填。要添加的目录
`persist`	body	boolean	缺省 `true`：追加到 `<项目根>/.kimi-code/local.toml` 的 `workspace.additional_dir`；为 `false` 时仅加入内存中的临时集合（同一工作区所有会话共享），不写盘

成功时 data 为 { project_root, config_path, additional_dirs, persisted }，其中 additional_dirs 是全部附加目录（含既有目录），persisted 表示本次是否写盘。

40001：校验失败（details 逐字段说明），或项目本地配置损坏等引擎校验错误
40409：path 不存在或不是目录
40410：工作区不存在

文件系统

会话内文件操作走 POST /api/v1/sessions/{session_id}/fs:{action}，请求体为 JSON；动作包括 list / read / list_many / stat / stat_many / mkdir / search / grep / git_status / diff / open / open-in / reveal。每个动作的请求体还接受可选的 runtime_id（string，默认 local），用于选择执行操作的运行时；open、open-in 与 reveal 仅在 local 运行时上可用。另有：

方法与路径	说明
`POST /api/v1/workspace/fs:search`	无会话的工作区搜索（body 携带工作区引用）
`POST /api/v1/workspace/fs:suggest`	无会话的文件补全候选（用于 `@` 文件提及）
`GET /api/v1/sessions/{session_id}/fs/{path}:download`	下载会话文件（二进制，见下文）
`GET /api/v1/fs:browse`	列出本机目录（文件夹选择器用）
`GET /api/v1/fs:home`	用户主目录与最近工作区
`GET /api/v1/fs:content`	读取本机任意文件原始字节（仅受 token 保护，谨慎暴露端口）
`POST /api/v1/fs:mkdir`	按绝对路径创建目录

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

列出会话工作区目录下的条目，可选递归子目录。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	要列出的目录，相对于会话工作目录。默认 `.`
`depth`	body	integer	递归深度，1–10。默认 `1`
`limit`	body	integer	最大条目数，1–1000。默认 `200`
`show_hidden`	body	boolean	包含点文件。默认 `false`
`follow_gitignore`	body	boolean	跳过 gitignore 的路径。默认 `true`
`exclude_globs`	body	string[]	额外要跳过的 glob
`sort`	body	string	`type_first`（默认）/ `name_asc` / `name_desc` / `mtime_desc` / `size_desc`
`include_git_status`	body	boolean	附带每个条目的 git 状态。默认 `false`

成功时 data 为 { items, truncated }——depth 大于 1 时另附 children_by_path（路径 → 条目的映射）。每项是一个条目对象 { path, name, kind, size?, modified_at, etag?, mime?, language_id?, is_binary?, is_symlink_to?, git_status?, child_count? }，其中 kind 为 file / directory / symlink；git_status（仅 include_git_status: true 时存在）为 clean / modified / added / deleted / renamed / untracked / ignored / conflicted 之一；truncated 表示 limit 截断了列表。

40001：请求体校验失败
40401：会话不存在
40409：路径不存在（包括 path 不是目录的情况）
41304：路径越出会话工作区

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

以文本或 base64 读取会话文件的一段内容。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	必填。文件路径，相对于会话工作目录
`offset`	body	integer	起始字节偏移。默认 `0`
`length`	body	integer	读取字节数，1–10485760（10 MiB）。默认 `1048576`（1 MiB）
`encoding`	body	string	`auto`（默认）/ `utf-8` / `base64`

成功时 data 为 { path, content, encoding, size, truncated, etag, mime, language_id?, line_count?, is_binary }，其中 encoding 报告实际使用的编码（utf-8 或 base64），size 为文件完整大小。encoding: "auto" 时文本以 utf-8 返回（非 UTF-8 文本会被转码），二进制内容以 base64 返回；encoding: "utf-8" 强制按文本读取并拒绝二进制文件。

40001：请求体校验失败
40401：会话不存在
40409：路径不存在
40906：路径是目录
40907：二进制文件却指定了 encoding: "utf-8"
41302：文件超过 10 MiB 读取上限
41304：路径越出会话工作区

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

一次调用列出多个会话目录；失败的路径会折进响应里，而不是让整个请求失败。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`paths`	body	string[]	必填。要列出的目录，1–100 条

其余请求体字段（depth、limit、show_hidden、follow_gitignore、exclude_globs、sort、include_git_status）的类型、取值范围与默认值同 fs:list。成功时 data 为 { results }——每个请求路径到其条目数组（条目对象见 fs:list 的说明）的映射，另附 truncated_paths（达到 limit 的路径）与 partial_errors（失败路径到其 { code, msg } 错误的映射）。

40001：请求体校验失败
40401：会话不存在

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

查询会话工作区内单个路径的元信息。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	必填。要查询的路径，相对于会话工作目录

成功时 data 为 fs:list 中说明的条目对象。

40001：请求体校验失败
40401：会话不存在
40409：路径不存在
41304：路径越出会话工作区

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

一次调用查询多个会话路径的元信息；不存在的路径返回 null，不会让整个请求失败。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`paths`	body	string[]	必填。要查询的路径，1–1000 条

成功时 data 为 { entries }——每个请求路径到其条目对象（见 fs:list 的说明）的映射，路径不存在时为 null。

40001：请求体校验失败
40401：会话不存在

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

在会话工作区内创建目录。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	必填。要创建的目录，相对于会话工作目录
`recursive`	body	boolean	创建缺失的父目录。默认 `false`

成功时 data 为所建目录的条目对象（见 fs:list 的说明）。

40001：请求体校验失败
40401：会话不存在
40409：父目录不存在（非递归创建）
40919：路径已存在（非递归创建）
41304：路径越出会话工作区

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

在会话工作区内模糊搜索文件与目录名。query 为空时改为列出顶层条目。当 {session_id} 位置携带的是工作区引用（已注册工作区 id 或绝对根路径）而非会话 id 时，搜索针对该工作区执行——这是为尚未创建的草稿会话准备的无会话形式；正式的无会话端点是 POST /api/v1/workspace/fs:search。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id，或工作区引用
`query`	body	string	必填。搜索文本；`""` 表示列出顶层
`limit`	body	integer	最大命中数，1–200。默认 `50`
`include_globs`	body	string[]	只保留匹配这些 glob 之一的路径
`exclude_globs`	body	string[]	跳过匹配这些 glob 的路径
`follow_gitignore`	body	boolean	跳过 gitignore 的路径。默认 `true`

成功时 data 为 { items, truncated }，每项为 { path, name, kind, score, match_positions }——kind 为 file / directory / symlink，score 为 0 到 1 之间的模糊匹配得分，match_positions 列出匹配到的字符偏移。命中按得分排序（同分按路径），truncated 表示超出 limit 的命中被丢弃。

40001：请求体校验失败
40401：该引用既不是会话，也不是可解析的工作区

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

在会话工作区内搜索文件内容——默认按字面字符串，regex: true 时按正则表达式。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`pattern`	body	string	必填。要搜索的文本或正则
`regex`	body	boolean	将 `pattern` 视为正则表达式。默认 `false`
`case_sensitive`	body	boolean	默认 `true`
`include_globs`	body	string[]	只保留匹配这些 glob 之一的文件
`exclude_globs`	body	string[]	跳过匹配这些 glob 的文件
`follow_gitignore`	body	boolean	跳过 gitignore 的路径。默认 `true`
`max_files`	body	integer	最多扫描的文件数，1–10000。默认 `200`
`max_matches_per_file`	body	integer	每个文件保留的匹配数，1–10000。默认 `50`
`max_total_matches`	body	integer	总共保留的匹配数，1–100000。默认 `5000`
`context_lines`	body	integer	每个匹配携带的上下文行数，0–10。默认 `2`

成功时 data 为 { files, files_scanned, truncated, elapsed_ms }，其中 files 的每项为 { path, matches }，每个匹配为 { line, col, text, before, after }（before / after 最多携带 context_lines 行上下文）；truncated 表示某个匹配配额截断了结果。

40001：请求体校验失败
40401：会话不存在
41305：搜索超时

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

读取会话工作区的 git 状态，可选限定在一组路径内。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`paths`	body	string[]	将状态限定在这些路径；省略表示整个工作区

成功时 data 为 { branch, ahead, behind, entries, additions, deletions, pullRequest }，其中 entries 把每个变更路径映射到其状态（clean / modified / added / deleted / renamed / untracked / ignored / conflicted），pullRequest 为 { number, state, url }（state 为 open / merged / closed / draft）或 null。

40001：请求体校验失败
40401：会话不存在
40908：git 不可用（不是仓库，或没有 git 可执行文件）

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

返回会话工作区内单个文件的 unified git diff。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	必填。要 diff 的文件，相对于会话工作目录

成功时 data 为 { path, diff, truncated }，其中 diff 为 unified diff 文本，truncated 表示过长的 diff 被截断。

40001：请求体校验失败
40401：会话不存在
40908：git 不可用（不是仓库，或没有 git 可执行文件）
41304：路径越出会话工作区

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

用宿主操作系统的默认程序打开会话文件。仅限 local 运行时。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	必填。要打开的文件，相对于会话工作目录
`line`	body	integer	在处理程序支持时跳转到的行号（正整数）

成功时 data 为 { opened: true }。

40001：请求体校验失败
40401：会话不存在
40409：路径不存在
41304：路径越出会话工作区

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

在指定的宿主应用程序中打开会话文件或目录。仅限 local 运行时。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`app_id`	body	string	必填。目标应用：`finder` / `cursor` / `vscode` / `iterm` / `terminal`
`path`	body	string	必填。要打开的文件或目录，相对于会话工作目录
`line`	body	integer	在应用支持时跳转到的行号（正整数）

成功时 data 为 { opened: true }。

40001：请求体校验失败
40401：会话不存在
40409：路径不存在
41304：路径越出会话工作区
50001：应用启动失败

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

在宿主操作系统的文件管理器中显示会话文件。仅限 local 运行时。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	body	string	必填。要显示的文件，相对于会话工作目录

成功时 data 为 { revealed: true }。

40001：请求体校验失败
40401：会话不存在
40409：路径不存在
41304：路径越出会话工作区

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

从会话工作区下载文件；{path} 是相对于工作区的文件路径，并带字面量 :download 后缀。响应为支持 Range 与 ETag 的二进制流——见二进制与流式端点。

参数	位置	类型	说明
`session_id`	path	string	必填。会话 id
`path`	path	string	必填。相对于工作区的文件路径，加 `:download` 后缀
`runtime_id`	query	string	从哪个运行时读取。默认 `local`

40001：路径缺失或为空
40401：会话不存在
40409：路径不存在
41304：路径越出会话工作区

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

fs:search 的无会话形式：工作区改由请求体而非 URL 携带。

参数	位置	类型	说明
`workspace`	body	string	必填。已注册工作区 id 或绝对根路径（当场注册）
`query`	body	string	必填。搜索文本；`""` 表示列出顶层
`limit`	body	integer	最大命中数，1–200。默认 `50`
`include_globs`	body	string[]	只保留匹配这些 glob 之一的路径
`exclude_globs`	body	string[]	跳过匹配这些 glob 的路径
`follow_gitignore`	body	boolean	跳过 gitignore 的路径。默认 `true`
`runtime_id`	body	string	在哪个运行时上搜索。默认 `local`

成功时 data 为 { items, truncated }，命中结构与排序同 fs:search。

40001：请求体校验失败
40410：工作区不存在，且不是可用的绝对路径

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

在无会话的情况下给出工作区内的文件与目录补全候选——即输入框中 @ 文件提及的后端。

参数	位置	类型	说明
`workspace`	body	string	必填。已注册工作区 id 或绝对根路径（当场注册）
`query`	body	string	必填。要补全的部分路径文本
`limit`	body	integer	最大候选数，1–200。默认 `50`
`follow_gitignore`	body	boolean	跳过 gitignore 的路径。默认 `true`
`show_hidden`	body	boolean	包含点文件。默认 `false`
`include_globs`	body	string[]	只保留匹配这些 glob 之一的路径
`exclude_globs`	body	string[]	跳过匹配这些 glob 的路径
`runtime_id`	body	string	在哪个运行时上补全。默认 `local`

成功时 data 为 { items, truncated }，每项为 { path, name, kind, score, match_positions }，命中结构同 fs:search。

40001：请求体校验失败
40410：工作区不存在，且不是可用的绝对路径

`GET /api/v1/fs:browse`

列出某个本机目录的子目录——文件夹选择器的后端。

参数	位置	类型	说明
`path`	query	string	绝对目录路径。默认用户主目录

成功时 data 为 { path, parent, entries }，其中 path 为解析后的目录，parent 为其父目录（文件系统根处为 null），每条目为 { name, path, is_dir: true }。

40001：path 不是绝对路径
40409：路径不存在
40411：权限不足

`GET /api/v1/fs:home`

返回文件夹选择器的落地数据。无参数。

成功时 data 为 { home, recent_roots }，其中 home 为用户主目录，recent_roots 列出已注册工作区的根目录。

`GET /api/v1/fs:content`

以流式返回本机文件系统上任意文件的原始字节——仅受 API token 保护，暴露端口时务必谨慎。支持 Range 请求与 ETag 缓存；见二进制与流式端点。

参数	位置	类型	说明
`path`	query	string	必填。绝对文件路径

40001：path 不是绝对路径，或不是普通文件
40409：路径不存在
40411：权限不足
40906：路径是目录

`POST /api/v1/fs:mkdir`

按绝对路径在本机文件系统上创建一个目录——文件夹选择器「新建文件夹」的后端。非递归：父目录必须已存在。

参数	位置	类型	说明
`path`	body	string	必填。绝对目录路径

成功时 data 为 { path }。

40001：path 不是绝对路径
40409：父路径不存在
40411：权限不足
40919：路径已存在

文件上传

方法与路径	说明
`POST /api/v1/files`	multipart 上传（字段 `file`，可选 `name`、`expires_in_sec`），返回文件元信息
`GET /api/v1/files/{file_id}`	下载（二进制，错误用真实 HTTP 状态码）
`DELETE /api/v1/files/{file_id}`	删除

`POST /api/v1/files`

以 multipart/form-data 上传文件，供后续引用（例如作为提示词附件）。

参数	位置	类型	说明
`file`	body	binary	必填。 multipart 的文件部分
`name`	body	string	存储的显示名。默认上传文件名
`expires_in_sec`	body	number	文件过期前的秒数（非负）。默认永不过期

成功时 data 为文件元信息 { id, name, media_type, size, created_at, expires_at? }，其中 media_type 取自上传的内容类型。

40001：multipart 请求体缺少 file 字段

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

下载已上传的文件。响应为二进制流，支持 Range 请求但不处理 If-None-Match；失败使用真实 HTTP 状态码——见二进制与流式端点。

参数	位置	类型	说明
`file_id`	path	string	必填。上传响应返回的文件 id

40407（HTTP 404）：没有该 id 的文件（包括已过期的文件）

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

删除已上传的文件。

参数	位置	类型	说明
`file_id`	path	string	必填。上传响应返回的文件 id

成功时 data 为 { deleted: true }。

40407（HTTP 404）：没有该 id 的文件

GUI 存储

由服务端支撑的键值存储，接口对齐浏览器的 localStorage，持久化在服务的 home 目录下；web UI 用它保存跨客户端的 UI 状态。值是不透明字符串——序列化由调用方负责。

方法与路径	说明
`GET /api/v1/gui/store/length`	已存键的数量
`GET /api/v1/gui/store/getItem`	按键读取值
`POST /api/v1/gui/store/setItem`	按键写入值
`POST /api/v1/gui/store/removeItem`	按键删除值
`POST /api/v1/gui/store/clear`	删除所有值

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

返回已存键的数量（对齐 localStorage.length）。无参数。

成功时 data 为 { length }。

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

读取一个值（对齐 localStorage.getItem）。

参数	位置	类型	说明
`key`	query	string	必填。要读取的键，1–256 个字符

成功时 data 为 { value }——已存字符串，键不存在时为 null。

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

写入一个值（对齐 localStorage.setItem）。

参数	位置	类型	说明
`key`	body	string	必填。要写入的键，1–256 个字符
`value`	body	string	必填。要存储的值

成功时 data 为 null。

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

删除一个值（对齐 localStorage.removeItem）。

参数	位置	类型	说明
`key`	body	string	必填。要删除的键，1–256 个字符

成功时 data 为 null。

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

删除所有已存值（对齐 localStorage.clear）。无参数。

成功时 data 为 null。

全局搜索与其他

方法与路径	说明
`POST /api/v1/search`	跨会话全文搜索，`mode` 为 `terms`（默认）或 `literal`（精确子串），`page_token` 分页
`GET /api/v1/connections`	列出当前在线的 WebSocket 连接
`GET /api/v2/sessions`	新一代会话列表，见下文
`POST /api/v2/sessions:archive`	批量归档会话，见下文
`POST /api/v2/sessions:restore`	批量恢复已归档会话，见下文
`/api/v2/mcp/*`	统一的 MCP 管理面，见下文
`/api/v1/debug/*`	反射式调试 RPC，仅 `--debug-endpoints` 且 loopback 时挂载，不属于稳定协议

`POST /api/v1/search`

跨会话全文搜索，覆盖 User 消息、Assistant 回复与会话标题，由服务端的持久搜索索引支撑。当 container.session_id 指向本服务进程中存活的会话时，搜索改为直接扫描该会话的内存转录，响应的 source 字段（index 或 live）会报告本页结果由哪条路径提供。

参数	位置	类型	说明
`query`	body	string	必填。搜索文本
`mode`	body	string	`terms`（默认）/ `literal`
`op`	body	string	`terms` 模式下的词项组合符：`AND`（默认）/ `OR`
`container`	body	object	将搜索限定在 `{ session_id?, agent_id? }`
`role`	body	string	限定 `user` / `assistant` / `title` 命中
`start_time`	body	integer	只看不早于该时间的命中（epoch 毫秒）
`end_time`	body	integer	只看不晚于该时间的命中（epoch 毫秒）
`sort`	body	string	`score`（默认）/ `time_desc` / `time_asc`；`literal` 模式忽略此参数，始终最新在前
`page_size`	body	integer	每页命中数，1–50。默认 `20`
`page_token`	body	string	上一页响应返回的令牌

terms 模式下查询会被分词（ASCII 词加 CJK n-gram）、去重，并以至多 32 个词项匹配倒排索引；literal 模式是零误报的精确子串搜索。成功时 data 为 { items, has_more, page_token?, index_state, source }，每项为 { session_id, workspace_id, session_title, agent_id, role, snippet, time, turn?, step_id?, score }。index_state 为 { state, indexed_sessions, total_sessions, documents, stale?, degraded? }，其中 state 为 building / ready / readonly 之一；stale 标记仍在追赶的落后视图，degraded 携带最近一次刷新失败的信息。超出预算的页会额外携带 incomplete，取值为 candidate_cap / postings_budget / deadline 之一。分页令牌锁定索引代际与查询条件——索引重建或查询变更会使其失效。

40001：请求体校验失败、查询不可用（为空或超过 32 个词项），或分页令牌非法

`GET /api/v1/connections`

列出当前连接到本服务的 WebSocket 客户端，按连接时间最早在前。无参数。

成功时 data 为 { connections }，每项为 { id, connected_at, remote_address, user_agent, has_client_hello, subscriptions }：connected_at 为 ISO 8601 时间戳；remote_address 与 user_agent 未知时为 null；has_client_hello 报告客户端是否已发送握手帧；subscriptions 列出该连接订阅的会话 id。

`GET /api/v2/sessions`

面向列表页的新一代会话查询，筛选、排序、字段组都在查询参数里：

参数	说明
`workspace.id`	按工作区过滤，可重复
`activity.status`	按活动状态过滤：`running` / `approval` / `question` / `failed` / `idle`，可重复
`meta.updated_after`	只看该时间（epoch 毫秒）之后更新过的会话
`meta.updated_before`	只看该时间（epoch 毫秒）之前更新过的会话
`meta.archived`	`true` / `false`（默认）/ `all`
`meta.has_prompt`	`true` 只保留有用户 prompt 的会话，`false` 只保留空会话（等价 `GET /api/v1/sessions` 的 `exclude_empty`）
`view`	`flat`（默认）/ `by_workspace`，见下文
`group.page_size`	`view=by_workspace` 时每个工作区返回的会话数：1–100，默认 5（使用 `id,archived` 投影时上限 10000）；未开分组视图时传入返回 `40001`
`sort`	`meta.updated_at_desc`（默认）/ `meta.updated_at_asc` / `meta.created_at_desc`
`include`	逗号分隔的附加字段组；目前支持 `git`（分支与 PR 信息，按目录去重并缓存 60 秒）
`fields`	逗号分隔的字段投影；目前仅支持 `id,archived`，每项裁剪为 `{ id, archived }`（用于全选匹配场景）。不可与 `include=git` 同传（`40001`）
`page_size`	1–100，默认 50；使用 `id,archived` 投影时上限放宽至 10000。`view=by_workspace` 时按组计数
`page_token`	上一页返回的翻页令牌
`page`	无状态的 1 起始页码；与 `page_token` 互斥（同传返回 `40001`）

响应每项固定包含 workspace、meta、activity 三组，include=git 时附加 git 组；fields=id,archived 时仅返回 { id, archived }。activity 组还会带上 model：会话仍加载在当前进程时为其绑定的模型别名，冷会话（未加载）为 null。每页额外携带 total，即过滤后的集合大小。翻页令牌绑定首页查询条件（含投影），中途改条件返回 40922。page 模式是跳页用的无状态替代：每次请求都是独立快照，不签发令牌，next_page_token 恒为 null。

view=by_workspace 时，同一份过滤、排序后的集合会重新投影为按工作区分组的形态，概览页因此可以用一次请求替代「每个工作区各一轮询」：

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_..."
}

每组携带该工作区按请求 sort 排序的前 group.page_size 条会话，以及该工作区匹配过滤条件的会话总数 total（用作「查看全部」入口）。只有至少有一条匹配会话的工作区才会出现；组间按组内首条会话的 sort key 排序，相同则按工作区 id。page 与 page_token 按组翻页（外层 total 为组数），指纹绑定规则相同：令牌同时覆盖 view 与分组参数，翻页途中变更同样返回 40922。

`POST /api/v2/sessions:archive` 与 `POST /api/v2/sessions:restore`

面向会话管理页的批量归档/恢复。请求体为 { "ids": ["session_..."] }——非空、去重后不超过 5000 条。仍在线的会话走完整生命周期；未加载的冷会话直接改写磁盘上的元数据，不会被加载。

只有请求体校验失败才会让整个请求失败（40001）；其余情况按条返回：data.results 保持输入顺序，每项为 { id, ok } 或 { id, ok: false, error }（不存在的 id 在自身条目里报 40401），并附 succeeded / failed 计数。

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 管理（`/api/v2/mcp`）

/api/v2/mcp/* 路由是服务的统一 MCP 管理面：独立于任何会话，直接管理 MCP server 注册表本身——全局（用户级）CRUD 与逐条校验、连接测试探测、locator 寻址的检查目录、按 server 的授权状态列表，以及完整的 OAuth 流程生命周期。

方法与路径	说明
`GET /api/v2/mcp/servers`	列出所有已知 MCP server
`GET /api/v2/mcp/servers/{name}`	按运行时名称获取单个 server
`POST /api/v2/mcp/servers`	向用户级 `mcp.json` 添加 server
`PUT /api/v2/mcp/servers/{name}`	替换一个用户级条目
`DELETE /api/v2/mcp/servers/{name}`	删除一个用户级条目
`POST /api/v2/mcp/servers:test`	对单个 server 发起真实连接探测
`POST /api/v2/mcp/servers:inspect`	locator 寻址的目录及批量连接探测
`GET /api/v2/mcp/auth-statuses`	目录中各 server 的 OAuth 状态
`POST /api/v2/mcp/auth:begin`	开始一次交互式 OAuth 流程
`POST /api/v2/mcp/auth:complete`	等待浏览器回调并完成 code 交换
`POST /api/v2/mcp/auth:cancel`	终止已开始的 OAuth 流程
`POST /api/v2/mcp/auth:reset`	清除某个 server 已存储的凭据

该管理面有两种寻址方式。CRUD 路由与 servers:test 使用普通的运行时 name；检查与 OAuth 路由使用 locator——文件层条目用 { "source": "global", "name" }，插件清单条目用 { "source": "plugin", "pluginId", "serverName" }——因为插件条目和文件条目可能共用同一个运行时名称。检查条目还带有一个稳定的 serverId 线上标识：global:<name> 或 plugin:<pluginId>:<serverName>（URL 编码）。

大多数路由接受可选的 cwd（查询参数，:-action 路由则为请求体字段）。不传时目录只覆盖用户级文件与插件清单；传入后，该目录的项目根层与项目本地层会并入——但仅当工作区受信任时，否则项目层会被跳过。对 stdio server 执行 servers:test 时，cwd 同时是子进程的工作目录。连接探测与 OAuth 调用会等待服务配置加载完成后再执行。

`GET /api/v2/mcp/servers` 与 `GET /api/v2/mcp/servers/{name}`

列出管理面已知的全部 MCP server；第二个路由返回该运行时名称对应的单个条目。

参数	位置	类型	说明
`name`	path	string	必填（仅 get）。 server 的运行时名称
`cwd`	query	string	并入该（受信任）目录的项目层

成功时 data 是受管 server 数组（get 路由为单个对象），每项为 { name, config, source, origin, mutable, plugin? }：

source：global（配置文件层）或 plugin（插件清单）
origin：条目的定义位置——文件路径或插件 id
mutable：只有用户级条目可变；插件与项目层条目均为只读
config：可变条目携带完整配置，便于编辑界面预填；只读条目被脱敏为排序后的键名列表（envKeys / headerKeys），绝不泄露密钥值
plugin：{ id, name }，仅插件条目携带
40001：校验失败
40408：不存在该名称的 server

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

针对用户级 mcp.json 的全局 CRUD。新增请求体是包含 name 的完整 server 配置——transport（stdio / http / sse）决定配置形状，每条配置写入前都会校验。更新请求体携带同样的配置但不含 name（由路径指定条目）；删除无请求体。三者都在 data 中返回刷新后的 server 列表。若写入与项目层的同名条目冲突，会因只读被拒绝——请改为编辑定义它的文件；与同名的插件条目冲突并不阻止写入，新的文件条目会将其遮蔽。

40001：校验失败，或目标条目为只读
40408：（更新/删除）不存在该名称的 server

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

对单个 server 发起真实连接探测，不持久化任何内容。传 name 探测注册表条目（含插件与受信任的项目层），或传 server（包含 name 的完整内联配置）按原样探测；两者都传或都不传会报 40001。

参数	位置	类型	说明
`name`	body	string	注册表条目的运行时名称
`server`	body	object	按原样探测的内联 server 配置
`cwd`	body	string	项目层并入解析；同时是 stdio 的工作目录

成功时 data 为 { success, output }：连接成功时 output 列出该 server 的可用工具，否则携带失败信息。

40001：两种目标形式都传或都不传、内联配置无效，或运行时名称被多个启用的 server 共用
40408：不存在该名称的 server

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

locator 寻址的目录（脱敏配置），外加对每个 OAuth 候选的批量真实连接探测。

参数	位置	类型	说明
`targets`	body	array	缩小目录范围的 locator 数组；不传则检查全部 server
`cwd`	body	string	并入该（受信任）目录的项目层

成功时 data 是检查结果数组，每项为 { serverId, locator, runtimeName, canonicalUrl?, origin, config, enabled, editable, authStatus, checkedAt?, error? }：canonicalUrl 是远程 server 的凭据 URL，config 为脱敏视图，authStatus 取值为 not-applicable / bearer-token / oauth-required / oauth-authorized / oauth-expired / unavailable 之一。运行时名称被多个启用的 server 共用时无法无歧义地探测，会报告 unavailable 并在 error 中给出说明。探测遇到过期授权时，可能刷新或作废已存储的凭据。

40001：校验失败
40408：targets 中有 locator 未匹配到任何条目

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

注册表目录中各 server 的 OAuth 状态——只需要授权维度时，这是比 servers:inspect 更轻量的选择。

参数	位置	类型	说明
`cwd`	query	string	并入该（受信任）目录的项目层
`verify`	query	string	`true` 对每个 OAuth 候选发起真实连接验证；`false` 完全离线（仅凭配置与已存储 token 分类）；缺省保留隐式 OAuth 探测，只探测未固定且没有已存储凭据的远程 server

成功时 data 是 { name, authStatus } 数组，authStatus 取值与 servers:inspect 相同。验证探测可能刷新或作废已存储的凭据。

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

远程 server 的 OAuth 流程生命周期。auth:begin 接受 locator 请求体（外加可选的 cwd 查询参数），返回 data 为 { status: "authorization-required", flowId, authorizationUrl }——在浏览器中打开该 URL 完成授权——或当授权已存在时返回 { status: "already-authorized" }。目标 server 必须使用远程传输（http / sse）且不含静态 bearer token；静态请求头仅当配置显式设置 auth: "oauth" 时允许。

auth:complete 等待已开始流程的浏览器回调并完成 code 交换。请求体为 { flowId, timeoutMs? }：等待默认 15 分钟（timeoutMs 可覆盖），空闲流程无论如何都会在 15 分钟后过期，关闭 HTTP 连接会中止等待。成功时 data 为 null。

auth:cancel 在未完成的情况下终止已开始的流程（{ flowId }）；未知流程会被忽略。auth:reset 接受 locator 请求体，清除该 server 已存储的凭据——失效事件会送达存活的会话。

40001：校验失败——包括 :complete 的 flowId 未知，或 :begin 的 server 无法使用 OAuth（stdio 传输、静态 bearer token，或未设置 auth: "oauth" 的静态请求头）
40408：（:begin / :reset）locator 未匹配到任何条目
40929：OAuth 流程本身失败

WebSocket 协议

建立连接

唯一端点是 ws://<host>:<port>/api/v1/ws；鉴权在升级请求时完成（见上文鉴权）。连接建立后服务端立即发送 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 }
  }
}

注意服务端不发送心跳，也不会主动断开空闲连接——保活与重连由客户端自己负责。

控制帧

客户端发送 JSON 帧 { "type", "id"?, "payload" }；每个请求帧都会收到应答 { "type": "ack", "id", "code", "msg", "payload" }，code 为 0 表示成功。

帧	payload	说明
`subscribe`	`{ session_ids, cursors?, agent_filter? }`	订阅会话事件；带 `cursors`（每会话 `{seq, epoch}`）时回放错过的持久事件
`unsubscribe`	`{ session_ids }`	取消会话订阅
`subscribe_v2`	`{ session_id, transcript, transcript_since? }`	订阅转录流（唯一的转录订阅通道），`transcript` 按 agent 指定粒度
`unsubscribe_v2`	`{ session_id, agent_ids? }`	退订转录流；省略 `agent_ids` 表示整个会话
`client_hello`	`{ client_id }`	握手帧，其余字段为遗留兼容

事件

事件帧形状为 { "type", "seq", "epoch"?, "volatile"?, "offset"?, "session_id"?, "timestamp", "payload" }，type 即事件类型。按投递范围分两类：

全局事件：发送到每个已建立连接，无需订阅——session.meta.updated、event.session.created、event.session.archived、event.session.work_changed、event.session.status_changed、event.workspace.*、event.config.*、event.model_catalog.*。
会话事件：只发给订阅了该会话的连接，受 agent_filter 过滤。主要事件族：

事件族	主要事件
轮次	`turn.started`、`turn.ended`、`turn.step.started` / `completed` / `interrupted` / `retrying`
流式文本	`assistant.delta`、`thinking.delta`（带 `offset` 用于对齐）
工具调用	`tool.call.started`、`tool.call.delta`、`tool.progress`、`tool.result`
交互	`event.approval.requested` / `resolved`、`event.question.requested` / `answered` / `dismissed`
subagent	`subagent.spawned` / `started` / `suspended` / `completed` / `failed`
后台	`task.started` / `terminated`、`shell.started` / `output` / `completed`
其他	`compaction.`、`skill.activated`、`goal.updated`、`prompt.`、`error`、`warning`

有三个全局生命周期事件可以让跨工作区概览免掉逐工作区轮询。event.session.archived 在在线归档与冷归档两条路径上都会发出；其事件帧 session_id 是全局水位 __global__，真实会话 id 在 payload 里：{ "type": "event.session.archived", "workspace_id": "wd_...", "sessionId": "session_..." }（payload 字段为 workspace_id / sessionId）。event.workspace.created / updated 携带完整工作区对象（{ id, root, name, created_at, last_opened_at, session_count }——会话创建触碰工作区时也会发 updated），event.workspace.deleted 携带 { "workspace_id", "root" }。这些事件只覆盖本服务进程内的变更；其他进程（例如写同一 home 目录的 CLI）的变更要等索引 reconcile（约一分钟）才可见，因此概览客户端应保留低频兜底轮询。目前没有会话删除事件。

事件另分持久与易失两种：持久事件带严格递增的 seq，落盘并可回放；易失事件（各 *.delta、tool.progress、shell.* 等）标 volatile: true，不回放。消费易失文本流时用 offset（该轮次内的累计字符偏移）与本地已累积文本比对：小于本地长度说明是重复帧，大于说明有缺漏、需走快照恢复。

断线恢复

重连后在 subscribe 的 cursors 里带上每个会话最后应用事件的 {seq, epoch}，服务端会回放缺口；落后超过缓冲（1000 条）或游标失效时改为收到 resync_required。此时调用 GET /api/v1/sessions/{session_id}/snapshot 拿全量快照（含 as_of_seq 与 epoch），再以新游标重新订阅。

转录协议

subscribe_v2 的 transcript 按 agent 指定粒度：off / turn / block / delta（键 "*" 表示默认粒度），粒度越高推送越细。粒度非 off 的 agent 走两帧推送：transcript.reset（基线快照，历史经 REST 分页回读）和 transcript.ops（增量批次，带每个 agent 连续递增的 seq）；该 agent 的旧式事件在同一连接上被抑制，改由转录帧承载。断线时用 transcript_since 续传；服务端批次日志无法覆盖缺口时（REST 补漏返回 complete: false）需全量刷新。REST 侧对应 GET .../transcript（按轮次分页）与 GET .../transcript/ops?since_seq=（批次补漏）。

二进制与流式端点

以下端点返回二进制流而非 JSON 载荷，各端点的 HTTP 能力并不相同：

方法与路径	说明	Range 分段（206）	ETag / 304
`GET /api/v1/files/{file_id}`	下载已上传文件	支持	不支持（会发送 `etag` 头，但不处理 `If-None-Match`）
`GET /api/v1/sessions/{session_id}/fs/{path}:download`	下载会话工作区文件	支持	支持
`GET /api/v1/fs:content`	读取本机任意文件（仅受 token 保护，谨慎暴露端口）	支持	支持
`POST /api/v1/sessions/{session_id}/export`	导出会话与诊断信息（zip 流）	不支持	不支持

错误语义也不相同：GET /api/v1/files/{file_id} 对查找和存储失败返回真实 404 / 500 状态码（参数校验失败仍走 HTTP 200 信封），其余三个端点的所有失败都走标准响应信封——客户端在这三个端点上仍需检查信封中的 code。

下一步

在网页中使用 — 启动服务并在浏览器中使用 Kimi Code
kimi 命令 — kimi web 的全部命令行选项

服务 API ​

基础约定 ​

地址 ​

鉴权 ​

响应信封 ​

错误码 ​

分页 ​

用 API 驱动一个会话 ​

REST 端点 ​

服务与元信息 ​

GET /api/v1/healthz ​

GET /api/v1/meta ​

POST /api/v1/shutdown ​

登录与用量 ​

GET /api/v1/auth ​

POST /api/v1/oauth/login ​

GET /api/v1/oauth/login ​

DELETE /api/v1/oauth/login ​

POST /api/v1/oauth/logout ​

GET /api/v1/oauth/usage ​

GET /api/v1/oauth/userinfo ​

GET /api/v1/oauth/region ​

配置 ​

GET /api/v1/config ​

POST /api/v1/config ​

模型与供应商 ​

GET /api/v1/models ​

POST /api/v1/models/{model_id}:set_default ​

GET /api/v1/providers ​

POST /api/v1/providers ​

GET /api/v1/providers/{provider_id} ​

PUT /api/v1/providers/{provider_id} ​

DELETE /api/v1/providers/{provider_id} ​

POST /api/v1/providers/{provider_id}:refresh ​

POST /api/v1/providers:refresh ​

POST /api/v1/providers:refresh_oauth ​

POST /api/v1/providers:import_catalog ​

POST /api/v1/providers:import_registry ​

GET /api/v1/catalog/providers ​

GET /api/v1/catalog/providers/{catalog_id} ​

会话 ​

session 对象 ​

POST /api/v1/sessions ​

GET /api/v1/sessions ​

GET /api/v1/sessions/{session_id} ​

GET /api/v1/sessions/{session_id}/profile ​

POST /api/v1/sessions/{session_id}/profile ​

POST /api/v1/sessions/{session_id}/title/generate ​

POST /api/v1/sessions/{session_id}:{action} ​

POST /api/v1/sessions/{session_id}:fork ​

POST /api/v1/sessions/{session_id}:compact ​

POST /api/v1/sessions/{session_id}:undo ​

POST /api/v1/sessions/{session_id}:abort ​

POST /api/v1/sessions/{session_id}:btw ​

POST /api/v1/sessions/{session_id}:archive ​

POST /api/v1/sessions/{session_id}:restore ​

GET /api/v1/sessions/{session_id}/children ​

POST /api/v1/sessions/{session_id}/children ​

GET /api/v1/sessions/{session_id}/status ​

GET /api/v1/sessions/{session_id}/goal ​

GET /api/v1/sessions/{session_id}/warnings ​

GET /api/v1/sessions/{session_id}/runtime ​

POST /api/v1/sessions/{session_id}/runtime ​

POST /api/v1/sessions/{session_id}/export ​

GET /api/v1/sessions/{session_id}/snapshot ​

GET /api/v1/sessions/{session_id}/media/{file_id} ​

消息与转录 ​

GET /api/v1/sessions/{session_id}/messages ​

GET /api/v1/sessions/{session_id}/messages/{message_id} ​

GET /api/v1/sessions/{session_id}/transcript ​

GET /api/v1/sessions/{session_id}/transcript/ops ​

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

GET /api/v1/sessions/{session_id}/transcript/plan ​

提示词 ​

GET /api/v1/sessions/{session_id}/prompts ​

POST /api/v1/sessions/{session_id}/prompts ​

POST /api/v1/sessions/{session_id}/prompts:steer ​

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

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

审批与提问 ​

服务 API

基础约定

地址

鉴权

响应信封

错误码

分页

用 API 驱动一个会话

REST 端点

服务与元信息

`GET /api/v1/healthz`

`GET /api/v1/meta`

`POST /api/v1/shutdown`

登录与用量

`GET /api/v1/auth`

`POST /api/v1/oauth/login`

`GET /api/v1/oauth/login`

`DELETE /api/v1/oauth/login`

`POST /api/v1/oauth/logout`

`GET /api/v1/oauth/usage`

`GET /api/v1/oauth/userinfo`

`GET /api/v1/oauth/region`

配置

`GET /api/v1/config`

`POST /api/v1/config`

模型与供应商

`GET /api/v1/models`

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

`GET /api/v1/providers`

`POST /api/v1/providers`

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

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

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

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

`POST /api/v1/providers:refresh`

`POST /api/v1/providers:refresh_oauth`

`POST /api/v1/providers:import_catalog`

`POST /api/v1/providers:import_registry`

`GET /api/v1/catalog/providers`

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

会话

session 对象

`POST /api/v1/sessions`

`GET /api/v1/sessions`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

消息与转录

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

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

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

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

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

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

提示词

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

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

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

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

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

审批与提问