Skip to content

服务与配置接口 ​

本页列出不绑定单个会话的服务级接口和配置接口。会话相关接口见 会话接口,文件接口见 文件接口,鉴权、响应信封、错误码和分页等通用约定见 服务 API。

路径中的 :{action} 后缀是动作约定:对单个资源或资源集合 POST 到 路径:动作,执行非 CRUD 操作(如会话的 :fork、:archive,供应商集合的 :refresh)。

服务与元信息 ​

这一组接口报告服务实例本身的信息,并提供探活和关闭入口。

方法与路径说明
GET /api/v1/healthz探活,免鉴权
GET /api/v1/meta服务版本、能力集、server_id、实验开关
POST /api/v1/shutdown优雅退出(先回 200 再关闭);绑定在 loopback 地址或以 --allow-remote-shutdown 启动时才挂载

GET /api/v1/healthz ​

探活接口,供脚本和进程管理器使用。它是唯一不需要 bearer token 的 /api 接口(见 鉴权),应答时不触碰配置和引擎。

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

GET /api/v1/meta ​

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

字段类型说明
server_versionstring服务版本
capabilitiesobject能力集:websocket、file_upload、fs_query、mcp、tasks,值恒为 true
server_idstring本服务实例的唯一 id
started_atstring启动时间,ISO 8601 格式
open_in_appsarray可作为 open-in 目标的宿主应用:finder / cursor / vscode / iterm / terminal。目前恒为空
dangerous_bypass_authboolean服务是否以 --dangerous-bypass-auth 启动(为 true 时客户端可以跳过 token 提示)
backendstring引擎后端:v1 / v2。本服务恒为 v2
web_titlestring来自 --web-title 的自定义浏览器标签页标题,未设置时省略
experimental_flagsobject实验开关 id → 是否启用,在请求时解析
featuresarray引擎 feature,每项为 { name, state, meta }。state 为 Pending / Activating / Active / Unloading / Failed

POST /api/v1/shutdown ​

请求服务优雅退出。服务端先发出响应,随后立即执行关闭,因此调用方收到的响应是可信的。

服务绑定在 loopback 地址,或以 --allow-remote-shutdown 启动时,才会挂载这个接口。其他情况下服务端不注册这个路由,请求得到 404。

成功时 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 失败。

字段类型说明
models_readyboolean默认模型能否解析到已配置的供应商,判断规则见上文
providers_countinteger已配置的供应商数量
managed_providerobject | null托管供应商的登录状态
managed_provider.namestring托管供应商名称
managed_provider.statusstringauthenticated / expired / revoked / unauthenticated

本接口不返回全局默认模型别名,改从 GET /api/v1/config 的 default_model 读取。

POST /api/v1/oauth/login ​

为托管供应商发起 OAuth device-code 登录流程。发起新流程会中止同一供应商进行中的流程。账号已登录时不需要用户交互,响应直接报告 authenticated。

参数位置类型说明
providerbodystring托管供应商名称。默认 managed:kimi-code
regionbodystringmainland-cn / global。覆盖 GET /api/v1/oauth/region 的区域解析结果,只对本次流程生效

成功时 data.status 为 pending 或 authenticated。账号已登录时,data 只有 flow_id、provider 和 status: "authenticated"。流程进行中时,data 字段如下:

字段类型说明
flow_idstring流程 id
providerstring托管供应商名称
statusstringpending
verification_uristring验证页地址,打开后输入 user_code
verification_uri_completestring可以直接打开的验证页地址,不需要再输入 user_code
user_codestring在 verification_uri 页面输入的用户码
expires_ininteger流程时限,单位秒。与 expires_at 表示同一时限
intervalinteger轮询间隔,单位秒
expires_atstring流程过期时间

拿到进行中的流程后,打开 verification_uri_complete(或打开 verification_uri 并输入 user_code),然后每隔 interval 秒轮询 GET /api/v1/oauth/login,直到流程完结或超过 expires_at。

GET /api/v1/oauth/login ​

轮询某个供应商的登录流程状态。

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

尚未发起过流程时,data 为 null。否则 data 为流程快照,包含 POST /api/v1/oauth/login 进行中形态的全部字段,以下字段的取值不同或为新增:

字段类型说明
statusstringpending / authenticated / denied / expired / cancelled
resolved_atstring流程离开 pending 后出现,记录流程到达终态的时间
error_messagestring描述失败的流程,可省略

DELETE /api/v1/oauth/login ​

取消某个供应商进行中的登录流程。没有进行中的流程时,本次调用不做任何操作,返回最近一次已知状态。

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

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

POST /api/v1/oauth/logout ​

登出托管供应商:丢弃已存储的 OAuth 凭据,中止进行中的登录流程,并把托管供应商从配置中移除。OAuth 托管的供应商不能手动编辑或删除(见 PUT / DELETE /api/v1/providers/{provider_id}),要移除它只能先登出。

登出默认 Kimi 供应商(managed:kimi-code)时,服务端还会拆除本机的远程控制,并清除缓存的远程控制云端会话。登出其他供应商不影响远程控制。拆除顺序取决于隧道由谁持有:

  • 没有隧道运行,或隧道由本机其他进程持有:服务端先把本机设备下线并持有本机锁,确保凭据被丢弃之前本机任何进程都无法再次开启远程控制。清理失败时,登出中止。
  • 隧道由本服务持有:服务端先丢弃凭据,响应发出后随即拆除隧道,因此通过远程控制链接发起的登出仍能收到响应。
参数位置类型说明
providerbodystring托管供应商名称。默认 managed:kimi-code

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

  • 50001:登出默认 Kimi 供应商时,远程控制清理或登出本身失败

GET /api/v1/oauth/usage ​

读取托管账号的套餐额度和加油包,数据实时取自账号服务。账号服务出错时信封仍然成功,错误放在 data 里返回。

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

成功时 data.kind 为 ok 或 error:

字段类型说明
quota.usagesobject仅 ok:各时间窗口的用量,键为 limit5h、limit7d、monthTotal、monthCode,客户端按实际下发的键渲染。每项为 { usedRatio, resetAt? }:usedRatio 是 0–1 的已用比例(浮点数),resetAt 是 RFC3339 格式的重置时间
quota.extraUsageobject | null仅 ok:按量付费钱包,字段为 balanceCents、totalCents、monthlyChargeLimitEnabled、monthlyChargeLimitCents、monthlyUsedCents、currency
messagestring仅 error:错误信息
statusinteger仅 error:账号服务返回的 HTTP 状态码,没有时省略

GET /api/v1/oauth/userinfo ​

读取托管账号的资料。账号服务出错时的处理方式与 GET /api/v1/oauth/usage 相同:信封仍然成功,错误放在 data 里返回。

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

成功时 data.kind 为 ok 或 error:

字段类型说明
userInfoobject仅 ok:账号资料。始终包含 userId、nickname、status、region、userLevel、userLevelName、domain、domainName;可能附加 globalId、bio、avatar、username、email、phone({ countryCode, number })、createdTime 和 lastLoginTime
messagestring仅 error:错误信息
statusinteger仅 error:账号服务返回的 HTTP 状态码,没有时省略

GET /api/v1/oauth/region ​

解析客户端所属的 Kimi 区域。结果在本地推导,不做网络探测。服务端按以下顺序取第一个能决定区域的输入:环境变量或配置固定的 OAuth host,已配置的 OAuth key,<home>/region 中的安装渠道标记。

