# API reference

> Manage zones, DNS records, edge settings, rules, analytics, AI agents and egress through the OpenWAF REST API.

The OpenWAF API is a JSON REST API over HTTPS. It manages everything the dashboard does: zones and DNS records, edge settings and rules, certificates and cache, analytics, AI agents, egress, members and API tokens. The [SDKs](https://developers.openwaf.dev/sdk/), the [CLI](https://developers.openwaf.dev/cli/) and the [MCP server](https://developers.openwaf.dev/mcp/) use the same API.

> **Note**
>
> This reference is generated from the OpenAPI specification of the API (120 operations). The TypeScript and Python SDKs are generated from the same specification, so their method names match the operation ids used here.


## Base URL

```text
https://dash.openwaf.dev/v1
```

Organization resources live under `/v1/orgs/{org}` and zone resources under `/v1/orgs/{org}/zones/{zone}`. `{org}` is the id of your organization and `{zone}` the id of a zone, both UUIDs. `GET /v1/orgs` returns the organization of the token, and [List zones](https://developers.openwaf.dev/api/zones/#list-zones) returns the zone ids.

## Authentication

Every request carries an API token in the `Authorization` header:

```http
GET /v1/orgs HTTP/1.1
Host: dash.openwaf.dev
Authorization: Bearer owf_…
```

Create tokens in the dashboard (**API tokens**) or with [Create token](https://developers.openwaf.dev/api/tokens/#create-token). A token acts with a [role](https://developers.openwaf.dev/api/authentication/#roles) and can be limited to one zone or one client. A request for an organization other than the token's answers `404`, exactly like a resource that does not exist. See [Authentication](https://developers.openwaf.dev/api/authentication/).

## Requests and responses

- Request bodies are JSON (`Content-Type: application/json`) unless an operation says otherwise, up to 1 MiB. Unknown fields are rejected with `400 bad_request`.
- Times are RFC 3339 in UTC and ids are UUIDs.
- Lists answer `{"items": […]}`. Long lists page with `limit` and a cursor (`cursor`, `before`) described in each operation.
- `204 No Content` answers have no body.

## Configuration changes

The configuration of a zone (records, edge settings, rules, its client) is versioned: every change creates a new version with its author and reason, visible in [Configuration versions](https://developers.openwaf.dev/api/versions/) and in the [audit log](https://developers.openwaf.dev/api/audit/). Writes that change configuration accept three controls:

| Control | Where | Effect |
|---|---|---|
| `X-Change-Reason` | Header | Reason of the change, 1-500 characters, recorded in the history and the audit log. Required by most writes: without it they answer `422 reason_required`. |
| `dry_run=1` | Query | Simulates the change: answers `200` with the plan ([Applied](https://developers.openwaf.dev/api/schemas/#applied)), the diff and the version it would create. Nothing is saved. |
| `If-Match` | Header | Expected current version, e.g. `"12"`. If the zone has changed since, the write answers `412 version_conflict` with `current_version`. |

Successful writes answer the new version in the `X-Config-Version` header and in `ETag` (quoted, ready for `If-Match`). The safe way to change a zone, the same two steps the MCP server enforces:

1. Send the write with `dry_run=1` and check the plan; read the current version from `from_version` (or the zone's `ETag`).
2. Send the same write without `dry_run`, with `If-Match: "<version>"` and an `X-Change-Reason`. If someone changed the zone in between you get `412 version_conflict`: simulate again.


## Errors

Errors answer an HTTP status and a JSON body with a stable `code`:

```json
{"error": {"code": "invalid", "message": "ttl must be between 60 and 86400", "field": "ttl"}}
```

See [Errors](https://developers.openwaf.dev/api/errors/) for every code.

## Rate limits

Some operations have their own limits and answer `429` with a `Retry-After` header (seconds) when they are exceeded:

| Operation | Limit |
|---|---|
| [Purge cache](https://developers.openwaf.dev/api/cache/#purge-cache) | Per organization: 10 purges per minute with bursts of 30 (everything, hosts, prefixes, tags) and 500 URLs per minute. |
| [Scan agent readiness](https://developers.openwaf.dev/api/agent-readiness/#scan-agent-readiness) | Once per name per minute. |
| [Security events stream](https://developers.openwaf.dev/api/security-events/#stream-events) and [egress events stream](https://developers.openwaf.dev/api/egress/#stream-egress-events) | 10 open streams per organization. |

## Versioning

Every endpoint is under `/v1`. Responses may gain new fields and enums new values over time: clients should ignore fields they do not know. Changes to the API are announced in the [changelog](https://developers.openwaf.dev/changelog/).

## SDKs, CLI and MCP

- [SDKs](https://developers.openwaf.dev/sdk/): TypeScript and Python clients generated from this API, one file each.
- [CLI](https://developers.openwaf.dev/cli/): `openwaf-cloud ctl`, the API from the terminal and from scripts.
- [MCP server](https://developers.openwaf.dev/mcp/): the API as tools for AI assistants, at `https://mcp.openwaf.dev/mcp`.


The SDK files are also served by the API without authentication: `https://dash.openwaf.dev/v1/sdk/openwaf.ts` and `https://dash.openwaf.dev/v1/sdk/openwaf.py`.

## Reference

- [Organizations](https://developers.openwaf.dev/api/organizations/): Read and rename your organization, the account that owns zones, members and tokens.
- [Members and invitations](https://developers.openwaf.dev/api/members/): List, add and remove the people of your organization, change their roles and manage invitations.
- [API tokens](https://developers.openwaf.dev/api/tokens/): Create, list and revoke the owf_ API tokens that authenticate requests to the API, the CLI and the MCP server.
- [Clients](https://developers.openwaf.dev/api/clients/): Group zones by the end customers of an agency and limit members and tokens to one client's zones.
- [White label](https://developers.openwaf.dev/api/white-label/): Brand the dashboard with your name, colour and logo, serve it on your own domain and use your own name servers.
- [Audit log](https://developers.openwaf.dev/api/audit/): Read the audit log of your organization, every change made through the API, the dashboard, the CLI or MCP.
- [Zones](https://developers.openwaf.dev/api/zones/): Add, list, check and delete zones (domains), in delegated or external DNS mode, and merge a zone into its parent.
- [Configuration versions](https://developers.openwaf.dev/api/versions/): Browse the version history of a zone, compare two versions, revert to an earlier one and follow its propagation to the edge.
- [DNS records](https://developers.openwaf.dev/api/dns-records/): List, create, update and delete the DNS records of a zone, in bulk or as one batch, and import existing records.
- [Email DNS](https://developers.openwaf.dev/api/email/): Plan the MX, SPF, DKIM and DMARC records for your email providers and check the mail records of a zone.
- [Edge settings](https://developers.openwaf.dev/api/edge-settings/): Read and change the edge settings of a zone (WAF, origin, TLS, cache, AI agents…) and the effective configuration of a name.
- [Rules](https://developers.openwaf.dev/api/rules/): Add, list and delete the edge rules of a zone, IP and country rules, WAF exceptions and rate limits.
- [Cache](https://developers.openwaf.dev/api/cache/): Purge what the edge cached for a zone, everything or by URL, prefix, host or cache tag, and follow recent purges.
- [Edge certificates](https://developers.openwaf.dev/api/certificates/): List the TLS certificates of a zone and the certificate status of each proxied site.
- [Origin TLS and Origin CA](https://developers.openwaf.dev/api/origin-tls/): Issue and revoke origin certificates of the OpenWAF Origin CA, check origin TLS and download the CA bundles.
- [Security events](https://developers.openwaf.dev/api/security-events/): Query the security events of a zone, with filters, summaries, histograms and a live Server-Sent Events stream.
- [Usage](https://developers.openwaf.dev/api/usage/): Daily traffic counters of a zone at the edge, requests, blocked requests, bytes and DNS queries.
- [Real user monitoring](https://developers.openwaf.dev/api/rum/): Core Web Vitals measured in your visitors' browsers, LCP, INP, CLS, FCP and TTFB, by page, country, device and more.
- [AI agents](https://developers.openwaf.dev/api/ai-agents/): How AI crawlers and agents use a zone, by category, bot and operator, plus traps, signals, MCP Shield and the bot catalog.
- [Agent readiness](https://developers.openwaf.dev/api/agent-readiness/): Scan how ready a name of the zone is for AI agents, robots.txt rules, sitemap, llms.txt, markdown and structured data.
- [Egress](https://developers.openwaf.dev/api/egress/): Manage OpenWAF Egress, the gateway between your AI agents and their providers, with targets, credentials, agents and events.


- [Schemas](https://developers.openwaf.dev/api/schemas/): every object returned or accepted by the API.

## Dashboard session

Sign-in (`/v1/auth/…`), invitation acceptance and account deletion serve the dashboard with a session cookie and are not part of the token API. With a session cookie, the dashboard also calls the routes of this reference; writes then require the `X-CSRF-Token` header. Integrations always use an API token.