Appointments API

Create an appointment

Create an appointment in the current workspace.

POST/v1/appointments

capability appointments.create · v1health dataserver-scoped workspace

Request

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

patientIdstring<uuid>required
body
practitionerIdstring<uuid>required
body
startsAtstring<date-time>required
body
durationMinutesintegerrequired
bodymin 5max 480
reasonstring | null
bodydefault nullmax length 240

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.
409The requested appointment time is unavailable.
422The appointment details are invalid.
503The appointment could not be saved.

Request

import { createDawnClient } from "@dawn/api";
import { patientIdSchema, practitionerIdSchema } from "@dawn/domain";

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

const result = await dawn.capabilities["appointments.create"]({
  "patientId": patientIdSchema.parse("33333333-3333-4333-8333-333333333333"),
  "practitionerId": practitionerIdSchema.parse("44444444-4444-4444-8444-444444444444"),
  "startsAt": "2026-08-01T09:00:00.000Z",
  "durationMinutes": 5,
  "reason": null,
});

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

Response

Created.

{
  "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": {}
}