API reference

Every endpoint on the Public and Frontend planes, plus the error shape every non-2xx response uses.

Base URL for the Public API: https://api.domainproof.dev. Base URL for the Frontend API: https://frontend.api.domainproof.dev. Every non-2xx response from either plane follows the same shape — see Errors below. This document is hand-maintained alongside the api's own OpenAPI 3.1 schema (GET /v1/openapi.json), which covers the same two planes machine-readably; the summary tables below link out to a full parameters + response breakdown for each endpoint.

Public API (/v1/*)

Authenticated with a project API key (Authorization: Bearer dp_test_... / dp_live_...) — see Authenticate with an API key. Rate limited per key: 100 requests per rolling minute, returning 429 rate_limited with a Retry-After header once exceeded.

See Claim and verify a domain for the full walkthrough, and How verification works for what each status and check outcome means.

Domain — the object every endpoint below returns, either alone ({ domain: Domain }) or as a page ({ domains: Domain[], nextCursor }):

Domain.records[] — one entry per record to add (currently always exactly one, the ownership TXT record):

Check — one verification attempt, returned as check alongside domain by POST /v1/domains/:id/verify:

Event — one entry in a domain's timeline, returned by GET /v1/domains/:id/events:

POST /v1/domains

Claims a domain for the authenticated key's project and mode, issuing a fresh verification challenge.

Returns 201 with { domain: Domain }.

GET /v1/domains

Cursor-paginated list of domains claimed by the key's project and mode. Filterable by external_id and/or domain.

Returns 200 with { domains: Domain[], nextCursor: string \| null }.

GET /v1/domains/:id

Gets a claimed domain and its current verification record instructions.

Returns 200 with { domain: Domain }.

DELETE /v1/domains/:id

Releases a domain claim.

Returns 200 with { domain: Domain } — the now-released domain.

POST /v1/domains/:id/verify

Runs the DNS check for a claim and returns the updated domain plus the check's outcome. Safe to poll — re-runs the check every time it's called.

Returns 200 with { domain: Domain, check: Check }.

POST /v1/domains/:id/regenerate

Issues a fresh challenge for a pending or failed domain, restarting verification.

Returns 200 with { domain: Domain } — carrying the fresh challenge.

GET /v1/domains/:id/events

Cursor-paginated timeline of events published for a domain (claimed, checks, transitions), oldest first.

Returns 200 with { events: Event[], nextCursor: string \| null }.

POST /v1/component-sessions

Mints a short-lived, single-use session token (expires in an hour if never spent) for a drop-in component to claim one domain on the caller's behalf, without handing the component the api key itself. The component spends it once against POST /frontend/component-sessions/:sessionToken/claim below.

Returns 201 with { sessionToken: string, expiresAt: string }.

Frontend API (/frontend/*)

No session, no API key — each domain claim carries its own unguessable frontendToken (embedded in verificationUrl) that authorizes exactly these routes for that one claim. See The hosted verification page.

Verification — the object every endpoint below returns, the hosted page's own view of a claim (no account id, project id, or key material):

ClaimResult — every Verification field above, plus:

FrontendEvent — one entry in a domain's timeline, the Frontend API's stripped-down view of Event above:

GET /frontend/verifications/:token

Reads a claim's status, record instructions, detected DNS provider, and last check outcome by its frontendToken.

Returns 200 with a Verification.

POST /frontend/verifications/:token/check

Runs the DNS check for a claim (rate limited: 1 per 15 seconds, 20 per hour, per token) and returns the same shape as the GET above.

Returns 200 with a Verification, after the check runs.

GET /frontend/verifications/:token/cloudflare/authorize

Redirects to Cloudflare's OAuth consent screen with a PKCE code_challenge and a signed state binding the request to this one claim — see Cloudflare one-click DNS setup.

Returns 302, redirecting to Cloudflare's consent screen — no JSON body on success.

GET /frontend/verifications/:token/events

Cursor-paginated timeline of events published for a domain, with no account/project ids in the payload.

Returns 200 with { events: FrontendEvent[], nextCursor: string \| null }.

POST /frontend/component-sessions/:sessionToken/claim

Claims a domain through the exact same path POST /v1/domains uses (same validation, same conflict/sandbox rules), with the project/mode and external_id carried over from the session. Rate limited: 10 attempts per hour, per session token.

Returns 201 with a ClaimResult.

GET /frontend/cloudflare/callback

Verifies state, exchanges the code, finds the matching zone, creates the TXT record, and triggers the standard verify path, then redirects to the hosted verification page. Not nested under /verifications/:token — the signed state round-tripped through Cloudflare's own redirect carries the claim binding instead, since a registered redirect_uri has to be a fixed, exact-match URL.

Returns 302, redirecting to the hosted verification page with ?cloudflare=<outcome> (success, denied, no_matching_zone, record_create_failed, exchange_failed, or not_found) — even on failure, as long as state itself is trustworthy.

Dashboard API (/dashboard/*)

Authenticated by your login session — this is what the DomainProof dashboard itself calls, covering project management, API key management, and webhook endpoint management. It's not meant to be called directly by an integration; everything an integration needs is on the Public and Frontend planes above, and it isn't part of the generated OpenAPI document either — see the README's endpoints table for its full route list.

Pagination

Every list endpoint is cursor-paginated the same way: ?limit= (default 20, max 100) and ?cursor=, the opaque nextCursor from the previous page. nextCursor is null once there's nothing left to fetch.

Errors

Every non-2xx response follows the same shape:

{ "error": { "code": "not_found", "message": "Domain not found" } }

Named codes you'll actually see (each endpoint above lists which of these it can return):

Any request can also fail with 500 internal_error on an unhandled server error — not tied to any one endpoint, so it's omitted from each endpoint's own table above.