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 CitaBox REST API is an HTTP/JSON interface that powers the CitaBox clinic management platform. Every feature available in the CitaBox dashboard — scheduling, patient records, billing, and analytics — is accessible programmatically through this API. This page covers the foundational conventions you need to understand before calling any endpoint.

​
Base URL

All API requests are made to the base URL configured via the NEXT_PUBLIC_API_URL environment variable. If the variable is not set, the client defaults to http://localhost:3001. 
http://localhost:3001
Set NEXT_PUBLIC_API_URL in your environment to point at the production or staging server.

​
Request format

All requests must send and receive JSON. Include the Content-Type: application/json header on every request that has a body (POST, PATCH). 
curl --request POST \
  --url http://localhost:3001/appointments \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --data '{"patient_id": "p_123", "doctor_id": "d_456", "start_time": "2026-05-20T09:00:00Z", "end_time": "2026-05-20T09:30:00Z"}'

​
Authentication headers

Most endpoints require two headers to identify both the calling user and the clinic context.
HeaderValueRequired
AuthorizationBearer <access_token>Yes (authenticated endpoints)
x-clinic-idUUID of the active clinicYes (authenticated endpoints)
Content-Typeapplication/jsonYes (POST / PATCH)
You obtain the access_token and clinic_id by calling POST /auth/login. See the authentication page for the full login flow.

​
Public endpoints

Booking and public clinic endpoints are exempt from authentication. These paths are designed for the patient-facing booking widget and do not require Authorization or x-clinic-id headers. Public path prefixes:
  • /public/clinics/:slug
  • /booking/*

​
Response structure

Successful responses return JSON bodies with HTTP 2xx status codes. The shape of the body depends on the endpoint. Common patterns:
  • Single object — most GET, POST, and PATCH endpoints return the affected resource directly.
  • Paginated list — GET /patients returns a PaginatedResponse<T> wrapper:
{
  "data": [ ... ],
  "meta": {
    "total": 120,
    "page": 1,
    "limit": 20,
    "totalPages": 6
  }
}
  • 204 No Content — DELETE endpoints return HTTP 204 with no body.

​
Error handling

When a request fails, the API returns a non-2xx status code and a JSON error body: 
{
  "statusCode": 422,
  "message": ["patient_id must be a UUID"],
  "error": "Unprocessable Entity"
}
The message field may be a string or an array of strings (validation errors). The optional error field contains the HTTP reason phrase.
Receiving a 401 Unauthorized response automatically invalidates the stored auth session on the client. You must re-authenticate via POST /auth/login to obtain a new token.

​
Example: authenticated request

# 1. Login to get a token
curl --request POST \
  --url http://localhost:3001/auth/login \
  --header "Content-Type: application/json" \
  --data '{"email": "doctor@clinica.cr", "password": "secret"}'

# 2. Use the token and clinic_id on subsequent requests
curl --request GET \
  --url "http://localhost:3001/appointments?date=2026-05-20" \
  --header "Authorization: Bearer eyJhbGci..." \
  --header "x-clinic-id: 7f3a1b2c-..."

​
Explore the API

Authentication

Login, token management, and the /auth/me endpoint.

Appointments

Schedule, update, cancel appointments, and manage time blocks.

Patients

Search, create, and retrieve patient profiles.

Medical records

Create and retrieve electronic medical records including prescriptions.

Billing

Manage invoices and Costa Rica Hacienda e-billing integration.

Public booking

Unauthenticated endpoints for the patient-facing booking flow.

Analytics

KPI metrics and revenue trends for the admin dashboard.

Build docs developers (and LLMs) love

Get started for freeTalk to us