Your First API Call

Your First API Call

This guide walks you through making your first request to the DELPHOS API. By the end, you will have retrieved a list of patients and understood the standard response format.

Prerequisites

• A valid API key (see Authentication)
• curl, Python with httpx, or any HTTP client

---

1. Set your API key

   Store your key in an environment variable:

   export DELPHOS_API_KEY="dph_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

2. List patients

   curl

   curl -s "https://your-instance.delphos.app/v1/patients?limit=3" \
     -H "x-api-key: $DELPHOS_API_KEY" | python3 -m json.tool

   Python

   import httpx
   import os
   
   client = httpx.Client(
       base_url="https://your-instance.delphos.app/v1",
       headers={"x-api-key": os.environ["DELPHOS_API_KEY"]},
   )
   
   response = client.get("/patients", params={"limit": 3})
   response.raise_for_status()
   data = response.json()
   
   print(f"Total patients: {data['total']}")
   for patient in data["patients"]:
       print(f"  {patient['id']} — active: {patient['is_active']}")

3. Inspect the response

   {
     "patients": [
       {
         "id": "550e8400-e29b-41d4-a716-446655440000",
         "external_ids": {
           "ehr_id": "pat-12345"
         },
         "name_hash": "e3b0c44298fc1c14...",
         "birth_date": "1985-03-15",
         "gender": "female",
         "is_active": true,
         "created_at": "2026-01-24T10:30:00Z",
         "updated_at": "2026-01-24T10:30:00Z"
       }
     ],
     "total": 145,
     "limit": 3,
     "offset": 0
   }

---

Response Format

Every DELPHOS API response follows a consistent structure:

Collection Endpoints

Collection endpoints return paginated lists:

Field	Type	Description
{resource}	array	List of resource objects
total	integer	Total count across all pages
limit	integer	Page size used for this request
offset	integer	Number of items skipped

Single-Resource Endpoints

Single-resource endpoints return the object directly (no wrapper).

Error Responses

Errors follow a standard schema:

{
  "detail": "Human-readable error message"
}

Status Code	Meaning
400	Bad request — malformed JSON or invalid parameters
401	Authentication failed
403	Insufficient permissions
404	Resource not found
409	Conflict — duplicate or state violation
422	Validation error — check field constraints
500	Server error — contact support

Tip

All timestamps are in UTC using ISO 8601 format (2026-04-14T10:30:00Z). All identifiers are UUIDs (550e8400-e29b-41d4-a716-446655440000).

---

Filtering & Pagination

Most list endpoints support:

• limit — Number of results per page (default varies by endpoint, max 100)
• offset — Skip this many results before returning
• Field-specific filters — Vary by endpoint (e.g., is_active, status, date_from)

Some endpoints use cursor-based pagination instead of offset:

{
  "items": [...],
  "next_cursor": "eyJpZCI6ImExYjJjM2Q0In0=",
  "has_more": true
}

Pass the next_cursor value as the cursor query parameter to fetch the next page.

---

Rate Limits

DELPHOS applies rate limits per API key:

Tier	Requests/minute
Standard	300
Premium	1,000

When rate-limited, you receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

---

Next Steps

• Core Concepts — Understand the platform model
• Consultation Lifecycle — Start your first consultation
• Booking an Appointment — Schedule appointments