API Explorer

API Explorer

DELPHOS provides interactive API documentation powered by OpenAPI/Swagger. You can browse all available endpoints, view request/response schemas, and test API calls directly from your browser.

Accessing the API Explorer

Live Swagger UI

The interactive API explorer is available at your DELPHOS instance:

https://your-instance.delphos.app/docs

ReDoc View

For a clean, read-only browsing experience, use the ReDoc interface:

https://your-instance.delphos.app/redoc

Tip

The Swagger UI at /docs allows you to make live API calls against your instance. The ReDoc view at /redoc provides a structured reading experience that is better suited for browsing schemas and endpoint details.

Caution

In production environments, the /docs and /redoc endpoints may be restricted to authenticated sessions or internal networks. Check with your DELPHOS administrator if these URLs are not accessible.

Authentication

All API requests require authentication via the x-api-key header. See the Authentication guide for full details on obtaining and managing API keys.

1. Click the Authorize button at the top of the Swagger UI page.
2. Enter your API key in the x-api-key field.
3. Click Authorize to save.
4. All subsequent requests made through the UI will include your API key automatically.

curl

curl -H "x-api-key: YOUR_API_KEY" \
  https://your-instance.delphos.app/v1/health

Python

import httpx

client = httpx.Client(
    base_url="https://your-instance.delphos.app/v1",
    headers={"x-api-key": "YOUR_API_KEY"},
)

response = client.get("/health")
print(response.json())

JavaScript

const response = await fetch(
  "https://your-instance.delphos.app/v1/health",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);

const data = await response.json();
console.log(data);

API Domains

The DELPHOS API is organized into the following domains:

Domain	Base Path	Description
Patients	/v1/patients	Patient registration, search, and clinical records
Consultations	/v1/consultation	Consultation sessions, SOAP notes, progressive streaming
Prescriptions	/v1/prescriptions	Prescription creation, management, and streaming extraction
Scheduling	/v1/scheduling	Appointment booking, calendar management, and availability
Doctors	/v1/doctors	Doctor registration and profile management
Chat	/v1/patients/{id}/chat	Patient-context clinical chat
Drug Interactions	/v1/drug-interactions	Drug safety and interaction checks
Health	/v1/health	Service health check

OpenAPI Specification

The raw OpenAPI JSON specification is available at:

https://your-instance.delphos.app/openapi.json

You can use this specification to generate client libraries, import into Postman, or integrate with any OpenAPI-compatible tooling.

Downloading the Spec

curl https://your-instance.delphos.app/openapi.json -o delphos-openapi.json

Importing into Postman

1. Open Postman and navigate to File > Import.
2. Select the downloaded delphos-openapi.json file.
3. Postman will create a collection with all DELPHOS endpoints.
4. Set the x-api-key variable in your Postman environment.

Key Endpoints to Explore

Streaming Endpoints (SSE)

These endpoints return Server-Sent Events for real-time updates. Set the Accept: text/event-stream header when calling them.

Endpoint	Description
POST /v1/consultation/progressive-soap/stream	Real-time SOAP note generation with progressive updates
POST /v1/prescriptions/stream	Streaming prescription extraction with safety gate validation

Note

For detailed usage of streaming endpoints, see the Streaming Prescription and SOAP Streaming guides.

CRUD Endpoints

Standard REST endpoints for resource management:

Endpoint	Description
GET /v1/patients	List and search patients
POST /v1/patients	Register a new patient
GET /v1/patients/{id}	Retrieve a patient record
GET /v1/scheduling/availability	Query available appointment slots
POST /v1/scheduling/appointments	Book an appointment
GET /v1/doctors	List registered doctors

Rate Limits and Best Practices

Caution

Respect rate limits to avoid 429 Too Many Requests responses. The API returns Retry-After headers when limits are reached.

• Always include x-api-key in every request — unauthenticated calls are rejected with 401.
• Use Accept: text/event-stream for SSE endpoints — the server will not stream without this header.
• Implement retry with exponential backoff for 5xx errors — transient failures resolve quickly with retries.
• Cache the previous_soap_hash returned by SOAP streaming — sending it on subsequent calls avoids redundant reprocessing.
• Validate against the OpenAPI spec — use the downloaded spec to validate request payloads before sending them.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "detail": "Description of what went wrong"
}

Status	Meaning
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Valid key, insufficient permissions
404 Not Found	Resource does not exist
422 Unprocessable Entity	Validation error on request payload
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Unexpected server error

---

Next Steps

• Authentication & API Keys — Set up your API credentials
• Your First API Call — Make your first request
• Booking an Appointment — Try the scheduling API
• Creating a Prescription — Explore prescription endpoints