API Overview

Welcome to the Picos Health API documentation. This guide covers all accessible Picos Health collections and globals with examples, best practices, and advanced patterns.

Documentation Structure

• Full API Reference - Complete endpoint documentation with all collections and globals
• Collections Examples - Practical JavaScript examples organized by collection
• Globals & Advanced Patterns - System configuration, caching, rate limiting, and optimization

Quick Start

1. Authentication

All API requests require a JWT token:

const token = "YOUR_JWT_TOKEN"; // Get from login endpoint

const response = await fetch('https://api.picoshealth.com/v1/users', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

2. Base URL

Development: https://dev-api.picoshealth.com/v1
Production: https://api.picoshealth.com/v1

3. Common Patterns

Get all documents:

GET /users?limit=50&page=1&sort=-createdAt

Filter by field:

GET /products?where={"status":{"equals":"published"}}

Create document:

POST /users
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "role": "patient"
}

Update document:

PATCH /users/{id}
Content-Type: application/json

{
  "role": "provider"
}

Delete document:

DELETE /users/{id}

Collections Overview

Core Entities

Financial

Care Management

Common Use Cases

User Management

Create a new patient:

const createPatient = async (token) => {
  const response = await fetch('https://api.picoshealth.com/v1/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'patient@example.com',
      password: 'SecurePass123!',
      firstName: 'John',
      lastName: 'Doe',
      role: 'patient',
    }),
  });
  return response.json();
};

Query Reference

Filtering

# Exact match
GET /users?where={"role":{"equals":"admin"}}

# In list
GET /users?where={"role":{"in":["admin","provider"]}}

# Text contains
GET /products?where={"title":{"contains":"socks"}}

Pagination

# Page 1 with 50 items
GET /users?limit=50&page=1

Sorting

# Sort ascending
GET /products?sort=price

# Sort descending
GET /orders?sort=-createdAt

Advanced Features

Caching

Implement caching for better performance with TTL (time-to-live).

Rate Limiting

Avoid rate limit errors (100 requests/minute) with proper queuing.

Response Format

List Response

{
  "docs": [
    { "id": "...", "email": "...", ... }
  ],
  "totalDocs": 100,
  "limit": 10,
  "page": 1,
  "totalPages": 10
}

Single Document

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "createdAt": "2024-01-20T10:30:00Z"
}

Security

Best Practices

1. Never commit tokens - Use environment variables
2. Always use HTTPS - In production
3. Rotate tokens regularly - Refresh every hour
4. Validate input - Check before sending
5. Handle errors safely - Don't leak sensitive info

Troubleshooting

Common Issues

Last Updated: June 17, 2026
API Version: 1.0.2