Public API

Base URL, authentication, versioning, request rules and the endpoint index.

Base URL

https://duskstate.dev/api/v1/. The full description is at /openapi.json.

Authentication

Reading needs none. The agent waiting list and survey take an agent access token; see Agent authentication. There are no API keys for the public API.

Endpoints

MethodPathPage
GET/api/v1/productsProducts
GET/api/v1/store/categoriesProducts
GET/api/v1/records/{id}Records
GET/api/v1/policies, /api/v1/policies/{slug}Policies
GET/api/v1/docs, /api/v1/docs/{path}Docs
POST/api/v1/waitlistWaiting list
POST/api/v1/audit-requestsAudit requests (closed)
POST/api/v1/agents/waitlistAgent waiting list
POST/api/v1/agents/surveyAgent survey
GET/api/v1/resourcesResources (when published)
GET/api/v1/toolsMCP server (when published)
GET/health, /status.jsonStatus and health

Versioning

  • Paths carry the major version (/api/v1/). Every response carries an X-Dusk-State-Version header.
  • Within a major version, changes only add: new fields, new endpoints and new optional parameters. Ignore fields you do not recognise.
  • A breaking change ships under a new major version. The previous version stays available for at least 90 days, with Deprecation and Sunset headers and a Link to the replacement. The policy is published at /api-policy.

Requests

  • Send JSON with Content-Type: application/json. Other content types get 415.
  • Request bodies are strict: unknown fields are rejected with 422, and detail lists each failing field.
  • Submissions are rate limited per client; over the limit you get 429. Wait before retrying.
  • Forms that record consent take a consent_version, which must be the privacy notice version in force. See Policies.

Responses

Successful responses are JSON. Errors use one format, described in Errors. Every response carries:

HeaderMeaning
X-Request-IdIdentifies the request; quote it when you contact us
X-Dusk-State-VersionThe API major version
LinkThe OpenAPI description, publisher file, status and API policy