/v1 的 API origin 和合适的后端 Token。
创建与读取
POST /v1/connections 接受严格对象:必填 kind(sandbox/model/tool/http)、非空 provider、name(1–200 字符);可选 config(对象,默认空)、credential(1–32,768 字符)或 secret_id(managed Secret UUID)。Credential 与 secret_id 互斥。Adapter 进一步解析 config,通用对象 schema 不证明任意 Provider 字段有效。引用的 managed Secret 必须存在且启用。
按具体集成指南准备 connection-create.json,含凭据文件必须私有保存。没有适用于所有 Provider 的通用配置 JSON。
GET /v1/connections 返回 200、{connections:[...]},按创建时间排列,排除删除项,无分页。GET /v1/connections/{id} 返回 200 和单个投影。路径 ID 使用 UUID 校验。不存在、已删除或其他租户连接返回 404 connection_not_found。
修改、验证、再启用
PATCH /v1/connections/{id} 接受严格的可选 name、config、credential、secret_id、enabled:boolean,不能更改 kind/provider。提供 config 是替换而非合并,省略保留原值。Credential/secret_id 仍互斥;提供直接 credential 会清除 managed Secret 关联。Null 不是通用清空方式。
出现 config/credential/secret_id 字段即重置 status=draft、禁用并清空 validation,即使值等价。每次接受 PATCH 都递增版本,包括仅改名称和空对象;没有 expected_version 检查。同时变更上述字段并启用,或启用非 ready 连接,返回 409 validation_required。关联 managed Secret 禁用/删除时启用返回 409 secret_disabled。
POST /v1/connections/{id}/validate 可能访问外部 Provider,OAuth 情况可能刷新凭据。即使验证失败也返回 200 和更新后的连接,必须检查 status(ready/invalid)和 validation.code。成功保留 enabled 而非自动启用,失败禁用。Validation 包含 checked_at 和被检查版本。远端校验期间版本变化时返回 409 connection_changed_during_validation,不能用旧检查认可新配置。
发现 Remote MCP Tools
POST /v1/connections/{id}/discover-mcp 无必需请求体,返回 200 和更新后的连接。只接受 kind=tool、provider=mcp-remote,否则 400 unsupported_connection_provider。它获取凭据并访问 MCP 服务;发现传输失败为 422 mcp_discovery_failed,获取凭据可独立失败。
409 connection_changed_during_validation,发现不会静默改写已有 grants。
断开 Tool 凭据
POST /v1/connections/{id}/disconnect 无必需请求体,返回 200、连接投影及 provider_revoked:false。非 Tool 返回 400 connection_kind_mismatch。
检查依赖与使用记录
GET /v1/connections/{id}/dependencies 返回 200、{agents,sessions,limit:100}。Agents 为保存绑定引用此 ID 的模板,包括归档项,字段 id/name/revision/archived_at。Sessions 含 id/state/agent_id,覆盖通过 Sandbox、模型、Tool、受保护 API 引用该连接的非 closed Session。两数组各最多 100 项,最新在前,无后续游标,不是完整导出。
GET /v1/connections/{id}/usage 接受 section=agents/sessions/calls(默认 sessions),offset 为 0–100000 整数,默认 0。成功 200 返回 {section,items,offset,next_offset},固定每页 25 项,观测到末页时 next_offset=null。与 dependencies 不同,usage 的 sessions 只跟踪 Tool 绑定,包括 closed,不枚举 Sandbox/模型/受保护 HTTP 使用。
删除
DELETE /v1/connections/{id} 软删除并禁用连接、设 status=deleted、递增版本后,返回 204,无响应体。任何非 closed Session 依赖导致 409 connection_in_use,此检查不受依赖列表截断影响。仅 Agent 模板引用不阻止删除,应主动更新相关模板避免后续失败。
404 connection_not_found。其他错误包括 400 invalid_request、400 ambiguous_credential、400 unsupported_connection_provider 及 managed Secret 错误。HTTP 200 时仍须检查 validation,不能把传输成功等同就绪。
来源:连接操作、使用查询、路由。本轮未使用真实凭据、验证 Provider 或修改连接。用户同意和流程状态响应见 OAuth 契约。下一步:连接工作流、HTTP 总览。