URL base
| ambiente | URL |
|---|---|
| produção | https://api.commandagi.com |
O prefixo /v1 é opcional: /v1/threads e /threads são a mesma rota.
Autenticação
Envie uma chave de API como token bearer:
curl https://api.commandagi.com/v1/me \
-H "Authorization: Bearer cagi_YOUR_KEY"- As chaves têm a forma
cagi_seguido de 64 caracteres hexadecimais, e são guardadas apenas como hashes. - Crie e revogue chaves na bancada de trabalho, em chaves de API no menu da conta, ou com
GET/POST /me/api-keyseDELETE /me/api-keys/:keyId. Agentes recebem as próprias chaves em/agents/:id/keys. - Para agir como uma das suas organizações, adicione
x-cagi-account: <account id>. - Os endpoints WebDAV e Git aceitam a mesma chave como senha de autenticação Basic.
A chave de um agente funciona dentro da conta do dono, mas nunca pode mudar autoridade: rotas que criam concessões, colocam máquinas ou mudam donos, configurações ou chaves de assinatura respondem 403 human_principal_required a ela.
Salvar arquivos sem perder trabalho
Uma escrita nomeia a versão que substitui: envie If-Match: "<sha256>" com o hash que você leu, ou If-None-Match: * para criar um arquivo que ainda não pode existir. Se o arquivo mudou nesse meio-tempo, a API responde 412 e nada é sobrescrito.
Endpoints
| grupo | endpoints |
|---|---|
| contas | GET POST /accounts · GET /accounts/:id · GET PUT PATCH /accounts/:id/settings · GET /accounts/me/chain |
| concessões permanentes | GET POST /accounts/:id/standing-grants · DELETE /standing-grants/:id · GET /standing-grants/held |
| chaves de assinatura | GET /accounts/:id/signing-key · POST /accounts/:id/signing-key/rotate |
| hosts | GET /accounts/:id/hosts · POST /hosts/:hostId/call |
| arquivos | GET /drive · POST /drive/upload · GET PUT /drive/:id/content · PATCH DELETE /drive/:id · POST /drive/folders |
| agentes | GET POST /agents · GET PATCH DELETE /agents/:id · GET PUT /default-agents |
| conversas | GET /me/threads · POST /threads · GET PATCH DELETE /threads/:id · GET /threads/:id/events · POST /threads/:id/inject |
| negociação | GET /trading/venues · POST /trading/order · POST /trading/account · POST /trading/cancel |
| modelos | GET /models · GET /models/catalog · GET /models/families |
| MCP | POST /mcp — veja SDK e MCP |
| saúde | GET /health |
Modelos
GET /models lista os modelos que você pode usar, como { "models": [ … ] }; filtre com ?useCase=. O modelo próprio é commandagi/CommandAGI-000. Modelos de outros provedores aparecem com os próprios ids, e você pode trazer a sua chave de provedor por conta ou organização.
Não há endpoint de chat completions compatível com OpenAI; use conversas.
Erros
O status HTTP informa o que deu errado: 401 sem uma chave válida, 403 quando o principal não pode fazer isto, 404 quando ele não existe ou não é seu para ver, 412 quando um arquivo mudou sob você.