ESopenwaf.devDashboard

API reference

View as Markdown

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

On this page

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, the CLI and the MCP server use the same API.

Base URL

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 returns the zone ids.

Authentication

Every request carries an API token in the Authorization header:

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

Create tokens in the dashboard (API tokens) or with Create token. A token acts with a role 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.

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 and in the audit log. Writes that change configuration accept three controls:

ControlWhereEffect
X-Change-ReasonHeaderReason 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=1QuerySimulates the change: answers 200 with the plan (Applied), the diff and the version it would create. Nothing is saved.
If-MatchHeaderExpected 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:

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

See 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:

OperationLimit
Purge cachePer organization: 10 purges per minute with bursts of 30 (everything, hosts, prefixes, tags) and 500 URLs per minute.
Scan agent readinessOnce per name per minute.
Security events stream and egress events stream10 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.

SDKs, CLI and MCP

SDKsTypeScript and Python clients generated from this API, one file each.CLIopenwaf-cloud ctl, the API from the terminal and from scripts.MCP serverthe 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

OrganizationsRead and rename your organization, the account that owns zones, members and tokens.Members and invitationsList, add and remove the people of your organization, change their roles and manage invitations.API tokensCreate, list and revoke the owf_ API tokens that authenticate requests to the API, the CLI and the MCP server.ClientsGroup zones by the end customers of an agency and limit members and tokens to one client's zones.White labelBrand the dashboard with your name, colour and logo, serve it on your own domain and use your own name servers.Audit logRead the audit log of your organization, every change made through the API, the dashboard, the CLI or MCP.ZonesAdd, list, check and delete zones (domains), in delegated or external DNS mode, and merge a zone into its parent.Configuration versionsBrowse the version history of a zone, compare two versions, revert to an earlier one and follow its propagation to the edge.DNS recordsList, create, update and delete the DNS records of a zone, in bulk or as one batch, and import existing records.Email DNSPlan the MX, SPF, DKIM and DMARC records for your email providers and check the mail records of a zone.Edge settingsRead and change the edge settings of a zone (WAF, origin, TLS, cache, AI agents…) and the effective configuration of a name.RulesAdd, list and delete the edge rules of a zone, IP and country rules, WAF exceptions and rate limits.CachePurge what the edge cached for a zone, everything or by URL, prefix, host or cache tag, and follow recent purges.Edge certificatesList the TLS certificates of a zone and the certificate status of each proxied site.Origin TLS and Origin CAIssue and revoke origin certificates of the OpenWAF Origin CA, check origin TLS and download the CA bundles.Security eventsQuery the security events of a zone, with filters, summaries, histograms and a live Server-Sent Events stream.UsageDaily traffic counters of a zone at the edge, requests, blocked requests, bytes and DNS queries.Real user monitoringCore Web Vitals measured in your visitors' browsers, LCP, INP, CLS, FCP and TTFB, by page, country, device and more.AI agentsHow AI crawlers and agents use a zone, by category, bot and operator, plus traps, signals, MCP Shield and the bot catalog.Agent readinessScan how ready a name of the zone is for AI agents, robots.txt rules, sitemap, llms.txt, markdown and structured data.EgressManage OpenWAF Egress, the gateway between your AI agents and their providers, with targets, credentials, agents and events.
  • 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.

Last updated:

↑↓ to navigate↵ to openesc to close