Appointments API

Transition an appointment

Move an appointment through its supported lifecycle.

PATCH/v1/appointments/{appointmentId}

capability appointments.transition · v1health dataserver-scoped workspace

Request

Path, query, and JSON body fields accepted by this operation.

appointmentIdstring<uuid>required
path
status"scheduled" | "checked_in" | "in_progress" | "completed" | "cancelled" | "no_show"required
body
expectedUpdatedAtstring<date-time>required
body

Response

Successful responses use Dawn's data envelope.

dataAppointmentrequired
- idstring<uuid>required
- workspaceIdstring<uuid>required
- patientIdstring<uuid>required
- practitionerIdstring<uuid>required
- startsAtstring<date-time>required
- endsAtstring<date-time>required
- status"scheduled" | "checked_in" | "in_progress" | "completed" | "cancelled" | "no_show"required
- reasonstring | nullrequired
  max length 240
- createdAtstring<date-time>required
- updatedAtstring<date-time>required
metaobject

Errors

Error responses use the shared error envelope.

403Scheduling is disabled or unavailable.
404The appointment could not be found.
409The transition is not allowed or the appointment changed.
422The appointment transition is invalid.
503The appointment could not be updated.

Request

import { createDawnClient } from "@dawn/api";
import { appointmentIdSchema } from "@dawn/domain";

const dawn = createDawnClient({
  baseUrl: "http://localhost:6400",
});

const result = await dawn.capabilities["appointments.transition"]({
  "appointmentId": appointmentIdSchema.parse("11111111-1111-4111-8111-111111111111"),
  "transition": {
    "status": "scheduled",
    "expectedUpdatedAt": "2026-08-01T09:00:00.000Z",
  },
});

if (result.isErr()) throw result.error;
console.log(result.value);

Response

Successful response.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "workspaceId": "22222222-2222-4222-8222-222222222222",
    "patientId": "33333333-3333-4333-8333-333333333333",
    "practitionerId": "44444444-4444-4444-8444-444444444444",
    "startsAt": "2026-08-01T09:00:00.000Z",
    "endsAt": "2026-08-08T17:00:00.000Z",
    "status": "scheduled",
    "reason": null,
    "createdAt": "2026-08-01T09:00:00.000Z",
    "updatedAt": "2026-08-01T09:00:00.000Z"
  },
  "meta": {}
}