> ## Documentation Index
> Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> The Cactal API base URL, hosts, versioning, response codes, and conventions. Everything the dashboard does, your code can do.

The Cactal API is a JSON REST API. It exposes every public platform operation, including the agent-safe operations available through the [MCP server](/docs/agents/mcp), with the same permissions, rate limits, and audit trail.

## Base URL

```text theme={null}
https://api.cactal.ai/v1
```

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

| Host            | Purpose                                         | Authentication                                                                    |
| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------- |
| `api.cactal.ai` | Public API for external integrations and agents | API key only. Requests carrying a browser session cookie are rejected with `401`. |
| `app.cactal.ai` | The dashboard and its same-origin API calls     | Browser session or API key — never both in one request.                           |

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:

```bash theme={null}
curl https://api.cactal.ai/v1/websites \
  -H "Authorization: Bearer $CACTAL_API_KEY"
```

See [Authentication](/docs/api-reference/authentication) for key scopes, roles, and lifecycle, or [Create an API key](/docs/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

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| `200`  | Success. The response body is the operation result.                  |
| `400`  | Validation failed. The body names the first invalid field.           |
| `401`  | Missing, invalid, expired, or revoked API key.                       |
| `403`  | The key is valid but lacks the required capability.                  |
| `404`  | The resource does not exist — or is outside your key's access scope. |
| `409`  | The request conflicts with current state.                            |
| `429`  | Rate limit exceeded. Retry after the `Retry-After` header value.     |
| `500`  | Internal error on Cactal's side. Safe to retry with backoff.         |

Every non-2xx response has the same body shape — see [Errors](/docs/api-reference/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](/docs/api-reference/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.

<AccordionGroup>
  <Accordion title="How do I find my organization id?">
    `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.
  </Accordion>

  <Accordion title="Is there an SDK?">
    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](/docs/agents/mcp), which exposes every endpoint on this reference as a typed tool.
  </Accordion>

  <Accordion title="Does the API support webhooks?">
    Not yet. Poll list endpoints or deployment status where you need to observe changes.
  </Accordion>
</AccordionGroup>