Skip to main content

​
Base URL

All API requests are made to: 
http://localhost:8000
For production deployments, replace with your server’s domain.

​
Authentication

ClinicalPilot does not currently enforce authentication at the API layer. All endpoints are publicly accessible when the server is running.
In production environments, you should add authentication middleware or deploy behind a secure gateway.

​
API Key Configuration

ClinicalPilot requires an OpenAI or Groq API key to function. You can provide API keys in two ways:

​
1. Environment Variables (Persistent)

Add to your .env file: 
OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...

​
2. Runtime Configuration (Session Only)

Use the /api/set-api-key endpoint to set keys at runtime: 
curl -X POST http://localhost:8000/api/set-api-key \
  -H "Content-Type: application/json" \
  -d '{
    "openai_api_key": "sk-...",
    "groq_api_key": "gsk_..."
  }'
Runtime-configured keys are stored in memory only and will be lost when the server restarts.

​
Common Request Patterns

​
Content Type

All POST requests should include: 
Content-Type: application/json

​
Response Format

All responses are JSON-encoded. Successful responses return HTTP 200 with a JSON body. Errors return appropriate HTTP status codes (400, 500, 503) with error details: 
{
  "detail": "Error message here"
}

​
Health Check

Use the health endpoint to verify the server is running: 
curl http://localhost:8000/api/health
Response: 
{
  "status": "ok",
  "service": "clinicalpilot",
  "version": "1.0.0",
  "model": "gpt-4o",
  "local_llm": false
}

​
Configuration Status

Check which LLM providers are configured: 
curl http://localhost:8000/api/config-status
Response: 
{
  "has_openai_key": true,
  "has_groq_key": false,
  "use_local_llm": false,
  "active_provider": "openai",
  "openai_model": "gpt-4o",
  "groq_model": "llama-3.3-70b-versatile"
}

​
Rate Limits

ClinicalPilot does not enforce rate limits. However, you are subject to the rate limits of your chosen LLM provider (OpenAI, Groq, or Ollama).

​
Error Handling

Status CodeDescription
200Success
400Bad Request - Invalid input
500Internal Server Error - Processing failed
503Service Unavailable - No API key configured

​
Next Steps

Analyze Endpoint

Full multi-agent clinical analysis pipeline

Emergency Endpoint

Fast-path triage for emergency scenarios

Chat Endpoint

AI-powered clinical decision support chat

Upload Endpoints

Upload FHIR bundles or EHR documents

Build docs developers (and LLMs) love

Get started for freeTalk to us