API reference

The Veridi REST API is documented as OpenAPI 3.0 and served alongside the API itself.

Interactive reference

The full reference — including request and response schemas, error codes, and a “Try it out” panel that accepts your API key — is served from the API process:

Open Swagger UI →

Raw OpenAPI spec

The machine-readable spec is exposed at http://localhost:3001/api/v1/docs-json. Feed it to your favourite code generator (oapi-codegen, openapi-typescript, openapi-generator) to scaffold a client in another language — the canonical TypeScript SDK lives in @veridi/sdk for callers who want auth, retries, and webhook verification handled.

The Swagger UI is unauthenticated; the spec lists the auth schemes so the “Try it out” panel asks for a key before issuing requests. Do not expose the docs URL on a publicly routable host without an IP/auth gate in production.

Authentication

Two schemes are accepted on the same routes:

X-Api-Key — B2B server-to-server credentials. Created and rotated under API Keys in the dashboard.
Authorization: Bearer <jwt> — Casdoor OIDC access token for dashboard users and reviewers.

Response envelope

Every response follows the same wrapper so you can write a single error handler:

{ "success": true, "data": { ... }, "meta": { "requestId": "...", "timestamp": "..." }, "error": null }

On errors, success flips to false, data becomes null, and error.code carries one of the canonical ERR_* codes.