客户端未登录、且上述输入都无法决定区域时,服务端根据设备时区和语言环境推断。推断出明确结果时,服务端把它缓存到 <home>/region.json,之后直接使用缓存;客户端登录后缓存被清除。原始时区和语言环境值不会上传。

信号缺失或冲突时,本次进程回退到 mainland-cn,但不持久化这个结果,下次启动时重新判断。设置 KIMI_CODE_REGION_MARKER=off 可以同时禁用安装渠道标记和本地推断;设置了 KIMI_CODE_BASE_URL 时也不做本地推断。

成功时 data 为 { region },region 为 mainland-cn / global。

远程控制 ​

这一组接口管理机器级的远程控制隧道(见 远程控制指南)和账号的设备注册表。隧道状态按机器区分。设备注册表按账号区分、保存在云端,因此设备接口需要 Kimi 登录;服务端持有登录会话,把请求代理到 relay,OAuth 凭据不会暴露给调用方。

方法与路径说明
GET /api/v1/remote-control读取隧道状态
POST /api/v1/remote-control开启或关闭隧道
GET /api/v1/remote-control/devices列出账号下的设备
PATCH /api/v1/remote-control/devices/{id}重命名设备
POST /api/v1/remote-control/devices/{id}/deactivate让设备下线
DELETE /api/v1/remote-control/devices/{id}从注册表中删除设备

GET /api/v1/remote-control ​

返回当前隧道状态。隧道处于关闭状态、但本机另一个存活进程持有单实例锁时,data.conflict 携带锁持有者的信息。隧道关闭时,每次读取都会重新检查锁;持有者进程退出后,conflict 和已存的 error 一并清除。

成功时 data 为隧道状态对象:

字段类型说明
enabledboolean远程控制开关
statestringoff / starting / on / stopping
urlstring隧道地址,可省略
device_idstring本机设备标识,可省略
device_namestring本机设备名称,可省略
errorstring错误信息,可省略
conflictobject锁持有者信息,只在上述冲突时出现:{ pid, local_origin, device_id, url, started_at }

POST /api/v1/remote-control ​

开启或关闭隧道。

参数位置类型说明
enabledbodybooleantrue 开启隧道,false 关闭隧道

成功时 data 为隧道状态对象,与 GET /api/v1/remote-control 相同。

  • 40001(VALIDATION_FAILED):开启时服务没有绑定在 loopback 地址,或以 --dangerous-bypass-auth 启动
  • 40928(REMOTE_CONTROL_ALREADY_RUNNING):开启时本机另一个存活进程持有单实例锁。details 携带锁持有者信息,结构与 conflict 相同
  • 50001(INTERNAL_ERROR):开启或关闭隧道失败

GET /api/v1/remote-control/devices ​

从云端注册表列出账号下的远程控制设备。

成功时 data 为 { devices, max_devices? },max_devices 是设备数量上限。devices 每项字段如下:

字段类型说明
device_idstring设备标识
aliasstring显示名称
statusstringonline / offline
platformstring设备平台
client_versionstring客户端版本
local_base_urlstring设备本地服务地址
created_atstring创建时间
updated_atstring更新时间
last_remote_access_atstring最近一次远程访问时间
  • 50001(INTERNAL_ERROR):请求云端注册表失败

PATCH /api/v1/remote-control/devices/{id} ​

重命名设备。

参数位置类型说明
idpathstring设备标识
aliasbodystring新的显示名称,去除首尾空白后为 1–50 个字符

成功时 data 为 { ok: true }。

  • 40001(VALIDATION_FAILED):名称为空或超长。服务端在请求云端之前就返回
  • 50001(INTERNAL_ERROR):请求云端注册表失败

POST /api/v1/remote-control/devices/{id}/deactivate ​

在云端注册表中把设备置为离线。离线设备保留在列表中,不占用套餐的设备额度;该设备下次开启远程控制时恢复在线。

目标设备是本机时,服务端先停止本地隧道(启动中的开启会被取消),再持有本机锁完成下线,确保并发的开启无法在成功响应之后重新注册设备。

参数位置类型说明
idpathstring设备标识

成功时 data 为 { ok: true }。

  • 50001(INTERNAL_ERROR):请求云端注册表失败;目标设备是本机、且锁持有者没有在限定时间内停止时也返回此错误,不报告成功

DELETE /api/v1/remote-control/devices/{id} ​

把设备从云端注册表中移除:设备从列表中消失,仍在连接的隧道被断开。与下线不同,删除不会把设备保留在列表中。

目标设备是本机时,服务端先停止本地隧道,再持有本机锁完成删除,确保设备无法在成功响应之后重新注册。

参数位置类型说明
idpathstring设备标识

成功时 data 为 { ok: true }。

  • 50001(INTERNAL_ERROR):请求云端注册表失败;目标设备是本机、且锁持有者没有在限定时间内停止时也返回此错误

配置 ​

这一组接口读写全局配置(config.toml),并读取由 Kimi Code 服务远程下发的客户端配置。

方法与路径说明
GET /api/v1/config读取全局配置(密钥字段脱敏)
POST /api/v1/config合并式更新配置,并广播 event.config.changed
POST /api/v1/client_configs读取由 Kimi Code 服务远程控制的指定客户端配置

GET /api/v1/config ​

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

成功时 data 为配置对象,字段与 顶层字段 中的顶层域一一对应:

字段类型说明
providersobject供应商 id → { type, base_url?, default_model?, api_key_env?, has_api_key } 的映射
default_providerstring全局默认供应商 id
default_modelstring全局默认模型别名
modelsobject模型别名 → 模型记录的映射
thinkingobjectThinking 模式的默认参数
plan_modebooleanPlan 模式开关
yoloboolean派生值:default_permission_mode 为 yolo 时为 true
default_permission_modestring新会话的默认权限模式
default_plan_modeboolean新会话是否以 Plan 模式启动
permissionobject初始权限规则
hooksarray生命周期钩子
servicesobject内置外部服务配置
merge_all_available_skillsboolean是否合并所有可用目录中的 Agent Skills
extra_skill_dirsarray额外的 Skill 搜索目录
loop_controlobjectAgent 循环控制参数
backgroundobject后台任务运行参数
subagentobjectsubagent 配置
secondary_modelobjectsubagent 的次级模型池
experimentalobject实验开关 id → 是否启用
telemetryboolean是否启用匿名遥测
auto_session_titleboolean是否允许客户端自动生成会话标题
disable_feedback_surveyboolean是否关闭会话评分提示
rawobject原始解析的 config.toml 内容,包含未建模的字段

POST /api/v1/config ​

合并式更新全局配置。请求体中的每个顶层域深合并进对应的域,请求体中没有出现的域保持不变。

请求体是部分配置对象:可以包含 GET /api/v1/config 响应中除 raw 外的任意顶层域,全部可选,类型和含义与响应表相同。以下两个域有额外的写入规则:

  • yolo:true 是 default_permission_mode: "yolo" 的简写;false 被忽略。
  • default_permission_mode:取值为 manual / yolo / auto。

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

每一次配置变更都会广播全局事件 event.config.changed(见 全局事件),包括经本接口成功更新、在进程外编辑 config.toml,以及服务端内部写入(如 OAuth 登录刷新)。短时间内的多次变更合并为一个事件:changedFields 携带受影响的域名(camelCase 配置域,例如 defaultModel),config 携带当前完整的配置投影(形状与 GET /api/v1/config 的响应相同)。

  • 40001:补丁被拒绝(值非法或持久化失败),响应带底层错误信息

POST /api/v1/client_configs ​

