Appearance
Conventions
Base URLs
| Environment | Base URL |
|---|---|
| Your deployment | https://api.example.com (placeholder; use your API host) |
| Local development | http://localhost:8787 (default PORT) |
| Behind dashboard/portal host | https://<app-host>/api |
The dashboard and portal serve a static SPA and proxy /api/ to the API, stripping the prefix: GET https://<app-host>/api/v1/me reaches GET /v1/me. The Vite dev servers do the same to http://localhost:8787. Direct API hosts have no /api prefix.
All paths in this reference are relative to the API root and start with /v1.
Requests and responses
- Bodies are JSON; send
Content-Type: application/json. - Responses are JSON unless noted. Error shapes are in Errors, pagination and limits.
Request IDs
Responses from the developer API routes carry an x-request-id header. If you send your own X-Request-Id, it is reused; otherwise the server generates a UUID. Quote it when reporting problems. The operational root /health probe runs before this middleware.
CORS
Browser calls to /v1/* allow the dashboard's WEB_ORIGIN (default http://localhost:5173) with credentials. Operators can additionally configure DOCS_ORIGIN (for example http://localhost:3100) for the API playground. The docs origin uses explicit Bearer headers and does not receive credentialed CORS. Other origins receive no matching allow-origin header; use a server integration or the same-origin /api proxy.
Idempotency
POST /v1/me/sessions requires an Idempotency-Key header (8-128 characters). Use a fresh key per user action and reuse it only when retrying the same action. See Session lifecycle. Other endpoints do not take this header.
Values and versioning
Optional means a field can be absent; nullable means its value can be null. Some billing and database numeric fields accept string or number representations; normalize them before arithmetic and verify units. Most date-time strings are ISO timestamps, while some Stripe fields are Unix seconds. Read the specific field schema.
The major version is in the path (/v1). Clients should tolerate unknown response fields. See API changes and compatibility for the current reference changes and maintenance policy.