Overview
One API, two planes - what the surface is and how to call it.
The Palamond API is one HTTP surface, versioned under /v1, served from your environment's API host (https://api.lab.palamond.dev here, a host per environment). The path tree follows the SDK namespaces, so palamond.patient.profile() maps to GET /v1/patient/profile, palamond.agreements.accept(...) maps to POST /v1/agreements/acceptances, and the OpenAPI document reads the same way your client code does. It follows a single rule:
FHIR is the record; endpoints are the actions.
| Plane | What it is | Where |
|---|---|---|
| Actions | Named workflow endpoints: start, complete, reschedule, accept, decide. | /v1/... |
| Record | FHIR R4 reads over the patient's chart, plus the few patient-authored writes. | /v1/fhir/... |
Exactly one path exists for any operation. If you try to write a resource on the record plane that a workflow owns, the 405 response names the endpoint to use instead.
Authentication
Every call carries a bearer token for a signed-in patient session:
Authorization: Bearer <access token>The SDK attaches it for you once the patient signs in. The API serves patient sessions only: each call acts as that patient and is scoped to their record by the platform's access policies. Staff and machine tokens are refused. Sign-in flows are covered in Authentication.
The record plane
GET /v1/fhir/{ResourceType} searches with standard FHIR search parameters and returns a Bundle; GET /v1/fhir/{ResourceType}/{id} reads one resource. The SDK's typed helpers (searchResources, readResource) target this plane.
Writes exist only where the patient is the author of record:
| Resource | Methods | Why |
|---|---|---|
Patient | PUT (own resource only) | The patient maintains their own demographics. |
QuestionnaireResponse | POST, PUT | The patient authors their own answers. |
Everything else changes through a workflow endpoint. FHIR operations ($...) are not available.
The action endpoints
The full list is on Endpoints, and every one of them is a typed method on the SDK client (assessments.start, tasks.complete, appointments.reschedule, ...), so in JavaScript and TypeScript you never call them by URL. Requests and responses are JSON; FHIR resources in responses are served as application/fhir+json. Fields named after a resource (healthcareService, carePlan, encounter) hold plain Type/<id> reference strings, and protocol and assessment fields hold canonicals (url|version), so a value from one response drops into the next request unchanged. Business failures are proper HTTP statuses carrying a machine-readable error envelope, never a 200 with a failure inside.
The OpenAPI document
The API describes itself: GET /v1/openapi.json serves the OpenAPI 3.1 document for the whole surface, generated from the same contracts that validate every request. Point your codegen or API client at it.
The API host root renders that document as a browsable reference: open https://api.lab.palamond.dev in your browser. Each environment serves its own, and the reference advertises the host it was served from.