FHIR Basics

The patient's record on Palamond is standard FHIR R4, served read-first under /v1/fhir. You do not need to master the specification. This page covers the four ideas a builder actually uses: resources, references, search, and bundles.

Remember the split: FHIR is the record; endpoints are the actions. You read the record with the patterns below. You change it through workflow endpoints, with two exceptions the patient authors directly: their own Patient resource and their QuestionnaireResponses.

Resources

A resource is a single typed record: a Patient, an Appointment, an Observation, a CarePlan. Each has a resourceType, a server-assigned id, and a set of fields defined by FHIR.

import type { Patient } from '@palamond/sdk/fhir';

const patient: Patient = await palamond.readResource('Patient', patientId);
console.log(patient.name?.[0]?.family, patient.birthDate);

The @palamond/sdk/fhir types cover every resource, so your editor tells you which fields exist and what they contain.

The one resource-shaped write you will do often is a QuestionnaireResponse, the patient's own answers to a form:

import type { QuestionnaireResponse } from '@palamond/sdk/fhir';

const response: QuestionnaireResponse = {
  resourceType: 'QuestionnaireResponse',
  status: 'completed',
  questionnaire: questionnaire.url, // version-pinned canonical of the form answered
  item: answers,
};

const saved = await palamond.createResource(response);
console.log(saved.id); // server-assigned

Everything else in the record is produced by the platform when you call a workflow endpoint.

References

Resources link to each other by reference, not by embedding. A reference is a string of the form ResourceType/id. Here is an Observation as you read it back from the record, pointing at the patient it was measured on:

{
  "resourceType": "Observation",
  "status": "final",
  "code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4", "display": "Heart rate" }] },
  "subject": { "reference": "Patient/…" },
  "valueQuantity": { "value": 72, "unit": "beats/minute" }
}

To follow a reference, read the target:

const subject = await palamond.readReference(observation.subject);

References are the backbone of the data model. A patient's whole record is a graph of resources that all reference the Patient (directly or one hop away).

Search

Search finds resources by their fields. You pass the resource type and a set of search parameters, and get back the matches. The SDK's typed helpers route to GET /v1/fhir/{ResourceType}, and every search is automatically scoped to the signed-in patient's record.

import type { Appointment } from '@palamond/sdk/fhir';

const upcoming: Appointment[] = await palamond.searchResources('Appointment', {
  status: 'booked',
  _sort: 'date',
  _count: '20',
});

A few parameters you will use constantly:

• Reference parameters (subject, based-on, supporting-info) filter by a link to another resource.
• Token parameters (status, code) filter by a code or value.
• _sort orders results; a leading - reverses (-_lastUpdated is newest first).
• _count limits page size.
• _include pulls referenced resources into the same response so you avoid a second round trip.

Bundles

A bundle is a container of resources. Search results come back as a bundle.

searchResources unwraps the bundle for you and returns a plain array. When you need the bundle itself (for paging links or match metadata), use search:

const bundle = await palamond.search('Observation', { category: 'vital-signs', _count: '5' });
for (const entry of bundle.entry ?? []) {
  console.log(entry.resource?.id);
}

You will not send transaction bundles. Multi-resource changes (rescheduling a visit, completing a task, accepting an agreement) each have a named endpoint that performs the whole change atomically on the server. If you try to write a resource a workflow owns, the 405 response names the endpoint to use instead.

Next

• Organizations - How tenancy works, and why you rarely think about it.
• Codes - Where the system and code values in resources come from.
• Reading and Writing - Patterns for reads and the few patient-authored writes.