Cargo API docs

The Cargo API docs are the human-readable reference for the Cargo REST API. Use them to call models, tools, plays, agents, connectors, and workspace administration from any HTTP client.

Base URL

https://api.getcargo.io/v1

Every path is authenticated. There is no public, unauthenticated endpoint. The version is in the path (/v1); a breaking change ships as a new path, not as a silent mutation of this one.

Do not send calls to api.getcargo.ai. That host is a signpost. Most HTTP clients drop the Authorization header across a cross-host redirect, so a request sent there returns 401 rather than data.

Authentication

Include a bearer token on every request:

curl -X GET "https://api.getcargo.io/v1/storage/models/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get a token with cargo-ai login (see Cargo auth docs). The CLI reads CARGO_API_TOKEN from the environment or from the nearest .env.

OpenAPI specification

The complete machine-readable contract — 280 paths, 340 operations — is the Cargo OpenAPI spec, served at https://www.getcargo.ai/openapi.json.

Versioning and deprecation

URL versioning (/v1). Breaking changes ship as a new path. Deprecated operations carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers, with at least 180 days between them. The policy lives at https://docs.getcargo.ai/api-reference/versioning.

Rate limits

Every /v1 response, including 401 Unauthorized, carries IETF RateLimit-* headers. On 429 Too Many Requests, back off by Retry-After.

Errors

Error bodies are JSON, not HTML. Typical shapes:

{ "errorMessage": "Human-readable error message" }

{ "reason": "modelNotFound" }

Official clients

• REST from any language against the OpenAPI spec
• TypeScript: @cargo-ai/api
• CLI: @cargo-ai/cli (cargo-ai)

Full reference

The operation-by-operation reference, including every request and response schema, is at https://docs.getcargo.ai/api-reference. This page is the named Cargo API docs entry point on getcargo.ai.