How It Fits Together
The two planes of the API, and how platform automation reacts to your calls.
Every interaction with Palamond goes through one API with two planes. Getting the split straight is the whole mental model:
The actions: workflow endpoints
Anything that changes the care workflow is a named endpoint: start an assessment, complete a task, reschedule a visit, accept an agreement, decide an order. The SDK wraps each one as a typed method on the client, so you call it, the platform validates it, and you get a typed result (or a precise error) in the same request.
// One call moves the visit; the platform validates the new slot server-side.
const replacement = await palamond.appointments.reschedule(appointment.id, {
start: slot.start,
end: slot.end,
practitioner: slot.practitioner.reference,
});Business failures are proper HTTP statuses with a stable machine code, never a 200 with a failure inside. A stale slot is a 409 with error.code: 'conflict'; unmet agreements are a 409 with error.code: 'consent_required' and the agreements listed in error.details. See Errors and Limits.
The record: the FHIR plane
Everything the platform knows about the patient is a FHIR R4 resource, read under /v1/fhir with standard FHIR search. The SDK's typed helpers target this plane directly:
const tasks = await palamond.searchResources('Task', {
'status:not': 'completed',
_sort: '-_lastUpdated',
});The record is almost entirely read-only. The exceptions are the few resources the patient personally authors: their own Patient demographics and their QuestionnaireResponse answers. Everything else answers 405 naming the workflow endpoint that owns the change, so a wrong turn corrects itself.
Automation reacts, you read back
An action does more than store data. Server-side, the platform advances the workflow: completing an intake task opens the clinician review; accepting a consent bundle activates the care plan; deciding an order places it. That happens after your call returns, and the results land as new or updated FHIR resources.
// A short time later, the platform's work is visible as normal FHIR data.
const next = await palamond.searchResources('Task', {
'based-on': started.appointment,
});Do not expect downstream resources to exist the instant your call returns. Read them back rather than assuming they are there.
Why it works this way
- Consistency. The clinical rules run server-side, once. Two apps taking the same action get the same downstream behavior.
- Safety. Every call acts as the signed-in patient, and the platform's access policies scope every read and write. There is no privileged client.
- Auditability. Actions and their side effects are all FHIR resources with provenance. The record of what happened is queryable.
Where to go next
- The API - The full surface, plane by plane.
- Complete an Assessment - The two planes working together, end to end.