Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bentlyy/Clinica/llms.txt

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

Bookings are the core of Clinica. You can check which time slots a doctor has open, create an appointment, view all your upcoming bookings, and cancel an appointment you no longer need. A confirmation email is sent to your address whenever you book or cancel. All booking endpoints require authentication. Include your JWT token in every request — see Authenticate with Clinica for how to obtain one.

​
Check available slots

Before booking, check which time slots a doctor has open on a given date. This endpoint returns a list of available start times, spaced 15 minutes apart, that fit within the doctor’s working hours and are not already taken. 
curl "http://localhost:3000/api/bookings/available-slots?doctor_id=5&date=2026-05-10&duration=30" \
  -H "Authorization: Bearer <token>"
Query parameters
ParameterRequiredDescription
doctor_idYesThe ID of the doctor you want to book.
dateYesThe date to check, in YYYY-MM-DD format.
durationNoAppointment length in minutes. Defaults to 30.
Response 
["09:00", "09:15", "09:30", "10:00", "10:15"]
An empty array means the doctor has no availability on that day or all slots are taken.

​
Create a booking

Once you’ve chosen a slot, create the booking. Your user ID is read from your token — you don’t need to include it in the request body. 
curl -X POST http://localhost:3000/api/bookings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "doctor_id": 5,
    "date": "2026-05-10",
    "time": "09:30",
    "duration": 30
  }'
Body parameters
FieldRequiredDescription
doctor_idYesThe ID of the doctor to book with.
dateYesAppointment date in YYYY-MM-DD format. Must be a future date.
timeYesAppointment start time in HH:MM (24-hour) format.
durationNoLength in minutes. Must be between 1 and 480. Defaults to 30.
Response 
{
  "id": 101,
  "doctor_id": 5,
  "user_id": 42,
  "date": "2026-05-10",
  "time": "09:30:00",
  "duration": 30
}
A confirmation email is sent to your registered address with the doctor’s name, date, and time.

​
Validation rules

The API enforces several rules when creating a booking:
  • The appointment must fall within the doctor’s configured availability window for that day of the week.
  • The time slot must not overlap with any existing booking for that doctor.
  • The time slot must not fall within a blocked exception period set by the doctor.
  • duration must be between 1 and 480 minutes (8 hours maximum).
  • time must be in HH:MM 24-hour format.
If any of these conditions are not met, the API returns a 400 error with a description of the problem.

​
View your bookings

Retrieve all bookings associated with your account, ordered by date and time. 
curl http://localhost:3000/api/bookings/me \
  -H "Authorization: Bearer <token>"
Response 
[
  {
    "id": 101,
    "date": "2026-05-10",
    "time": "09:30:00",
    "duration": 30,
    "doctor_name": "Dr. Sofia Ruiz",
    "specialty": "General Medicine"
  }
]

​
Cancel a booking

Cancel a booking by its ID. You can only cancel your own bookings — attempting to cancel another patient’s booking returns a 400 error. 
curl -X DELETE http://localhost:3000/api/bookings/101 \
  -H "Authorization: Bearer <token>"
Response 
{ "message": "Booking cancelled successfully" }
A cancellation email is sent to your registered address with the original appointment date and time.
Cancellation is immediate and cannot be undone through the API. There is no confirmation step.

Build docs developers (and LLMs) love

Get started for freeTalk to us