读取由 Kimi Code 服务远程控制的指定客户端配置,包括哪些模型或思考强度的切换需要用户确认,以及客户端的升级策略。服务端从账号所在区域的 Kimi Code 服务读取(设置了 KIMI_CODE_BASE_URL 时改用该地址),并把结果规范化成该名称预期的结构。

参数位置类型说明
namebodystring必填。model_switch_confirm / effort_switch_confirm / client_upgrade_policy

成功时 data 为 { name, config }。名称不在上述范围内或读取失败时,config 为 null,客户端回退到内置行为。

读到的值不会变成 null:缺失或格式不对的字段取关闭状态的默认值。例如格式不对的 model_switch_confirm 返回 { enable: false, rules: [] }。

模型与供应商 ​

这一组接口管理模型配置的两部分: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(201)/ import_registry(201)
GET /api/v1/catalog/providers浏览 models.dev 目录(服务端代理)
GET /api/v1/catalog/providers/{catalog_id}读取目录中的单个条目

GET /api/v1/models ​

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

成功时 data.items 为模型数组,每项字段如下:

字段类型说明
providerstring所属供应商 id
modelstring别名 id:供应商管理的别名为 provider_id/model,其余为裸键
display_namestring显示名,可省略
max_context_sizeinteger上下文窗口,单位 token
capabilitiesarray能力标志,可省略
support_effortsarray支持的 Thinking 模式 effort 档位,可省略
default_effortstring默认 effort 档位,可省略
upgradeobject自定义 registry 模型可以携带,用于引导用户切换到替代模型
upgrade.modelstring替代模型
upgrade.migration_markdownstring迁移说明,其中的占位符已替换为模型 ID
upgrade.retirement_atstring退役时间,可省略

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_idpathstring必填。配置中的模型别名键原样,含 / 时需要 URL 编码

成功时 data 为 { default_model, model }:default_model 是当前生效的别名,model 是它的目录项(形态与 GET /api/v1/models 的单项相同)。

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

GET /api/v1/providers ​

列出每个已配置的供应商及其凭据和模型发现状态,不泄露任何密钥。这里的条目形态也是其他供应商接口引用的「供应商条目」。

成功时 data.items 为供应商条目数组:

字段类型说明
idstring供应商 id
typestring通信协议,原样返回配置中的值(通过本组接口写入的取值见 POST /api/v1/providers 的 type),配置未设置时为 openai
base_urlstringAPI 基础 URL,未设置时省略
default_modelstring该供应商的默认模型别名。供应商未设置、但全局 default_model 属于该供应商时取全局值,否则省略
api_key_envstring读取 API 密钥的环境变量名,未设置时省略
has_api_keyboolean是否有可用的 API 密钥:配置了非空的 api_key,或 api_key_env 指向的环境变量有值,或供应商的 env 中提供了密钥
statusstring凭据配置冲突(api_key 与 api_key_env 同时存在,或其中之一与 OAuth 同时存在)时为 error;否则存在 API 密钥或缓存的 OAuth token 时为 connected,都没有时为 unconfigured
modelsarray该供应商的模型别名 id

POST /api/v1/providers ​

一次保存创建供应商及其模型别名,成功时返回 HTTP 201 和标准信封。全局 default_model 完全未配置时(全新安装),服务端用新供应商的 default_model(或第一个模型)作为初始值;已有的默认值不会被修改。

凭据二选一:api_key 直接存储密钥,api_key_env 改为记录读取密钥的环境变量名。两者同时传入非空值时请求被拒绝。

参数位置类型说明
idbodystring必填。供应商 id,只能包含字母、数字、-、_ 和空格,必须以字母或数字开头
typebodystring必填。通信协议:kimi / openai / openai_responses / anthropic / bedrock / google-genai / vertexai
api_keybodystringAPI 密钥,存储在 config.toml 中
api_key_envbodystring读取 API 密钥的环境变量名。服务端只存储变量名,不存储密钥
base_urlbodystringAPI 基础 URL,不能包含环境变量占位符(${...})
default_modelbodystring该供应商的默认模型,必须是 models[].model 之一
modelsbodyarray必填。至少一条,model 值不能重复;条目结构见下表

每个 models[] 条目声明一个别名,别名 id 为 id/model:

字段类型说明
modelstring必填。上游模型名
max_context_sizeinteger必填。上下文窗口,单位 token,≥ 1
display_namestring显示名
capabilitiesarray能力标志,如 thinking 或 image_in
protocolstring线路协议覆盖:anthropic、openai 或 openai_responses;省略时按模型 ID 推断
max_output_sizeinteger最大输出 token 数,≥ 1
support_effortsarray支持的 Thinking 模式 effort 档位
adaptive_thinkingboolean自适应 thinking 开关

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

  • 40001:请求体校验失败,或 api_key 与 api_key_env 同时传入非空值
  • 40921:已存在该 id 的供应商

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

读取单个供应商。与列表接口不同,设置了密钥时响应会返回存储的 api_key,供本地编辑表单预填。对外暴露服务端口时要考虑这一点。

参数位置类型说明
provider_idpathstring必填。供应商 id

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

  • 40412:供应商不存在

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

一次保存整体替换供应商。type、base_url 和模型列表被重写,该供应商的别名按 models 重建:不再列出的别名从 config.toml 中消失,其他供应商的别名不受影响。除 new_id 重命名引起的迁移外,本接口不修改全局默认指针。

api_key 和 api_key_env 各有三种写法:省略表示保留已存的值,"" 表示清除,其他值表示替换。两者互斥:其中一个传入非空值时,另一个被清除;两者同时传入非空值时请求被拒绝。

参数位置类型说明
provider_idpathstring必填。当前供应商 id
new_idbodystring重命名供应商。providers 键、模型别名、default_provider、指向旧别名的 default_model 以及 subagent 次级模型池都随之迁移。id 规则与 POST /api/v1/providers 相同
typebodystring必填。通信协议:kimi / openai / openai_responses / anthropic / bedrock / google-genai / vertexai
api_keybodystringAPI 密钥,三种写法见上文
api_key_envbodystring读取 API 密钥的环境变量名,三种写法见上文
base_urlbodystringAPI 基础 URL,不能包含环境变量占位符(${...})
default_modelbodystring该供应商的默认模型,必须是 models[].model 之一
modelsbodyarray必填。至少一条,model 值不能重复;条目结构与 POST /api/v1/providers 相同

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

  • 40001:请求体校验失败、api_key 与 api_key_env 同时传入非空值,或重命名后的别名 id 会与其他供应商的别名冲突
  • 40003:供应商由 OAuth 托管,需改用 POST /api/v1/oauth/logout 登出
  • 40412:供应商不存在
  • 40921:new_id 已被占用

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

删除供应商及其全部模型别名,并级联清理 subagent 次级模型池。全局 default_provider / default_model 指针保持不变,即使它们指向被删除的供应商;这两个值是用户的设置,本接口不代为回收。

参数位置类型说明
provider_idpathstring必填。供应商 id

成功时返回 HTTP 204,没有响应体,状态码本身表示删除成功(见 响应信封)。

  • 40003:供应商由 OAuth 托管,需改用 POST /api/v1/oauth/logout 登出
  • 40412:供应商不存在

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

从上游来源重新发现单个供应商的模型元数据,并重写该供应商的别名。模型来源为静态的供应商不发起网络请求,直接报告 unchanged。

