Reschedule or Cancel a Visit

Visits are scheduled by the care team, or issued by the platform when an assessment or care plan calls for one. Your app manages the visits the patient already has: GET /v1/availability finds open slots, and the reschedule and cancel actions change the visit. Slot validation is server-side against the same engine availability reads from, so what you show is what reschedule accepts.

A visit has a modality: sync (a live voice or video call at a slot) or async (work the patient completes on their own time, with no calendar slot).

Find the visit

The record plane is the source of truth for what is scheduled:

const upcoming = await palamond.searchResources('Appointment', {
  date: `ge${new Date().toISOString()}`,
  status: 'booked',
  _sort: 'date',
});

const appointment = upcoming[0];

Find a new slot

Ask for open slots for the visit's practitioner or care team. Pass excludeAppointment so the visit's own time counts as free. For a month view, view: 'days' returns per-day counts to shade a calendar.

const availability = await palamond.availability.list({
  careTeam: `CareTeam/${careTeamId}`,
  durationMin: 20,
  horizonDays: 14,
  excludeAppointment: `Appointment/${appointment.id}`,
});
// { view: 'slots', hasAvailability: true, slots: [{ start, end, practitioner }] }

const newSlot = availability.slots[0];

Reschedule

Reschedule is not an in-place edit: it cancels the original and books a linked replacement, so the platform can regenerate the dependent tasks for the new time. The response is the replacement Appointment.

const replacement = await palamond.appointments.reschedule(appointment.id, {
  start: newSlot.start,
  end: newSlot.end,
  practitioner: newSlot.practitioner.reference,
});

A slot can be taken between reading availability and rescheduling. That answers 409 conflict: refresh availability and let the patient pick again; the original visit is untouched.

Or cancel

await palamond.appointments.cancel(appointment.id, {
  reason: 'Feeling better',
});

The platform cascades the cancellation: not-yet-picked-up work is cancelled with it, and a materialized Encounter is cancelled too.

Starting the visit

The visit Encounter is created lazily, when the visit actually begins, not when it is scheduled. When your app opens the visit experience, materialize it idempotently:

const { encounter } = await palamond.appointments.startEncounter(appointment.id);

A 409 consent_required here means required agreements are unmet; accept them via agreements and retry.

What the platform does for you

Validates the new slot against live availability before writing anything; no double bookings.
On reschedule, cancels the original with reason rescheduled, links the pair, and regenerates dependent tasks and the encounter for the new time.
On cancel, unwinds the visit's open work so you never clean up by hand.