Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DUVAN100/saludya-api/llms.txt

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

This documentation represents the API specification for SaludYa. The examples below demonstrate the intended API design and behavior.

​
Welcome to SaludYa API

This guide provides example API requests for the SaludYa medical appointment management system. You’ll see how authentication works, how to retrieve patient information, and create appointments.

​
API Base URL

The API is designed to be hosted at: 
https://api.saludya.com/v1

​
Prerequisites

When implementing this API, clients will need:
  • An API key for authentication
  • A tool to make HTTP requests (curl, Postman, or any HTTP client)
1

API Key Authentication

The API uses bearer token authentication. API keys should be included in the Authorization header.
Keep your API key secure and never commit it to version control. Treat it like a password.
2

Authenticate Your Request

All API requests require authentication using your API key in the Authorization header with the Bearer scheme.
curl https://api.saludya.com/v1/auth/verify \
  -H "Authorization: Bearer YOUR_API_KEY"
Response:
{
  "status": "success",
  "data": {
    "organization_id": "org_7Yh8KpQmN3",
    "organization_name": "City Medical Center",
    "environment": "production"
  }
}
3

Retrieve Available Doctors

Before creating an appointment, let’s fetch the list of available doctors in your organization.
curl https://api.saludya.com/v1/doctors?specialty=cardiology \
  -H "Authorization: Bearer YOUR_API_KEY"
Response:
{
  "status": "success",
  "data": [
    {
      "id": "doc_9KmLp3xQw2",
      "name": "Dr. Maria Rodriguez",
      "specialty": "cardiology",
      "license_number": "MED-12345",
      "available_slots": 12
    },
    {
      "id": "doc_5TnPq8vRx4",
      "name": "Dr. Carlos Mendez",
      "specialty": "cardiology",
      "license_number": "MED-67890",
      "available_slots": 8
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 2
  }
}
4

Get Doctor Availability

Check available time slots for a specific doctor on a given date.
curl "https://api.saludya.com/v1/doctors/doc_9KmLp3xQw2/availability?date=2026-03-10" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response:
{
  "status": "success",
  "data": {
    "doctor_id": "doc_9KmLp3xQw2",
    "date": "2026-03-10",
    "slots": [
      {
        "start_time": "09:00",
        "end_time": "09:30",
        "available": true
      },
      {
        "start_time": "09:30",
        "end_time": "10:00",
        "available": true
      },
      {
        "start_time": "10:00",
        "end_time": "10:30",
        "available": false
      }
    ]
  }
}
5

Create an Appointment

Now let’s create a medical appointment for a patient.
curl -X POST https://api.saludya.com/v1/appointments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient": {
      "id": "pat_4XmNp9kLq7",
      "name": "Juan Perez",
      "email": "juan.perez@example.com",
      "phone": "+52-555-1234"
    },
    "doctor_id": "doc_9KmLp3xQw2",
    "date": "2026-03-10",
    "start_time": "09:00",
    "end_time": "09:30",
    "reason": "Cardiac consultation",
    "type": "in-person"
  }'
Response:
{
  "status": "success",
  "data": {
    "id": "apt_8QrLm5xTw3",
    "patient": {
      "id": "pat_4XmNp9kLq7",
      "name": "Juan Perez",
      "email": "juan.perez@example.com",
      "phone": "+52-555-1234"
    },
    "doctor": {
      "id": "doc_9KmLp3xQw2",
      "name": "Dr. Maria Rodriguez",
      "specialty": "cardiology"
    },
    "date": "2026-03-10",
    "start_time": "09:00",
    "end_time": "09:30",
    "reason": "Cardiac consultation",
    "type": "in-person",
    "status": "confirmed",
    "confirmation_code": "SALUD-8Q3W",
    "created_at": "2026-03-06T14:32:10Z"
  }
}
Congratulations! You’ve successfully created your first appointment with the SaludYa API.
6

Retrieve Appointment Details

You can retrieve the details of any appointment using its ID.
curl https://api.saludya.com/v1/appointments/apt_8QrLm5xTw3 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Next Steps

Now that you’ve made your first API calls, explore more capabilities:

API Reference

Explore all available endpoints and their parameters

Authentication

Learn about API keys, OAuth, and security best practices

Rate Limits

Understand rate limiting and best practices

Error Handling

Understand error codes and how to handle them

​
Common Use Cases

Use the PATCH endpoint to update appointment status:
curl -X PATCH https://api.saludya.com/v1/appointments/apt_8QrLm5xTw3 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled", "cancellation_reason": "Patient request"}'
Filter appointments by patient ID:
curl "https://api.saludya.com/v1/appointments?patient_id=pat_4XmNp9kLq7" \
  -H "Authorization: Bearer YOUR_API_KEY"
Register a new patient before creating their first appointment:
curl -X POST https://api.saludya.com/v1/patients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Garcia",
    "email": "maria.garcia@example.com",
    "phone": "+52-555-5678",
    "date_of_birth": "1985-05-15",
    "insurance_provider": "IMSS"
  }'

​
Rate Limits

The SaludYa API implements rate limiting to ensure system stability:
  • Free tier: 100 requests per minute
  • Pro tier: 1,000 requests per minute
  • Enterprise tier: Custom limits
Rate limit information is included in response headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709740800

​
Need Help?

GitHub

View the project repository

Architecture

Understand the system design