本接口和集合级的 :refresh、:refresh_oauth 都遵循同一条广播规则:刷新报告的 changed 非空(至少一个供应商的别名或托管模型元数据发生变化)时,服务端广播全局事件 event.model_catalog.changed(见 全局事件),事件内容与刷新报告相同。

参数位置类型说明
provider_idpathstring必填。供应商 id

成功时 data 为刷新报告:

字段类型说明
changedarray有变化的供应商,每项为 { provider_id, provider_name, added, removed },added / removed 是新增 / 移除的别名数
unchangedarray无差异的供应商 id
failedarray刷新失败的供应商,每项为 { provider, reason }
retired_defaultobject可选。刷新发现 registry 移除了当前默认模型、且该模型此前声明过 upgrade 替代模型时出现,为 { from, to, from_display_name }

出现 retired_default 时,默认模型已重定向为 to,仍绑定 from 的已打开会话也已切换到 to;from_display_name 是被移除模型的显示名,供提示使用。event.model_catalog.changed 事件中也会出现同一字段。

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

POST /api/v1/providers:refresh ​

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

成功时 data 为刷新报告,结构与 POST /api/v1/providers/{provider_id}:refresh 相同,同样可能带 retired_default。

POST /api/v1/providers:refresh_oauth ​

只刷新托管供应商 managed:kimi-code 的模型列表。该供应商不存在或不是 OAuth 托管时,不做任何刷新,返回空报告。请求体可选,内容被忽略。

成功时 data 为刷新报告,只含 changed / unchanged / failed,不带 retired_default。

POST /api/v1/providers:import_catalog ​

把一个 models.dev 目录条目导入为已配置的供应商,成功时返回 HTTP 201 和标准信封。通信协议和端点来自目录解析,目录中的每个模型都写为一个别名。

导入已存在的 id 等同于刷新:供应商条目及其别名按目录重写,省略 api_key 时保留已存密钥。本接口不修改已有的全局默认指针;只有完全没有配置默认模型时,才用第一个导入的模型作为 default_model 的初始值。

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

成功时 data 为 { provider, models_imported }: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 相同。

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

成功时 data 字段如下:

字段类型说明
providersarray导入的供应商条目
models_importedinteger写入的别名总数
credential_envobject供应商 id → 环境变量名的映射。注册表为某个供应商声明了 API 密钥环境变量时,取其中第一个非空的变量名
  • 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 为目录条目数组:

字段类型说明
idstring目录条目 id
namestring条目名称
wire_typestring | null解析出的协议,枚举与供应商 type 相同
base_urlstring | null解析出的端点。needs_base_url 为 true 或被拒绝的条目为 null
guessedboolean是否为启发式解析的结果
needs_base_urlboolean导入时是否要求提供 base URL
rejectedboolean服务端是否无法导入该条目
reject_reasonstring | null机器可读的拒绝原因
env_keystring | null上游约定的 API 密钥环境变量
modelsarray每项为 { id, name?, max_context_size, capabilities?, reasoning }
  • 50004:目录不可用(在线拉取与内置快照均失败)

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

按 catalog id 读取单个 models.dev 目录条目。

参数位置类型说明
catalog_idpathstring必填。目录条目 id

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

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

Skill、工具与 MCP ​

查看工作区可见的 Skill 目录与当前生效 Agent 的工具列表。MCP 服务注册表与 OAuth 管理见 MCP 管理;会话级的 Skill 目录与 Skill 激活(斜杠命令 /<skill> 的 REST 等价形式)见 会话 Skill。

