API v1

One contract for the console and CLI.

The public API is JSON over HTTPS. Customer-only endpoints use an MFA-authenticated session cookie; automation uses a scoped rasp_live_… bearer key.

Conventions

Send Idempotency-Key on zone creation and purge requests. Reusing a key with the same body returns the original result; reusing it with a different body returns 409. Zone updates use expectedVersion, and deletion uses If-Match.

curl https://api.rasp-cdn.dev/api/v1/organizations/$ORG/zones \
  -H "Authorization: Bearer $RASP_API_TOKEN"

curl -X POST https://api.rasp-cdn.dev/api/v1/organizations/$ORG/zones \
  -H "Authorization: Bearer $RASP_API_TOKEN" \
  -H "Idempotency-Key: deploy-2026-09-03-assets" \
  -H "Content-Type: application/json" \
  --data '{"name":"Assets","hostname":"assets.example.com","origin":"https://origin.example.com","defaultTtlSeconds":3600,"maximumTtlSeconds":86400}'

GET/api/v1

API discovery

POST/api/v1/auth/invitations/inspect

Inspect a pending invitation

POST/api/v1/auth/invitations/accept

Accept a single-use invitation

POST/api/v1/auth/login

Verify password and start MFA

POST/api/v1/auth/mfa/totp/enrollment

Begin TOTP enrollment

POST/api/v1/auth/mfa/totp/verify

Verify TOTP and issue a session

POST/api/v1/auth/mfa/recovery/verify

Consume a recovery code

GET/api/v1/customer/session

Read the customer session

DELETE/api/v1/customer/session

Revoke the customer session

POST/api/v1/organizations/{organizationId}/invitations

Invite an organization member

GET/api/v1/organizations/{organizationId}/api-keys

List API keys without secrets

POST/api/v1/organizations/{organizationId}/api-keys

Create a one-time API key

DELETE/api/v1/organizations/{organizationId}/api-keys/{keyId}

Revoke an API key

GET/api/v1/organizations/{organizationId}/zones

List zones

POST/api/v1/organizations/{organizationId}/zones

Create and publish a zone

PATCH/api/v1/organizations/{organizationId}/zones/{zoneId}

Update with an expected version

DELETE/api/v1/organizations/{organizationId}/zones/{zoneId}

Delete with If-Match

POST/api/v1/organizations/{organizationId}/zones/{zoneId}/purges

Queue a durable purge

GET/api/v1/organizations/{organizationId}/purges

Read purge completion

GET/api/v1/organizations/{organizationId}/configuration/latest

Read the published snapshot

GET/api/v1/organizations/{organizationId}/usage

Read rolling 30-day usage

GET/api/v1/organizations/{organizationId}/audit-events

Read audit events

GET/api/v1/organizations/{organizationId}/billing

Read beta entitlements

GET/api/v1/organizations/{organizationId}/support-access

Read active staff support access

Errors and retries

Error bodies contain a stable code and human-readable message. Retry network errors, 429, and transient 5xx responses with capped exponential backoff. Do not retry validation or authorization failures unchanged.

{
  "error": {
    "code": "zone_version_conflict",
    "message": "The zone changed since it was read."
  }
}

The machine-readable OpenAPI 3.1 contract is versioned in docs/api/openapi.yaml. Internal staff, certificate, configuration-distribution, purge-worker, and telemetry routes are deliberately excluded from the public API.