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

服务 API

kimi web 启动的本地服务暴露两组程序化接口：REST API（/api/v1，另有 /api/v2/sessions）和 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 的生成与轮换见 本地服务与 API：鉴权。

鉴权失败返回 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 页码模式作为替代。

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

鉴权就绪状态快照：服务是否具备可用的模型配置，以及托管供应商的登录状态。当至少配置了一个供应商、设置了默认模型、且托管供应商（如存在）未被吊销时，ready 为 true。

成功时 data 携带 ready（布尔值）、providers_count（已配置供应商数量）、default_model（全局默认模型别名，或 null）与 managed_provider（null，或 { name, status }，其中 status 为 authenticated / expired / revoked / unauthenticated 之一）。

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" 的简写。更新成功后，服务会广播全局 event.config.changed 事件，携带变更的字段名与完整的更新后配置；被拒绝的补丁（值非法或持久化失败）返回 40001 与底层错误信息。

请求体是部分配置对象——上述响应域中除 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	取消任务

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 是唯一的动作——单独的任务 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 为最终状态

技能、工具与 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/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 }。每页额外携带 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" } } ],
        "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_..."
}

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.*。
• 会话事件：只发给订阅了该会话的连接，受 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。

下一步

• 本地服务与 API — 启动、鉴权与端到端调用流程
• kimi 命令 — kimi web 的全部命令行选项