方法与路径说明
GET /api/v1/workspaces/{workspace_id}/skills无会话的工作区 Skill 目录
GET /api/v1/tools列出当前生效 Agent 的工具
/api/v1/mcp/*MCP 服务注册表增删改查、探测与 OAuth 管理,见 MCP 管理

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

列出该工作区中的会话会看到的 Skill 目录,不创建也不恢复会话。目录针对工作区的主目录和额外源文件夹计算,合并的来源与会话相同:内置、插件、extra、用户、项目。

参数位置类型说明
workspace_idpathstring必填。已注册工作区 id

成功时 data 为 { skills },每项是一个 Skill 描述符,与 会话 Skill 返回的结构相同:

字段类型说明
namestringSkill 名称。同名 Skill 可以以不同 path 作为多个变体返回
descriptionstringSkill 描述
pathstringSkill 的路径
sourcestringproject / user / extra / builtin
workspace_dirstring项目级 Skill 的根目录,其他来源省略
typestring可选。Skill 类别,只有用户可激活的类型才能被激活
disable_model_invocationboolean可选。为 true 时 Skill 对模型不可见
scopesstring[]可选。Skill 声明的适用客户端:tui / web
  • 40410:工作区不存在

GET /api/v1/tools ​

列出当前生效 Agent 的工具。当前生效 Agent 是所选会话的 main agent,会话的取法有两种:

  • 传入 session_id:服务端按需恢复该会话,冷会话也会被加载到本服务进程中。会话不存在时列表为空。
  • 省略 session_id:取最近创建的会话,但不恢复它。该会话不在本服务进程中存活时列表为空,不会回退到更早的存活会话。
参数位置类型说明
session_idquerystring要查看其 main agent 的会话。默认最近创建的会话

成功时 data 为 { tools },每项字段如下:

字段类型说明
namestring工具名
descriptionstring工具描述
input_schemanull目前恒为 null
sourcestringbuiltin / skill / mcp
mcp_server_idstring仅 MCP 工具携带,从 mcp__<server>__<tool> 形式的工具名解析
activeboolean可选。工具策略的判定结果

能力与插件 ​

查询内置能力的就绪状态并安装能力,以及管理插件从市场浏览、安装到移除的整个过程。

能力是内置特性,由检测步骤和后台安装两部分组成,就绪状态分级(见 能力状态对象 的 state)。当前版本注册了 kimi-cu(Kimi Computer Use)与 kimi-webbridge(Kimi Browser Extension)。插件是已安装的 Skill、MCP 服务、hook 与命令的打包集合。

方法与路径说明
GET /api/v1/capabilities列出内置能力及其就绪状态
GET /api/v1/capabilities/{capability_id}读取单个能力的状态
POST /api/v1/capabilities/{capability_id}:install开始安装能力(后台进行,轮询 GET 查看进度)
GET /api/v1/plugins列出已安装插件
GET /api/v1/plugins/{plugin_id}读取已安装插件及其声明的能力
POST /api/v1/plugins安装自定义插件,或安装指定预期版本的市场条目
POST /api/v1/plugins/preview只读检查市场条目的能力,不安装插件
GET /api/v1/plugins/marketplace插件市场目录,合并实时安装状态
POST /api/v1/plugins/{plugin_id}:enable启用插件
POST /api/v1/plugins/{plugin_id}:disable停用插件
POST /api/v1/plugins/{plugin_id}:remove移除插件

能力状态对象 ​

所有能力接口都返回这个结构。

字段类型说明
idstring能力 id
pluginIdstring可选。插件 id
displayNamestring展示名称
descriptionstring描述
supportedboolean当前平台是否支持
statestringready(所有必需检测步骤均为 ok)/ partial(部分步骤为 ok)/ not_installed / unsupported(当前平台 / 架构不可用)
versionstring可选。版本
stepsarray各检测步骤,每项为 { id, state, detail?, optional? },其中 state 为 ok / missing / failed
install.runningboolean是否正在安装
install.stepstring可选。当前安装步骤
install.percentnumber可选。安装进度,取值 0 到 100
install.errorstring可选。安装错误
install.notestring可选。安装说明
install.confirmationRequiredstring可选。为 stop-processes 时,安装因相关进程仍在运行而停止,需要用户确认后带 stopRunningProcesses: true 重新安装

GET /api/v1/capabilities ​

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

成功时 data 为 { capabilities },每项是一个 能力状态对象。

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

读取单个能力的就绪状态。安装能力后,客户端轮询这个接口查看进度。

参数位置类型说明
capability_idpathstring必填。能力 id

成功时 data 为 能力状态对象。

  • 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_idpathstring必填。能力 id
stopRunningProcessesbodyboolean可选。为 true 时允许安装过程停止仍在运行的相关进程。请求体可省略

成功时 data 为 能力状态对象。

目前只有 Windows 上的 kimi-cu 会检查运行中的进程:存在相关进程且没有传 stopRunningProcesses: true 时,后台安装结束,install.confirmationRequired 为 stop-processes。

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

插件摘要 ​

列出、安装插件时返回这个结构,插件详情在它的基础上增加字段。

字段类型说明
idstring插件 id
displayNamestring展示名称
descriptionstring可选。描述
shortDescriptionstring可选。简短描述
longDescriptionstring可选。详细描述
versionstring可选。版本
enabledboolean是否启用
statestringok / error。加载失败时也会置 hasErrors
skillCountintegerSkill 数量
mcpServerCountintegerMCP 服务数量
enabledMcpServerCountinteger已启用的 MCP 服务数量
hookCountintegerhook 数量
commandCountinteger命令数量
hasErrorsboolean是否有错误
sourcestringlocal-path / zip-url / github
originalSourcestring可选。原始来源
githubobject可选。GitHub 来源的插件携带来源信息 { owner, repo, ref, installedSha? },其中 ref 为 { kind, value },kind 为 branch / tag / sha
originstringmarketplace / custom / unknown
catalogIdstring可选。目录 id
installedAtstring安装时间,ISO 时间戳

GET /api/v1/plugins ​

列出已安装插件。

成功时 data 为 { plugins },每项是一个 插件摘要。

GET /api/v1/plugins/{plugin_id} ​

读取已安装插件的详情与能力。skills 和 mcpServers 两份清单都来自插件的真实文件与 manifest。interface.skillOverrides 和 interface.mcpOverrides 只覆盖展示信息,不改变调用名称或运行配置。

参数位置类型说明
plugin_idpathstring必填。已安装插件 id
localequerystring可选。例如 en-US 或 zh-CN,用于读取 interface.locales 中对应语言的翻译,只影响能力的展示文案;未匹配的字段回退到默认 interface

成功时 data 为 插件摘要,另加以下字段:

字段类型说明
rootstring插件根目录
updatedAtstring可选。更新时间
manifestKindstring可选。manifest 类型:kimi-plugin-root / kimi-plugin-dir
manifestPathstring可选。manifest 路径
skillsarray实际发现的 Skill:调用名称 name,以及可选的展示名称 displayName 与描述 description
mcpServersarraymanifest 声明的 MCP 服务:名称、运行时名称、启停状态、传输方式、非敏感连接配置,以及可选的展示名称、描述和图标 URL
shadowedManifestPathstring可选。被遮蔽的 manifest 路径
diagnosticsarray诊断信息,每项为 { severity, message },severity 为 error / warn / info
  • 40419:没有该 id 的已安装插件

POST /api/v1/plugins ​

安装插件并返回其摘要。请求体二选一:自定义安装只传 source;市场安装传 marketplaceId 及预期版本信息,不直接传 source。两种写法都不接受其他字段。

参数位置类型说明
sourcebodystring自定义安装时必填。本地绝对路径、http(s) ZIP URL 或 GitHub URL。GitHub URL 可以用 /tree/<branch-or-sha>、/releases/tag/<tag> 或 /commit/<sha> 锁定版本
marketplaceIdbodystring市场安装时必填。目录条目 id
expectedVersionbodystring市场安装用。用户看到的版本;无版本的自定义条目可省略
expectedSha256bodystring市场安装用。用户看到的 sha256sum(64 位十六进制)。ZIP 条目声明了 sha256sum 时,必须传入且与目录一致;本地目录和 GitHub 条目无需传

市场安装时,服务端从同一份目录快照解析 source、sha256sum 和预期插件 ID,在解压前校验压缩包,并校验 manifest ID。

成功时 data 为 插件摘要。

  • 40001:校验失败,例如 source 既不是 URL 也不是绝对路径,或插件加载失败
  • 40409:本地路径不存在
  • 40419:没有该 id 的市场条目
  • 40934:目录条目已相对用户看到的版本发生变化(刷新目录后重试)

POST /api/v1/plugins/preview ​

只读检查市场条目的能力,不安装插件。服务端把压缩包下载到临时目录,在解压前校验 SHA-256,校验 manifest ID,并发现其中的 Skill 与 MCP 服务。预览不写入安装记录,不安装运行时,也不保留解压后的插件。

参数位置类型说明
marketplaceIdbodystring必填。目录条目 id
expectedVersionbodystring用户看到的版本
expectedSha256bodystring可选。用户看到的 sha256sum(64 位十六进制),提供时必须与当前目录一致
localebodystring可选。展示文案的语言,选择规则与 GET /api/v1/plugins/{plugin_id} 的 locale 相同

成功时 data 为 { skills, mcpServers },例如:

json
{
  "skills": [{ "name": "<Skill 名称>", "description": "<可选描述>" }],
  "mcpServers": [{ "name": "<manifest 中的名称>", "runtimeName": "<运行时名称>", "enabled": true, "transport": "stdio" }]
}

两类条目还可以包含 overrides 提供的 displayName、description,MCP 条目还可以包含 iconUrl。MCP 条目的字段结构与 GET /api/v1/plugins/{plugin_id} 相同,示例只列出常用字段。

  • 40001:请求、压缩包、SHA-256 或 manifest 无效
  • 40419:没有该 id 的市场条目
  • 40934:目录条目已相对用户看到的版本发生变化(刷新目录后重试)

GET /api/v1/plugins/marketplace ​

列出插件市场目录,并合并实时安装状态。默认目录 URL 由当前 managed baseURL 派生为 ${baseURL}/plugins/marketplace,不再注入内置能力条目。

服务端按两个条件过滤条目,两个条件必须同时满足:

  • 宿主:目录中的 clients 把条目限制为 desktop、cli 或两者,缺省时两种宿主均可用。Web 和 Remote Control 使用所连接 server 的宿主身份。
  • 操作系统:platforms 独立按服务端所在的操作系统过滤。platforms 未设置、包含服务端所在的平台,或者只包含 cloud 时,条目保留;其他条目被过滤,包括同时列了 cloud 和其他平台、但不包含服务端所在平台的条目。

cloud-only 条目不能在本机安装。旧 kimi-webbridge 条目不再返回,Computer Use 只返回当前平台对应的接线插件。

安装记录和托管文件仍共享在服务端的数据目录下。当前宿主不可用的条目,也会从该宿主的已安装列表和运行能力中隐藏。

服务端把最近一次成功获取的可用性配置缓存到 plugins/availability.json。目录刷新成功后,客户端规则的变化会隐藏或恢复已有安装,无需重新安装,也不会删除插件文件。

成功时 data 为 { entries },每项字段如下。安装市场条目的请求写法见 POST /api/v1/plugins。

字段类型说明
idstring目录条目 id,市场安装时作为 marketplaceId 传入
tierstring条目层级:official / curated / third-party。条目声明了 distribution 时,distribution.category 为 official 取 official,否则取 curated;没有声明时取条目的 tier,缺省为 third-party
classificationstring条目分类:official / third_party。条目声明了 distribution 时取 distribution.category,否则由 tier 推出:official 取 official,其余取 third_party
displayNamestring展示名称
descriptionstring可选。描述,语言由 defaultLocale 声明
shortDescriptionstring可选。简短描述
longDescriptionstring可选。详细描述
cliDescriptionstring可选。CLI 描述,语言由 defaultLocale 声明
homepagestring可选。主页
keywordsstring[]可选。关键词
versionstring可选。版本
sourcestring条目来源
iconUrlstring可选。图标 URL
sha256sumstring可选。压缩包摘要
filenamestring可选。文件名
localeobject可选。各语言的 displayName、shortDescription、longDescription 和 cliDescription 翻译
defaultLocalestring可选。顶层 description / cliDescription 的语言
platformsstring[]可选。darwin / win32 / linux / cloud
distributionobject可选。分发信息:category 为 official / third_party;可选的 region(string)、defaultInstall(boolean)、weight(number)、userLevel 原样取自目录
billingobject可选。计费信息,原样取自目录
installedobject可选。已安装时携带实时安装状态 { version?, enabled }
updateAvailableboolean可选。有可用更新时为 true,否则省略
capabilityIdstring可选。只由服务端标注,且只在使用默认市场时标注:kimi-browser-extension 映射到 kimi-webbridge 能力,kimi-cu / kimi-cu-win 映射到 kimi-cu 能力
  • 50001:市场不可达或返回了非法目录

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

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

参数位置类型说明
plugin_idpathstring必填。已安装插件 id

成功时 data 为 { ok: true }。

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

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

停用一个已安装插件,但不移除它。分发规则同 :enable。

参数位置类型说明
plugin_idpathstring必填。已安装插件 id

成功时 data 为 { ok: true }。

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

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

移除一个已安装插件。分发规则同 :enable。

参数位置类型说明
plugin_idpathstring必填。已安装插件 id

成功时 data 为 { ok: true }。

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

工作区 ​

管理工作区注册表,并读写每个工作区的信任状态。工作区是已注册的项目目录,会话都落在其中;信任状态决定是否加载该工作区的项目级 MCP 配置。返回工作区的接口都使用 工作区对象。

方法与路径说明
GET /api/v1/workspaces列出已注册工作区
POST /api/v1/workspaces注册工作区(每次调用创建新条目,重试用 idempotency_key 去重)
PATCH /api/v1/workspaces/{workspace_id}重命名,或整体替换源文件夹
POST /api/v1/workspaces/{workspace_id}/primary把某个源文件夹提升为主目录
GET /api/v1/workspaces/project-config-dirs只读获取项目 local.toml 中的附加目录
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撤销信任

工作区对象 ​

注册和更新工作区时,服务端广播 全局事件 event.workspace.created / event.workspace.updated。

字段类型说明
idstring工作区 id。隐式渠道(CLI / VS Code 按目录进入)为 wd_<slug>_<hash12>,经 POST /api/v1/workspaces 显式创建的为 wm_<uuid>
rootstring主目录的绝对路径
namestring显示名,1–100 个字符;默认取主目录的基名
kindstringmanaged:显式创建,wm_ id,会话不合并项目 local.toml。implicit:按目录隐式注册,wd_ id,会话合并项目 local.toml 以兼容旧配置
additional_dirsstring[]注册表管理的额外源文件夹绝对路径,不含项目 local.toml 与临时来源
created_atstring注册时间,ISO 8601
last_opened_atstring最近一次打开或重新注册工作区的时间,ISO 8601
session_countinteger工作区内的会话数

GET /api/v1/workspaces ​

列出所有已注册工作区。

成功时 data 为 { items },每项是一个 工作区对象。

POST /api/v1/workspaces ​

注册一个新工作区并返回它。每次调用都创建新条目(wm_<uuid> id),即使同一路径已是其他工作区的主目录,也不会合并到已有条目或给出提示。

客户端重复提交(网络重试、重复点击)时应携带同一个 idempotency_key,服务端按键去重并返回首次创建的条目。

参数位置类型说明
rootbodystring必填。已存在目录的绝对路径,作为主目录
namebodystring显示名,1–100 个字符。默认主目录的基名
additional_dirsbodystring[]额外源文件夹,最多 64 项。每项按 add-dir 的规则解析(绝对路径、相对主目录或 ~ 展开),必须已存在且为目录,不能与主目录或彼此重复
idempotency_keybodystring客户端生成的幂等键,1–200 个字符。相同键的重试返回首次创建的工作区

成功时 data 为 工作区对象。

  • 40001:root 缺失或不是绝对路径,或其他请求校验失败(details 列出该字段)
  • 40006:additional_dirs 含重复项或与主目录相同。msg 为 Duplicate source folder: <实际路径>;details 为 [{ "path": "additional_dirs.N", "directory": "<解析后的绝对路径>" }],其中 path 是请求字段位置,directory 是重复的目录
  • 40409:root 或 additional_dirs 中的路径不存在或不是目录

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

更新工作区的显示名和 / 或源文件夹,主目录不可修改。name 与 additional_dirs 至少提供其一。additional_dirs 是整体替换:提交编辑后的完整列表,省略该字段则保持不变。

参数位置类型说明
workspace_idpathstring必填。工作区 id
namebodystring新的显示名,1–100 个字符
additional_dirsbodystring[]替换后的完整额外源文件夹列表,解析与校验规则同 POST /api/v1/workspaces

成功时 data 为 工作区对象。

  • 40001:两个字段都缺失,或其他请求校验失败(details 逐字段说明)
  • 40006:目录项重复或与主目录相同,msg、details.path 和 details.directory 的含义同 POST /api/v1/workspaces
  • 40409:additional_dirs 中的路径不存在或不是目录
  • 40410:工作区不存在

POST /api/v1/workspaces/{workspace_id}/primary ​

把目录集内的某个源文件夹提升为主目录。服务端做原子交换:该路径成为新的 root,原主目录进入 additional_dirs;工作区 id 与会话桶不变,全部会话保留。local.toml 跟随主目录生效,因此交换后原主目录 local.toml 中的附加目录不再并入。

对于已在 local 环境上运行、且未显式设置 environmentCwd 的既有会话,后续工具调用的默认工作目录和相对路径会跟随新的主目录。显式 environmentCwd 和远程环境绑定仍使用其配置的目录。

附加目录只扩大允许访问的范围,不会成为相对路径的候选根目录,访问这些目录需使用绝对路径或显式 cwd。切换过程中已注册的工具保持可用,工作区原有的信任决定也会在重启后保留。

参数位置类型说明
workspace_idpathstring必填。工作区 id
pathbodystring必填。要提升的目录,解析规则同 add-dir;必须在当前目录集(root ∪ additional_dirs)内

成功时 data 为 工作区对象。

  • 40001:path 不在目录集内
  • 40409:path 不存在或不是目录
  • 40410:工作区不存在

GET /api/v1/workspaces/project-config-dirs ​

只读返回指定项目 local.toml 中的 workspace.additional_dir,结果已解析为绝对路径、去重,并剔除 root 自身。接口不修改注册表,也不修改 local.toml。客户端可以用它把项目的旧配置并入新建或编辑工作区的表单,随保存生效。

服务端从 root 向上查找包含 .git 的目录作为项目根(找不到时用 root 本身),读取其中的 .kimi-code/local.toml。local.toml 缺失时返回空数组。TOML 损坏或配置的目录已不存在时请求失败,不会按空配置返回。

参数位置类型说明
rootquerystring必填。项目主目录的绝对路径

成功时 data 为 { additional_dirs: string[] }。

  • 40001:root 缺失或为空;local.toml 的结构不合法(例如 workspace.additional_dir 不是字符串数组);或其中配置的目录不存在、不是目录
  • 50001:local.toml 不是合法的 TOML,或读取失败

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

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

参数位置类型说明
workspace_idpathstring必填。工作区 id

成功时 data 为 { deleted: true }。

  • 40410:工作区不存在

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

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

参数位置类型说明
workspace_idpathstring必填。工作区 id

成功时 data 为 { trusted }。

  • 40410:工作区不存在

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

把工作区标记为受信任,并加载其项目级 MCP 配置。

参数位置类型说明
workspace_idpathstring必填。工作区 id

成功时 data 为 { trusted: true }。

  • 40410:工作区不存在

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

撤销与当前目录集关联的持久化信任记录。进程或配置覆盖没有让工作区保持受信任时,同时卸载其项目级 MCP 配置。

参数位置类型说明
workspace_idpathstring必填。工作区 id

成功时 data 为 { trusted },表示撤销后的有效信任状态。通常为 false;KIMI_CODE_TRUST_WORKSPACE 或 [workspace] require_trust = false 生效时仍为 true。

  • 40410:工作区不存在

文件上传 ​

上传文件供后续引用(例如作为提示词附件),以及下载、删除已上传的文件。

方法与路径说明
POST /api/v1/filesmultipart 上传(字段 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 上传文件。

参数位置类型说明
filebodybinary必填。multipart 的文件部分
namebodystring存储的显示名。默认上传的文件名
expires_in_secbodynumber文件过期前的秒数(非负)。默认永不过期

成功时 data 为文件元信息:

字段类型说明
idstring文件 id,下载和删除时使用
namestring显示名
media_typestring取自上传的内容类型
sizeinteger文件大小
created_atstring上传时间
expires_atstring可选。过期时间
  • 40001:multipart 请求体缺少 file 字段

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

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

参数位置类型说明
file_idpathstring必填。上传响应返回的文件 id
  • 40407(HTTP 404):没有该 id 的文件(包括已过期的文件)

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

删除已上传的文件。

参数位置类型说明
file_idpathstring必填。上传响应返回的文件 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。

参数位置类型说明
keyquerystring必填。要读取的键,1–256 个字符

成功时 data 为 { value }:已存的字符串,键不存在时为 null。

POST /api/v1/gui/store/setItem ​

写入一个值,对齐 localStorage.setItem。

参数位置类型说明
keybodystring必填。要写入的键,1–256 个字符
valuebodystring必填。要存储的值

成功时 data 为 null。

POST /api/v1/gui/store/removeItem ​

删除一个值,对齐 localStorage.removeItem。

参数位置类型说明
keybodystring必填。要删除的键,1–256 个字符

成功时 data 为 null。

POST /api/v1/gui/store/clear ​

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

成功时 data 为 null。

全局搜索与其他 ​

跨会话全文搜索、列出在线的 WebSocket 连接,以及其他接口的入口。

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

POST /api/v1/search ​

跨会话全文搜索 User 消息、Assistant 回复与会话标题,由服务端的持久搜索索引支撑。

用 container.session_id 限定在单个会话内搜索时同样走索引。因此运行中步骤正在生成的文本,要等该步骤保存、索引追上之后才能搜到;仍在追赶的视图由 index_state.stale 标记。

参数位置类型说明
querybodystring必填。搜索文本
modebodystringterms(默认)/ literal
opbodystringterms 模式下的词项组合方式:AND(默认)/ OR
containerbodyobject把搜索限定在 { session_id?, agent_id? }
rolebodystring只看 user / assistant / title 命中
start_timebodyinteger只看不早于该时间的命中(epoch 毫秒)
end_timebodyinteger只看不晚于该时间的命中(epoch 毫秒)
sortbodystringscore(默认)/ time_desc / time_asc;literal 模式忽略此参数,始终最新在前
page_sizebodyinteger每页命中数,1–50。默认 20
page_tokenbodystring上一页响应返回的令牌

terms 模式把查询分词(ASCII 词加 CJK n-gram)、去重,并以至多 32 个词项匹配倒排索引。literal 模式是零误报的精确子串搜索。

分页令牌锁定索引代际与查询条件,索引重建或查询变更都会使令牌失效。

成功时 data 字段如下:

字段类型说明
itemsarray命中列表,每项字段见下表
has_moreboolean是否还有下一页
page_tokenstring可选。下一页的令牌
incompletestring仅超出预算的页携带:candidate_cap / postings_budget / deadline
index_state.statestringbuilding / ready / readonly
index_state.indexed_sessionsinteger已索引的会话数
index_state.total_sessionsinteger会话总数
index_state.documentsinteger文档数
index_state.staleboolean可选。标记仍在追赶的落后视图
index_state.degradedstring可选。最近一次刷新失败的信息

items 每项字段:

字段类型说明
session_idstring会话 id
workspace_idstring工作区 id
session_titlestring会话标题
agent_idstringAgent id
rolestringuser / assistant / title
snippetstring命中片段
timenumber命中时间
turninteger可选。轮次
step_idstring可选。步骤 id
scorenumber相关性得分
  • 40001:请求体校验失败、查询不可用(为空或超过 32 个词项),或分页令牌非法

GET /api/v1/connections ​

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

成功时 data 为 { connections },每项字段如下:

字段类型说明
idstring连接 id
connected_atstring连接时间,ISO 8601
remote_addressstring | null远端地址,未知时为 null
user_agentstring | nullUser-Agent,未知时为 null
subscriptionsstring[]该连接订阅的会话 id

MCP 管理 ​

/api/v1/mcp/* 是服务统一的 MCP 管理面,独立于任何会话,直接管理 MCP 服务注册表本身。它覆盖用户级配置的增删改查(每条配置写入前校验)、连接测试、按 locator 寻址的检查目录、各服务的授权状态,以及完整的 OAuth 流程。

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

管理面有两种寻址方式:

  • 运行时名称:增删改查接口与 servers:test 使用普通的运行时 name。
  • locator:检查与 OAuth 接口使用 locator,因为插件条目和文件条目可能共用同一个运行时名称。文件层条目的 locator 为 { "source": "global", "name" },插件清单条目为 { "source": "plugin", "pluginId", "serverName" }。

检查结果还带有稳定的 serverId 标识:global:<name> 或 plugin:<pluginId>:<serverName>(URL 编码)。

除 auth:complete 和 auth:cancel 外,各接口都接受可选的 cwd:servers:test 和 servers:inspect 放在请求体中,其余接口(包括 auth:begin 和 auth:reset)是查询参数。不传时目录只覆盖用户级文件与插件清单;传入后,该目录的项目根层与项目本地层会并入,但仅在工作区 受信任 时并入,否则跳过项目层。对 stdio 服务执行 servers:test 时,cwd 同时是子进程的工作目录。

连接探测与 OAuth 调用会等服务配置加载完成后再执行。

GET /api/v1/mcp/servers ​

列出管理面已知的全部 MCP 服务。

参数位置类型说明
cwdquerystring并入该目录(须受信任)的项目层

成功时 data 是受管 MCP 服务数组,每项字段如下:

字段类型说明
namestring运行时名称
configobject可变条目携带完整配置,便于编辑界面预填;只读条目脱敏为排序后的键名列表(envKeys / headerKeys),不会泄露密钥值
sourcestringglobal(配置文件层,包括用户级文件和项目层)或 plugin(插件清单)。schema 中另有 caller,目前不会返回
originstring条目的定义位置:文件路径或插件 id
mutableboolean只有用户级条目可变;插件与项目层条目均为只读
pluginobject仅插件条目携带:{ id, name }
  • 40001:校验失败

GET /api/v1/mcp/servers/{name} ​

按运行时名称获取单个 MCP 服务。

参数位置类型说明
namepathstring必填。MCP 服务的运行时名称
cwdquerystring并入该目录(须受信任)的项目层

成功时 data 为单个受管 MCP 服务,字段同 GET /api/v1/mcp/servers。

  • 40001:校验失败
  • 40408:不存在该名称的 MCP 服务

POST /api/v1/mcp/servers ​

向用户级 mcp.json 添加 MCP 服务。请求体是包含 name 的完整服务配置,transport(stdio / http / sse)决定配置形状,写入前会校验。

写入与项目层的同名条目冲突时,因条目只读而被拒绝,需改为编辑定义它的文件。项目层只在传入 cwd 且该目录受信任时并入,因此只有这时才会检查这一冲突。与同名的插件条目冲突不阻止写入,新的文件条目会遮蔽插件条目。

参数位置类型说明
cwdquerystring并入该目录(须受信任)的项目层,返回的列表也包含项目层

成功时 data 为刷新后的 MCP 服务列表,字段同 GET /api/v1/mcp/servers。

  • 40001:校验失败,或目标条目为只读

PUT /api/v1/mcp/servers/{name} ​

替换一个用户级条目。请求体与 POST /api/v1/mcp/servers 的配置相同,但不含 name,由路径指定条目;与同名条目冲突时的规则也相同。

参数位置类型说明
namepathstring必填。要替换的条目的运行时名称
cwdquerystring并入该目录(须受信任)的项目层

成功时 data 为刷新后的 MCP 服务列表。

  • 40001:校验失败,或目标条目为只读
  • 40408:不存在该名称的 MCP 服务

DELETE /api/v1/mcp/servers/{name} ​

删除一个用户级条目。无请求体。

参数位置类型说明
namepathstring必填。要删除的条目的运行时名称
cwdquerystring并入该目录(须受信任)的项目层

成功时 data 为刷新后的 MCP 服务列表。

  • 40001:校验失败,或目标条目为只读
  • 40408:不存在该名称的 MCP 服务

POST /api/v1/mcp/servers:test ​

对单个 MCP 服务发起真实连接探测,不持久化任何内容。传 name 探测注册表条目(含插件与受信任的项目层),或传 server 按原样探测内联配置;两者必须且只能传一个。

参数位置类型说明
namebodystring注册表条目的运行时名称
serverbodyobject按原样探测的内联配置,须包含 name
cwdbodystring用于并入项目层;同时是 stdio 子进程的工作目录

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

  • 40001:两种目标形式都传或都不传、内联配置无效,或运行时名称被多个已启用的 MCP 服务共用
  • 40408:不存在该名称的 MCP 服务

POST /api/v1/mcp/servers:inspect ​

返回按 locator 寻址的目录(配置已脱敏),并对每个 OAuth 候选批量发起真实连接探测。探测遇到过期授权时,可能刷新或作废已存储的凭据。

参数位置类型说明
targetsbodyarray缩小目录范围的 locator 数组;不传则检查全部 MCP 服务
cwdbodystring并入该目录(须受信任)的项目层

成功时 data 是检查结果数组,每项字段如下:

字段类型说明
serverIdstring稳定标识,格式见 MCP 管理
locatorobject该条目的 locator
runtimeNamestring运行时名称
canonicalUrlstring可选。远程服务的凭据 URL
originstring条目来源,取值与 GET /api/v1/mcp/servers 的 source 相同
configobject脱敏后的配置
enabledboolean是否启用
editableboolean是否可编辑
authStatusstringnot-applicable / bearer-token / oauth-required / oauth-authorized / oauth-expired / unavailable。运行时名称被多个已启用的 MCP 服务共用时无法无歧义地探测,报告 unavailable
checkedAtnumber可选。检查时间
errorstring可选。错误说明,例如运行时名称被共用时的说明
  • 40001:校验失败
  • 40408:targets 中有 locator 未匹配到任何条目

GET /api/v1/mcp/auth-statuses ​

读取注册表目录中各 MCP 服务的 OAuth 状态。只需要授权维度时,它比 servers:inspect 更轻量。验证探测可能刷新或作废已存储的凭据。

参数位置类型说明
cwdquerystring并入该目录(须受信任)的项目层
verifyquerystringtrue:对每个 OAuth 候选发起真实连接验证。false:完全离线,只凭配置与已存储的 token 分类。缺省:保留隐式 OAuth 探测,只探测未固定且没有已存储凭据的远程服务

成功时 data 是 { name, authStatus } 数组,authStatus 的取值与 servers:inspect 相同。

POST /api/v1/mcp/auth:begin ​

为远程 MCP 服务开始一次交互式 OAuth 流程。目标必须使用远程传输(http / sse),且不含静态 bearer token;静态请求头仅在配置显式设置 auth: "oauth" 时允许。

参数位置类型说明
locatorbodyobject必填。整个请求体是目标的 locator
cwdquerystring可选。并入该目录(须受信任)的项目层

成功时 data.status 为以下两种之一:

字段类型说明
statusstringauthorization-required:需要授权。already-authorized:授权已存在,此时没有其他字段
flowIdstring仅 authorization-required:流程 id,供 auth:complete 与 auth:cancel 使用
authorizationUrlstring仅 authorization-required:在浏览器中打开该 URL 完成授权
  • 40001:校验失败;该 MCP 服务无法使用 OAuth(stdio 传输、静态 bearer token,或未设置 auth: "oauth" 的静态请求头);或运行时名称被多个已启用的 MCP 服务共用
  • 40408:locator 未匹配到任何条目
  • 40929:OAuth 流程本身失败

POST /api/v1/mcp/auth:complete ​

等待已开始流程的浏览器回调,并完成 code 交换。等待默认 15 分钟,可用 timeoutMs 覆盖;空闲流程无论如何都会在 15 分钟后过期。客户端关闭 HTTP 连接会中止等待。

参数位置类型说明
flowIdbodystring必填。auth:begin 返回的流程 id
timeoutMsbodyinteger等待时长(毫秒),1 到 2³¹−1。默认 15 分钟

成功时 data 为 null。

  • 40001:校验失败,包括 flowId 未知、timeoutMs 超出范围
  • 40929:OAuth 流程本身失败

POST /api/v1/mcp/auth:cancel ​

在未完成的情况下终止已开始的流程。未知流程会被忽略。

参数位置类型说明
flowIdbodystring必填。要终止的流程 id

成功时 data 为 null。

  • 40001:校验失败
  • 40929:OAuth 流程本身失败

POST /api/v1/mcp/auth:reset ​

清除某个 MCP 服务已存储的凭据,失效事件会送达存活的会话。

参数位置类型说明
locatorbodyobject必填。整个请求体是目标的 locator
cwdquerystring可选。并入该目录(须受信任)的项目层

成功时 data 为 null。

  • 40001:校验失败;目标使用 stdio 传输;或运行时名称被多个已启用的 MCP 服务共用
  • 40408:locator 未匹配到任何条目
  • 40929:OAuth 流程本身失败