Base URL
| environment | URL |
|---|---|
| production | https://api.commandagi.com |
A /v1 prefix is optional: /v1/threads and /threads are the same route.
Authentication
Send an API key as a bearer token:
curl https://api.commandagi.com/v1/me \
-H "Authorization: Bearer cagi_YOUR_KEY"- Keys look like
cagi_followed by 64 hexadecimal characters, and are stored only as hashes. - Create and revoke keys in the workbench from the account menu's API keys, or with
GET/POST /me/api-keysandDELETE /me/api-keys/:keyId. Agents get their own keys at/agents/:id/keys. - To act as one of your organizations, add
x-cagi-account: <account id>. - WebDAV and Git endpoints accept the same key as a Basic-auth password.
An agent's key works inside its owner's account with its own identity and scopes. Routes that create grants, place machines, or change owners, settings or signing keys apply the same checks to a person's key and an agent's key, and record which one acted. A program's service token gets 403 named_principal_required.
Saving files without losing work
A write names the version it replaces: send If-Match: "<sha256>" with the hash you read, or If-None-Match: * to create a file that must not exist yet. If the file changed in the meantime, the API answers 412 and nothing is overwritten.
Endpoints
| group | endpoints |
|---|---|
| accounts | GET POST /accounts · GET /accounts/:id · GET PUT PATCH /accounts/:id/settings · GET /accounts/me/chain |
| standing grants | GET POST /accounts/:id/standing-grants · DELETE /standing-grants/:id · GET /standing-grants/held |
| signing keys | GET /accounts/:id/signing-key · POST /accounts/:id/signing-key/rotate |
| hosts | GET /accounts/:id/hosts · POST /hosts/:hostId/call |
| files | GET /drive · POST /drive/upload · GET PUT /drive/:id/content · PATCH DELETE /drive/:id · POST /drive/folders |
| agents | GET POST /agents · GET PATCH DELETE /agents/:id · GET PUT /default-agents |
| threads | GET /me/threads · POST /threads · GET PATCH DELETE /threads/:id · GET /threads/:id/events · POST /threads/:id/inject |
| trading | GET /trading/venues · POST /trading/order · POST /trading/account · POST /trading/cancel |
| models | GET /models · GET /models/catalog · GET /models/families |
| MCP | POST /mcp — see SDK and MCP |
| health | GET /health |
Models
GET /models lists the models you can use, as { "models": [ … ] }; filter with ?useCase=. The first-party model is commandagi/CommandAGI-000. Models from other providers are listed with their own ids, and you can bring your own provider key per account or organization.
There is no OpenAI-compatible chat-completions endpoint; use threads.
Errors
The HTTP status says what went wrong: 401 without a valid key, 403 when the principal may not do this, 404 when it does not exist or is not yours to see, 412 when a file changed under you.