Appointments API

Create, retrieve, update, and cancel appointments across your clinic.

GET/v1/appointments

Returns a paginated list of appointments. Filter by date, doctor, or status.

Query Parameters

Parameter	Type	Required	Description
date	string	Optional	Filter by date (YYYY-MM-DD)
doctor_id	string	Optional	Filter by doctor UUID
status	string	Optional	Filter by status: scheduled, completed, cancelled
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Results per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.relaya.one/v1/appointments?date=2026-07-25&status=scheduled" \
  -H "Authorization: Bearer rlya_live_abc123"

Example Response

{
  "data": [
    {
      "id": "apt_8xk2m9v3",
      "patient_id": "pat_4jn7h2",
      "doctor_id": "doc_9km3p1",
      "datetime": "2026-07-25T10:00:00Z",
      "duration": 30,
      "status": "scheduled",
      "notes": "Follow-up consultation",
      "created_at": "2026-07-20T14:32:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "has_more": false
  }
}

POST/v1/appointments

Create a new appointment. Validates against doctor availability.

Request Body

Parameter	Type	Required	Description
patient_id	string	Required	Patient UUID
doctor_id	string	Required	Doctor UUID
datetime	string	Required	ISO 8601 datetime
duration	integer	Required	Duration in minutes (15, 30, 45, 60)
notes	string	Optional	Optional appointment notes
type	string	Optional	Appointment type: consultation, follow_up, procedure

Example Request

curl -X POST "https://api.relaya.one/v1/appointments" \
  -H "Authorization: Bearer rlya_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_4jn7h2",
    "doctor_id": "doc_9km3p1",
    "datetime": "2026-07-28T14:00:00Z",
    "duration": 30,
    "notes": "Annual checkup"
  }'

Example Response

{
  "data": {
    "id": "apt_n3k8m2v1",
    "patient_id": "pat_4jn7h2",
    "doctor_id": "doc_9km3p1",
    "datetime": "2026-07-28T14:00:00Z",
    "duration": 30,
    "status": "scheduled",
    "notes": "Annual checkup",
    "type": "consultation",
    "created_at": "2026-07-25T09:15:00Z"
  }
}

GET/v1/appointments/:id

Retrieve a single appointment by its ID.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	Appointment UUID

PATCH/v1/appointments/:id

Update an existing appointment. Only provided fields are modified.

Request Body

Parameter	Type	Required	Description
datetime	string	Optional	New ISO 8601 datetime
duration	integer	Optional	New duration in minutes
notes	string	Optional	Updated notes
status	string	Optional	New status: scheduled, completed, no_show

DELETE/v1/appointments/:id

Cancel an appointment. Sets status to cancelled. Cannot be undone.

Example Response

{
  "data": {
    "id": "apt_8xk2m9v3",
    "status": "cancelled",
    "cancelled_at": "2026-07-25T11:00:00Z"
  }
}

Error Codes

Code	Status	Description
400	bad_request	Invalid parameters or missing required fields
401	unauthorized	Invalid or missing API key
404	not_found	Appointment not found
409	conflict	Time slot not available (scheduling conflict)
422	unprocessable	Invalid datetime or duration value
429	rate_limited	Too many requests