API reference

Reference

The interactive API reference is served by the Weeks app:

Open the API reference

It uses Scalar and the current OpenAPI document from the app, so endpoint details stay with the application code that implements them.

The static docs should also build from that same OpenAPI document. That keeps the app-hosted reference available at weeks.app/api while giving the docs site a faster reference page and stable anchors for coverage links.

Create a space The product interaction behind the spaces create endpoint. Open the interaction

Authentication

Send an OAuth access token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Existing clients can also supply the token in the access_token query parameter. Prefer the header so credentials do not appear in URLs or URL logs. If no valid token identifies a user, the API responds with 401 and:

{"error":"Invalid token or no user signed in"}

Errors

The API uses three implementation-backed JSON error shapes:

• Authentication, lookup, pagination, and include failures return an error string.
• Model validation failures return an object keyed by field, with an array of messages for each field.
• Custom actions that can report several messages return an errors array.

Check the operation in the interactive API reference for its documented 400, 401, 404, and 422 responses. A 404 can also mean that a resource is not available to the authenticated user.

OpenAPI

The machine-readable document is available at:

https://weeks.app/api/v1/openapi.yaml

Use that document for generated clients, contract checks, and exact endpoint lookups. The main staffing surfaces currently include spaces, plans, slots, jobs, assigned people, assigned jobs, job routes, planning contexts, and planning states.

Coverage

The API reference explains each endpoint in isolation. Coverage connects those endpoints to user interactions and CLI commands, so we can see which real workflows are complete across surfaces.