基础 URL
| 环境 | URL |
|---|---|
| 生产环境 | https://api.commandagi.com |
/v1 前缀可选：/v1/threads 和 /threads 是同一个路由。
认证
以 bearer 令牌的形式发送 API 密钥：
curl https://api.commandagi.com/v1/me \
-H "Authorization: Bearer cagi_YOUR_KEY"- 密钥的形式为
cagi_加 64 个十六进制字符，只以哈希形式存储。 - 在工作台账户菜单的 API 密钥中创建和吊销密钥，或使用
GET/POST /me/api-keys和DELETE /me/api-keys/:keyId。智能体在/agents/:id/keys获取它们自己的密钥。 - 要以你的某个组织的身份操作，请添加
x-cagi-account: <account id>。 - WebDAV 和 Git 端点接受同一个密钥作为 Basic 认证的密码。
智能体的密钥可以在其所有者的账户内使用，但永远不能改变权限：对于创建授权、放置机器，或更改所有者、设置或签名密钥的路由，它都会得到 403 human_principal_required 的回应。
保存文件而不丢失工作
写入时须指明它要替换的版本：发送 If-Match: "<sha256>" 并附上你读取时的哈希，或发送 If-None-Match: * 来创建一个此前必须不存在的文件。如果文件在此期间已被修改，API 返回 412，不会覆盖任何内容。
端点
| 分组 | 端点 |
|---|---|
| 账户 | GET POST /accounts · GET /accounts/:id · GET PUT PATCH /accounts/:id/settings · GET /accounts/me/chain |
| 长期授权 | GET POST /accounts/:id/standing-grants · DELETE /standing-grants/:id · GET /standing-grants/held |
| 签名密钥 | GET /accounts/:id/signing-key · POST /accounts/:id/signing-key/rotate |
| 主机 | GET /accounts/:id/hosts · POST /hosts/:hostId/call |
| 文件 | GET /drive · POST /drive/upload · GET PUT /drive/:id/content · PATCH DELETE /drive/:id · POST /drive/folders |
| 智能体 | GET POST /agents · GET PATCH DELETE /agents/:id · GET PUT /default-agents |
| 线程 | GET /me/threads · POST /threads · GET PATCH DELETE /threads/:id · GET /threads/:id/events · POST /threads/:id/inject |
| 交易 | GET /trading/venues · POST /trading/order · POST /trading/account · POST /trading/cancel |
| 模型 | GET /models · GET /models/catalog · GET /models/families |
| MCP | POST /mcp——参见 SDK 与 MCP |
| 健康检查 | GET /health |
模型
GET /models 以 { "models": [ … ] } 的形式列出你可以使用的模型；可用 ?useCase= 筛选。自研模型是 commandagi/CommandAGI-000。其他服务商的模型以它们自己的 id 列出，你也可以按账户或组织使用自己的服务商密钥。
没有兼容 OpenAI 的 chat-completions 端点；请使用线程。
错误
HTTP 状态码说明出了什么问题：没有有效密钥时返回 401，主体无权执行此操作时返回 403，资源不存在或你无权查看时返回 404，文件在你操作期间被修改时返回 412。