Scheduling API Reference

Scheduling API Reference

All scheduling endpoints require an x-api-key header. All request and response bodies use application/json unless noted otherwise.

---

Appointments

Method	Path	Description
POST	/v1/scheduling/appointments	Create appointment
GET	/v1/scheduling/appointments	List appointments (cursor-paginated)
GET	/v1/scheduling/appointments/{id}	Get appointment detail with status history
PUT	/v1/scheduling/appointments/{id}	Update notes, room, or metadata (requires version)
DELETE	/v1/scheduling/appointments/{id}	Cancel appointment (shorthand)

Appointment Lifecycle

Method	Path	Transition	Body fields
POST	/v1/scheduling/appointments/{id}/confirm	requested → confirmed	confirmed_by (string, optional)
POST	/v1/scheduling/appointments/{id}/check-in	confirmed → checked_in	checked_in_by (string, optional)
POST	/v1/scheduling/appointments/{id}/start	checked_in → in_progress	none
POST	/v1/scheduling/appointments/{id}/complete	in_progress → completed	notes (string, optional)
POST	/v1/scheduling/appointments/{id}/no-show	confirmed/checked_in → no_show	notes (string, optional)
POST	/v1/scheduling/appointments/{id}/cancel	requested/confirmed/checked_in → cancelled	reason, cancelled_by (both optional)
POST	/v1/scheduling/appointments/{id}/reschedule	creates new appointment	new_start_time, new_end_time, new_location_id, new_room_id, reason

Fields marked * are required.

AppointmentCreate required fields

Field	Type
provider_profile_id	UUID
patient_id	UUID
appointment_type_id	UUID
location_id	UUID
start_time	datetime (UTC)
end_time	datetime (UTC)

Optional: room_id, source (default "api"), notes, internal_notes, external_reference, metadata.

Status codes

Code	Meaning
201	Appointment created
200	Operation succeeded
204	Deleted/deactivated
404	Appointment not found
409	Conflict (double-booking) or invalid transition
422	Validation error

---

Slots

Method	Path	Description
GET	/v1/scheduling/slots	Search available appointment slots

Required query parameters

Parameter	Type
date_from	date
date_to	date (max 30 days from date_from)
appointment_type_id	UUID
provider_id OR specialty	UUID or string (at least one required)

Optional: location_id, duration_minutes, limit (default 50, max 200), cursor.

AvailableSlot fields

provider_id, provider_name, specialty, location (object with id/name), date, start_time (HH:MM), end_time (HH:MM), available (bool), score (float).

---

Providers

Method	Path	Description
POST	/v1/scheduling/providers	Create provider profile
GET	/v1/scheduling/providers	List providers
GET	/v1/scheduling/providers/{id}	Get provider
PUT	/v1/scheduling/providers/{id}	Update provider
DELETE	/v1/scheduling/providers/{id}	Deactivate provider (soft delete, 204)

ProviderProfileCreate required fields

Field	Type
doctor_id	UUID

Optional: default_appointment_duration_minutes (default 30), buffer_between_appointments_minutes (default 0), max_daily_appointments, max_concurrent_appointments (default 1), primary_location_id, specialties, is_accepting_new_patients (default true), metadata.

Schedule Templates

Method	Path	Description
GET	/v1/scheduling/providers/{id}/templates	List templates
POST	/v1/scheduling/providers/{id}/templates	Create template
PUT	/v1/scheduling/providers/{id}/templates/{tid}	Update template
DELETE	/v1/scheduling/providers/{id}/templates/{tid}	Deactivate template (soft delete, 204)

Schedule Overrides

Method	Path	Description
GET	/v1/scheduling/providers/{id}/overrides	List overrides
POST	/v1/scheduling/providers/{id}/overrides	Create override (blocked, modified, or added)
DELETE	/v1/scheduling/providers/{id}/overrides/{oid}	Delete override (hard delete, 204)

Conflict Detection

Method	Path	Description
GET	/v1/scheduling/providers/{id}/cross-location-conflicts	Check cross-location conflicts
GET	/v1/scheduling/providers/{id}/locations-schedule	Full multi-location schedule view

---

Webhooks

Method	Path	Description
POST	/v1/scheduling/webhooks	Create subscription
GET	/v1/scheduling/webhooks	List subscriptions
GET	/v1/scheduling/webhooks/{id}	Get subscription
PUT	/v1/scheduling/webhooks/{id}	Update subscription
DELETE	/v1/scheduling/webhooks/{id}	Deactivate subscription (soft delete, 204)
POST	/v1/scheduling/webhooks/{id}/test	Send test event
GET	/v1/scheduling/webhooks/{id}/deliveries	Delivery history
GET	/v1/scheduling/webhooks/dead-letters	Dead-letter queue

---

Conversation Engine

Method	Path	Description
POST	/v1/scheduling/conversation	Process conversation message (FSM multi-turn)
GET	/v1/scheduling/conversation/{patient_id}/{channel}/state	Get FSM state (debug)
DELETE	/v1/scheduling/conversation/{patient_id}/{channel}	Clear conversation state

---

Natural Language Scheduling

Method	Path	Description
POST	/v1/scheduling/natural-language	Process NL scheduling request in Brazilian Portuguese

Request: { message: string, patient_id: UUID, ... }. Returns extracted entities and resolved database references.

---

Voice Scheduling

Method	Path	Description
POST	/v1/scheduling/voice	Process audio file for scheduling intent

Request: multipart/form-data with audio (file) and patient_id (UUID form field). Returns VoiceSchedulingResponse or VoiceClarificationResponse.

Note

Audio data is processed in-memory only. No audio is persisted (LGPD compliance).

---

No-Show Prediction

Method	Path	Description
GET	/v1/scheduling/no-show/appointments/{appointment_id}/risk	Single appointment risk score
GET	/v1/scheduling/no-show/daily-risks	Batch risk scores for a date (query: date)
GET	/v1/scheduling/no-show/model-info	Prediction model metadata

NoShowRiskResponse fields

risk_score (float, 0–1), risk_level (low/medium/high), risk_factors (array), recommendation (string).

---

Waitlist

Method	Path	Description
POST	/v1/scheduling/waitlist	Add patient to waitlist
GET	/v1/scheduling/waitlist	List waitlist entries
DELETE	/v1/scheduling/waitlist/{id}	Remove from waitlist (204)
GET	/v1/scheduling/waitlist/position/{id}	Get queue position

---

Common Error Responses

All scheduling endpoints use a consistent error format:

{
  "detail": "Human-readable error message"
}

HTTP Code	When it occurs
401	Missing or invalid API key
403	Insufficient permissions for this tenant
404	Resource not found
409	Conflict (double-booking, duplicate, or invalid status transition)
422	Request body or query parameter validation failure
500	Internal server error