Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/FerchoSG/healthcare-web/llms.txt

Use this file to discover all available pages before exploring further.

The appointments API lets you query, create, update, and delete clinic appointments. It also exposes time blocks — periods when a doctor is unavailable — which the booking engine uses when calculating available slots. All endpoints require a valid Authorization bearer token and x-clinic-id header scoped to the active clinic.

​
AppointmentStatus values

Appointments move through a defined lifecycle. The valid status values are:
ValueDescription
PENDINGAppointment has been created but not confirmed.
CONFIRMEDAppointment confirmed by clinic staff.
WAITINGPatient has arrived and is in the waiting room.
IN_CONSULTATIONPatient is currently with the doctor.
COMPLETEDConsultation is finished.
CANCELLEDAppointment was cancelled.

​
GET /appointments

Fetch appointments for a date range or a single date. The x-clinic-id header scopes results to the active clinic. Query parameters
​
startDate
string
Start of the date range in YYYY-MM-DD format. Used together with endDate to fetch a range.
​
endDate
string
End of the date range in YYYY-MM-DD format. Used together with startDate.
​
date
string
A single date in YYYY-MM-DD format. When startDate equals endDate, the client sends date instead of the range pair.
Response — Appointment[]
​
id
string
UUID of the appointment.
​
clinic_id
string
UUID of the owning clinic.
​
patient_id
string
UUID of the patient.
​
doctor_id
string
UUID of the doctor.
​
service_id
string | null
UUID of the booked service, or null.
​
start_time
string
ISO 8601 UTC start time.
​
end_time
string
ISO 8601 UTC end time.
​
status
string
Current AppointmentStatus value.
​
reason
string | null
Patient-provided reason for the visit, or null.
​
reminder_sent
boolean
Whether a reminder was sent to the patient.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
​
patient
object
​
doctor
object
​
service
object | null
# Fetch appointments for a date range
curl --request GET \
  --url "http://localhost:3001/appointments?startDate=2026-05-19&endDate=2026-05-23" \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

# Fetch appointments for a single date
curl --request GET \
  --url "http://localhost:3001/appointments?date=2026-05-20" \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

​
POST /appointments

Create a new appointment. Request body
​
patient_id
string
required
UUID of the patient.
​
doctor_id
string
required
UUID of the doctor who will see the patient.
​
start_time
string
required
ISO 8601 UTC start time. Example: 2026-05-20T09:00:00Z.
​
end_time
string
required
ISO 8601 UTC end time. Example: 2026-05-20T09:30:00Z.
​
reason
string
Optional free-text reason for the appointment.
​
service_id
string
Optional UUID of the service being booked.
Response — Appointment Returns the newly created appointment object. See the GET /appointments section for the full field list. 
curl --request POST \
  --url http://localhost:3001/appointments \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "patient_id": "p_abc123",
    "doctor_id": "d_def456",
    "start_time": "2026-05-20T09:00:00Z",
    "end_time": "2026-05-20T09:30:00Z",
    "reason": "Dolor de cabeza recurrente",
    "service_id": "svc_789"
  }'

​
PATCH /appointments/:id/status

Update the status of an existing appointment. Use this endpoint to advance appointments through the lifecycle (e.g., from CONFIRMED to WAITING). Path parameters
​
id
string
required
UUID of the appointment to update.
Request body
​
status
string
required
New status value. Must be a valid AppointmentStatus: PENDING, CONFIRMED, WAITING, IN_CONSULTATION, COMPLETED, or CANCELLED.
Response — Appointment The updated appointment object. 
curl --request PATCH \
  --url http://localhost:3001/appointments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{"status": "CONFIRMED"}'

​
PATCH /appointments/:id

Update appointment details such as the scheduled time or reason. Path parameters
​
id
string
required
UUID of the appointment to update.
Request body
​
start_time
string
New ISO 8601 UTC start time.
​
end_time
string
New ISO 8601 UTC end time.
​
reason
string
Updated reason for the appointment.
​
status
string
Updated appointment status.
Response — Appointment The updated appointment object. 
curl --request PATCH \
  --url http://localhost:3001/appointments/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "start_time": "2026-05-20T10:00:00Z",
    "end_time": "2026-05-20T10:30:00Z"
  }'

​
DELETE /appointments/:id

Soft-delete an appointment. Returns HTTP 204 with no body on success. Path parameters
​
id
string
required
UUID of the appointment to delete.
curl --request DELETE \
  --url http://localhost:3001/appointments/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

​
Time blocks

Time blocks mark periods when a doctor is unavailable. They are used by the booking engine to exclude those periods from available slots.

​
GET /time-blocks

Fetch time blocks for a date range, optionally filtered by doctor. Query parameters
​
startDate
string
required
Start of the range in YYYY-MM-DD format.
​
endDate
string
End of the range in YYYY-MM-DD format.
​
doctor_id
string
Filter results to a specific doctor UUID.
Response — TimeBlock[]
​
id
string
UUID of the time block.
​
doctor_id
string
UUID of the doctor who is blocked.
​
clinic_id
string
UUID of the owning clinic.
​
start_time
string
ISO 8601 UTC start of the block.
​
end_time
string
ISO 8601 UTC end of the block.
​
reason
string | null
Optional reason for the block.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
​
doctor
object
curl --request GET \
  --url "http://localhost:3001/time-blocks?startDate=2026-05-19&endDate=2026-05-23&doctor_id=d_def456" \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

​
POST /time-blocks

Create a new time block for a doctor. Request body
​
doctor_id
string
required
UUID of the doctor to block.
​
start_time
string
required
ISO 8601 UTC start of the block.
​
end_time
string
required
ISO 8601 UTC end of the block.
​
reason
string
Optional free-text reason for the block (e.g., “Congreso médico”).
Response — TimeBlock The newly created time block object. 
curl --request POST \
  --url http://localhost:3001/time-blocks \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "doctor_id": "d_def456",
    "start_time": "2026-05-22T12:00:00Z",
    "end_time": "2026-05-22T14:00:00Z",
    "reason": "Almuerzo de equipo"
  }'

​
DELETE /time-blocks/:id

Delete a time block. Returns HTTP 204 with no body on success. Path parameters
​
id
string
required
UUID of the time block to delete.
curl --request DELETE \
  --url http://localhost:3001/time-blocks/tb_xyz789 \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

Build docs developers (and LLMs) love

Get started for freeTalk to us