API Reference

The API reference documentation is auto-generated from the OpenAPI specification at apps/api/openapi.json. This specification is the single source of truth for all API endpoints, request/response schemas, and authentication requirements.

Regenerating the docs

When API routes change, regenerate the OpenAPI spec and API reference docs:

# Regenerate OpenAPI spec from API routes
pnpm openapi:generate

# Regenerate API reference MDX files from the spec
pnpm docs:api:generate

The openapi:generate command introspects the Effect HttpApi route definitions in apps/api and produces an updated apps/api/openapi.json. The docs:api:generate command then reads this spec and generates MDX documentation files.

Runtime docs endpoints

When the API server is running (default http://localhost:4000), it also exposes:

Swagger UI at /docs
Raw OpenAPI JSON at /openapi.json

The runtime /openapi.json powers /docs and reflects the running server. The generated apps/api/openapi.json is the checked-in artifact used by pnpm docs:api:generate and other repo tooling.

Endpoint groups

The API is organized into tag pages generated directly from OpenAPI:

auth: password auth, Google sign-in, refresh, sign-out, and password reset endpoints
organizations: organization CRUD plus invitation lifecycle endpoints
teams: team management endpoints
billing: subscription/billing settings, checkout, portal, usage, and Stripe webhook endpoints
permissions: permission lookup endpoints
health: service health endpoint

Authentication

Authentication requirements are shown per endpoint in generated pages. Protected endpoints include:

GET /v1/auth/me
POST /v1/auth/sign-out
POST /v1/auth/sign-out-all
GET /v1/organizations
GET /v1/teams
PATCH /v1/organizations/{organizationId}/billing

These endpoints require a Bearer token in Authorization: Bearer <jwt-token>.

Health check

GET /health

Returns { "status": "healthy" } with a 200 status code. This endpoint is used by Docker health checks and deployment smoke tests.

Paginated responses

List endpoints support cursor-based pagination with limit and cursor query parameters. Responses include a nextCursor field when more results are available:

{
  "data": [...],
  "nextCursor": "abc123"
}

OpenAPI spec location

The generated OpenAPI spec in the repository lives at:

apps/api/openapi.json

This file is generated, not hand-written. Do not edit it directly --- changes will be overwritten by pnpm openapi:generate. For runtime inspection, use /openapi.json on the API server.