API conventions

The API runs on port 6400 locally. Use the endpoint reference for request fields, response schemas, status codes, and copyable typed SDK, cURL, JavaScript, and Python examples generated from the implemented contract.

Operational and discovery routes:

Patient deletion returns 409 when appointments still reference the patient. Set the patient status to archived with PATCH instead so their appointment history remains intact.

Workspace context

Requests do not contain a workspace selector. Non-browser clients send a short-lived signed token:

curl http://localhost:6400/v1/patients \
  -H "Authorization: Bearer $DAWN_ACCESS_TOKEN"

Web sessions use the HttpOnly dawn_access cookie. Member claims carry a member ID and role. Patient claims carry one patient ID and cannot read another patient’s record or appointments. Missing, expired, or invalid tokens return 401; role and subject violations return 403. Static owner access is limited to non-production demo mode.

OpenAPI

Endpoint methods, paths, inputs, success responses, and problem statuses are defined in @dawn/api. Its OpenAPI generator converts the referenced domain and API Zod schemas instead of maintaining separate schema copies.

Fetch the current runtime document from /openapi.json. The checked-in artifact at packages/api/openapi.json is refreshed and verified with:

pnpm openapi:generate
pnpm openapi:check

Each operation includes an x-dawn-capability extension linking its typed HTTP contract to the transport-neutral capability catalog. Workspace-owned operations also include x-dawn-workspace-scoped: true; that is metadata, not a client-supplied tenant selector.

Response envelopes

Successful responses use one envelope:

{
  "data": {}
}

Failures use one error envelope:

{
  "error": {
    "kind": "validation",
    "code": "invalid_patient",
    "message": "The patient details are invalid."
  }
}

Client code should branch on the HTTP status and parse the matching envelope.