API Overview - SaludYa API

This is the API specification for SaludYa. The implementation is currently under development.

Introduction

The SaludYa API is a RESTful API specification designed for comprehensive medical appointment management. Built with a layered architecture, it provides robust endpoints for managing appointments, patients, doctors, and schedules.

Base URL

All API endpoints are relative to the base URL:

https://api.saludya.com/v1

Versioning

The API uses URL-based versioning. The current version is v1, which is included in the base URL path. Breaking changes will result in a new version (e.g., v2).

Authentication

All API requests require authentication using Bearer tokens in the Authorization header:

Authorization: Bearer your_access_token_here

Standard Headers

Required Headers

Header	Value	Description
`Authorization`	`Bearer {token}`	Authentication token
`Content-Type`	`application/json`	Request payload format

Optional Headers

Header	Value	Description
`Accept-Language`	`es`, `en`	Preferred response language
`X-Request-ID`	UUID	Unique identifier for request tracing

Common Request Parameters

Query Parameters

Many endpoints support these common query parameters:

Parameter	Type	Description
`page`	integer	Page number for pagination (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`sort`	string	Sort field (prefix with `-` for descending)
`filter`	string	Filter expression for resource filtering

Example Paginated Request

GET /appointments?page=2&limit=50&sort=-createdAt

Response Format

All API responses follow a consistent JSON structure.

Successful Response

{
  "success": true,
  "data": {
    "id": "apt_1234567890",
    "type": "appointment",
    "attributes": {
      "patientId": "pat_abc123",
      "doctorId": "doc_xyz789",
      "scheduledAt": "2026-03-15T10:00:00Z",
      "status": "confirmed"
    }
  },
  "meta": {
    "timestamp": "2026-03-06T12:00:00Z",
    "requestId": "req_unique_id"
  }
}

Paginated Response

{
  "success": true,
  "data": [
    {
      "id": "apt_001",
      "type": "appointment",
      "attributes": { }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    },
    "timestamp": "2026-03-06T12:00:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "scheduledAt",
        "message": "Date must be in the future"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-03-06T12:00:00Z",
    "requestId": "req_unique_id"
  }
}

HTTP Status Codes

Status Code	Description
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Request succeeded with no response body
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Authenticated but not authorized
`404 Not Found`	Resource not found
`409 Conflict`	Request conflicts with current state
`422 Unprocessable Entity`	Validation error
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error
`503 Service Unavailable`	Service temporarily unavailable

Error Codes

Common error codes returned by the API:

Code	Description
`AUTHENTICATION_REQUIRED`	Missing authentication token
`INVALID_TOKEN`	Invalid or expired token
`VALIDATION_ERROR`	Request validation failed
`RESOURCE_NOT_FOUND`	Requested resource does not exist
`DUPLICATE_RESOURCE`	Resource already exists
`SCHEDULE_CONFLICT`	Appointment time conflicts with existing booking
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Internal server error

Rate Limiting

The API implements rate limiting to ensure fair usage:

Default limit: 1000 requests per hour per API key
Burst limit: 100 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1709730000

API Resources

Explore the different resource groups available in the SaludYa API:

Appointments

Create, retrieve, update, and cancel medical appointments

Patients

Manage patient profiles and medical information

Doctors

Access doctor profiles, specialties, and availability

Schedules

Manage doctor schedules and available time slots

Example: Complete Request Flow

Here’s a complete example of creating an appointment:

Request

curl -X POST https://api.saludya.com/v1/appointments \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "patientId": "pat_abc123",
    "doctorId": "doc_xyz789",
    "scheduledAt": "2026-03-15T10:00:00Z",
    "reason": "Annual checkup",
    "notes": "Patient prefers morning appointments"
  }'

Response

{
  "success": true,
  "data": {
    "id": "apt_1234567890",
    "type": "appointment",
    "attributes": {
      "patientId": "pat_abc123",
      "doctorId": "doc_xyz789",
      "scheduledAt": "2026-03-15T10:00:00Z",
      "status": "confirmed",
      "reason": "Annual checkup",
      "notes": "Patient prefers morning appointments",
      "createdAt": "2026-03-06T12:00:00Z",
      "updatedAt": "2026-03-06T12:00:00Z"
    },
    "relationships": {
      "patient": {
        "data": { "type": "patient", "id": "pat_abc123" }
      },
      "doctor": {
        "data": { "type": "doctor", "id": "doc_xyz789" }
      }
    }
  },
  "meta": {
    "timestamp": "2026-03-06T12:00:00Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Best Practices

Use Request IDs: Include X-Request-ID header for debugging and tracking
Handle Rate Limits: Implement exponential backoff when rate limited
Validate Before Sending: Validate data client-side to reduce errors
Use Pagination: Always use pagination for list endpoints
Cache Responses: Cache GET responses where appropriate
Handle Errors Gracefully: Implement proper error handling for all error codes
Use HTTPS: Always use HTTPS for secure communication
Keep Tokens Secure: Never expose API tokens in client-side code

SDK and Libraries

Official SDKs are available for popular programming languages:

JavaScript/TypeScript: npm install @saludya/api-client
Python: pip install saludya-api
Java: maven: com.saludya:api-client
PHP: composer require saludya/api-client

Support

For API support and questions:

Documentation: https://docs.saludya.com
API Status: https://status.saludya.com
Support Email: api-support@saludya.com
Developer Portal: https://developers.saludya.com

Overview

Appointments

Patients

Doctors

Schedules

Documentation Index

​Introduction

​Base URL

​Versioning

​Authentication

​Standard Headers

​Required Headers

​Optional Headers

​Common Request Parameters

​Query Parameters

​Example Paginated Request

​Response Format

​Successful Response

​Paginated Response

​Error Response

​HTTP Status Codes

​Error Codes

​Rate Limiting

​API Resources

Appointments

Patients

Doctors

Schedules

​Example: Complete Request Flow

​Request

​Response

​Best Practices

​SDK and Libraries

​Support

Build docs developers (and LLMs) love

Introduction

Base URL

Versioning

Authentication

Standard Headers

Required Headers

Optional Headers

Common Request Parameters

Query Parameters

Example Paginated Request

Response Format

Successful Response

Paginated Response

Error Response

HTTP Status Codes

Error Codes

Rate Limiting

API Resources

Example: Complete Request Flow

Request

Response

Best Practices

SDK and Libraries

Support