kimi-code/docs/zh/reference/server-api.md

服务 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 生成。两者都需要鉴权；当本页与在线规范不一致时，以在线规范为准。

::: warning 注意 本页描述的 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 响应统一包在信封里：

{
  "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。

1. 确认服务状态：

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 状态码只表达传输层结果。

2. 创建会话，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。

3. 连接 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]] },
    }),
  );

4. 提交提示词：

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（轮次结束）。

5. 随时可以用 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 登录和 auto_session_title 实验开关；未提供 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 成一个禁用工具调用的子 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	撤销信任

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

{
  "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 计数。

{
  "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：

{
  "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 表示整个会话
watch_fs_add / watch_fs_remove	{ session_id, paths, recursive? }	订阅 / 取消文件变更通知（event.fs.changed）
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 的全部命令行选项