Developer Docs

REST Reference

Canonical willaOS REST resources, request/response shapes, and generated reference artifacts.

The canonical REST namespace is /api/*. There is no public /api/v1 contract.

Response Envelope

Most JSON routes return:

{
  "data": {},
  "request_id": "req_..."
}

Validation and auth failures return an error envelope or simple error object depending on legacy route age:

{
  "error": {
    "message": "X-Version header is required"
  },
  "request_id": "req_..."
}

Some file routes return the file body directly instead of a JSON envelope.

Core Resources

Resource	Methods	Notes
`/api/clients`	`GET`, `POST`	List and create client records.
`/api/clients/{id}`	`GET`, `PATCH`, `DELETE`	Read, update, and soft-delete one client. Mutations use `X-Version`.
`/api/clients/{id}/{field}`	`GET`, `PUT`	Field-level client reads and writes guarded by field permissions.
`/api/clients/{id}/projects`	`GET`, `POST`	List or create projects under a client.
`/api/projects`	`GET`	List visible projects.
`/api/projects/{id}`	`GET`, `PATCH`, `DELETE`	Read, update, and soft-delete one project. Mutations use `X-Version`.
`/api/projects/{id}/documents`	`GET`, `POST`	Project document list and create.
`/api/projects/{id}/workstreams`	`GET`, `PATCH`	First-class workstream state and blockers.
`/api/projects/{id}/readiness-rollup`	`GET`	Cross-system readiness rollup.
`/api/projects/{id}/qa-config`	`GET`	QA extension project contract.
`/api/projects/{id}/qa-items`	`GET`, `POST`	Canonical QA item intake and list.
`/api/sops`	`GET`, `POST`	SOP registry.
`/api/skills`	`GET`	Pull-only Skill Library sync metadata.
`/api/skills/{slug}`	`GET`	One active installable Skill Library bundle with version/checksum metadata.
`/api/milestones`	`GET`	Cross-project milestone list.
`/api/meeting-proposals`	`GET`, `POST`	Meeting availability proposal workflow.
`/api/status`	`GET`	Public JSON health check.

The full generated route inventory is in REST Route Inventory. The OpenAPI seed is docs/openapi/willaos-public.json and covers the stable core routes that should be exposed first in hosted reference navigation.

Query And Body Shapes

List routes commonly support limit, cursor, client_id, project_id, status, or route-specific filters. Invalid query params return 400.

Write routes accept JSON bodies validated by local Zod schemas or route-specific domain parsers. Unknown or unsupported fields are ignored only on legacy routes; newer routes reject invalid input.

Request IDs

When a route returns request_id, include it in support or incident reports. It is also the preferred correlation key for audits and logs.