Authentication

All PearMedica API requests require authentication via API keys. This guide covers key management, rate limiting, and security best practices.

PearMedica issues two types of API keys, distinguished by their prefix:

Include your API key in the Authorization header of every request:

Authorization: Bearer sk_live_your_api_key_here

What Your Key Unlocks

Every API key gives you full access to the entire PearMedica platform. There are no endpoint-specific restrictions — your single key works across all endpoints.

Only POST /v1/assess and POST /v1/fhir/assess count toward your monthly assessment quota. All other endpoints are free and unlimited.

Key Management

Manage your API keys from the Dashboard → API Keys page. Available actions:

All API keys have a default rate limit of 100 requests per minute using a sliding window algorithm. Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709193600

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff to handle this gracefully.

Response Headers

Handling Rate Limits

async function fetchWithRetry(url, options, maxRetries = 3) {
  const baseDelayMs = 1000;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status !== 429) return res;

    // Use server-provided Retry-After directly when available;
    // only fall back to exponential backoff when absent or invalid.
    const retryAfterRaw = parseInt(res.headers.get('Retry-After') || '', 10);
    const backoff = Number.isFinite(retryAfterRaw) && retryAfterRaw > 0
      ? retryAfterRaw * 1000
      : baseDelayMs * Math.pow(2, attempt);
    await new Promise(r => setTimeout(r, backoff));
  }
  throw new Error('Rate limit exceeded after max retries');
}

For billable POST endpoints, include an Idempotency-Key header to prevent duplicate processing on network retries. This is critical in Africa's unreliable network environment.

const response = await fetch('https://api.pearmedica.com/v1/assess', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', // UUID
  },
  body: JSON.stringify({ patient, evidence }),
});
// If you retry with the same Idempotency-Key, you'll get
// the cached response — no duplicate assessment or billing.