REST API Overview

Base URL and versioning

• Prefix: All routes are under /api.
• Versioning: URI-based. Unversioned routes at /api/*; versioned at /api/v1/*, /api/v2/*, etc.
• OpenAPI spec: Available at GET /api/docs-json (Swagger UI at /api/docs).

Authentication

Use Bearer JWT in the Authorization header:

Authorization: Bearer <your-token>

Tokens are issued via the account app (Better Auth). Optional headers: X-Request-ID, X-Org-Id, X-Org-Role.

Response format

All success responses are wrapped as { success: true, data, meta? }. Errors are { success: false, error: { code, message, details?, timestamp, path, requestId? } }. Paginated lists put items in data and pagination in meta. The full specification is in the repo: docs/API_RESPONSE_STANDARDS.md.

Interactive reference

For a full, interactive API reference with try-it-out, use the API Reference page (powered by Scalar).