API Reference

The JSON API is served under /api. The web app uses the same endpoints documented here.

Mac clients use separate agent protocols.

Authentication

The API accepts either the woodstar_session cookie created during sign-in or an account API key:

Authorization: Bearer <api-key>

An API key has the same access as the associated account. Create or rotate a key from the Account page.

Operations declare their resource requirements in the OpenAPI x-authz extension. Read access is view, write access is edit, and missing grants mean none. The account response includes effective_permissions, combining direct and inherited grants.

Errors

Errors use application/problem+json and include a readable detail. Validation errors can also include field-level entries.

Generation

The backend generates the OpenAPI schema from its registered routes. Use this machine-readable contract for operation parameters, request bodies, and responses. The docs site turns that schema into the operation pages in this section.

mise run openapi-types
mise run //docs:gen-api-docs

Generated API pages should not be edited by hand.