Overview
One API, two planes - what the surface is and how to call it.
The Palamond API is one HTTP surface, versioned under /v1: https://api.prd.palamond.dev in production, with a host per environment (https://api.lab.palamond.dev for the lab). 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.