Skip to main content
The Cactal API is a JSON REST API. It exposes every public platform operation, including the agent-safe operations available through the MCP server, with the same permissions, rate limits, and audit trail.

​
Base URL

All endpoint paths in this reference are relative to the base URL. Requests and responses use application/json, except the CSV export endpoints, which return text/csv.

​
Hosts

Use api.cactal.ai for everything you build. The examples throughout these docs assume it.

​
Authentication

Send an API key as a bearer token on every request:
See Authentication for key scopes, roles, and lifecycle, or Create an API key to get one.

​
Versioning

The path prefix /v1 is the API’s compatibility boundary. Within /v1, Cactal makes additive changes only: new endpoints, new optional parameters, and new response fields. Breaking changes would ship under a new prefix. Build clients that tolerate unknown response fields.

​
Response codes

Every non-2xx response has the same body shape — see Errors.

​
Conventions

  • Ids are opaque 21-character strings. Never parse or construct them.
  • Timestamps are ISO 8601 strings in UTC, for example 2026-07-08T18:30:00.000Z.
  • List endpoints use cursor pagination with an { "items": [...], "nextCursor": "..." } envelope — see Pagination. A few fixed-cardinality reads, capped by a product rule rather than by data volume, return plain objects.
  • Write endpoints take their parameters in the JSON body; GET endpoints take them as query parameters; path parameters are always in the URL.

​
Machine-readable metadata

Each endpoint in this reference carries agent-oriented extensions in the OpenAPI spec: x-cactal-required-capability (the capability your key needs), x-cactal-read-only, x-cactal-destructive, and x-cactal-idempotent. Use the contextual menu on any page to copy it as Markdown or download the full spec.
GET /v1/organizations returns the organizations your key can access. Organization-scoped keys see their own organization; website-scoped keys see the organization that owns their websites.
Not yet. The API is plain JSON over HTTPS and works with any HTTP client. Agents can skip HTTP entirely and use the MCP server, which exposes every endpoint on this reference as a typed tool.
Not yet. Poll list endpoints or deployment status where you need to observe changes.