Skip to content

10 — API Endpoints & Contracts

Design Principles

  • All routes under /api/v1/
  • Standard response envelope: { data, meta, errors }
  • Idempotency keys on all write operations (X-Idempotency-Key header)
  • Correlation IDs on every request (X-Correlation-ID header)
  • Tenant isolation via X-Tenant-ID header
  • Swagger UI at /docs (staging)

Core MVP Endpoints

Method Endpoint Description Auth Agent
POST /api/v1/patients Create patient Clerk —
GET /api/v1/patients/{id} Get patient Clerk + tenant —
PUT /api/v1/patients/{id} Update patient Clerk + tenant —
POST /api/v1/consent Grant/revoke consent Clerk —
GET /api/v1/patients/{id}/consent Get consent status Clerk + tenant —
POST /api/v1/patients/{id}/chat Unified conversation Clerk + tenant Orchestrator
POST /api/v1/patients/{id}/analyze-report Trigger clinical extraction Clerk + tenant Clinical Context
POST /api/v1/patients/{id}/match Execute matching Clerk + tenant Match Agent
GET /api/v1/patients/{id}/matches Get match results Clerk + tenant —
GET /api/v1/patients/{id}/fhir Get FHIR resources Clerk + tenant —
GET /api/v1/patients/{id}/fhir/{type} Get FHIR by type Clerk + tenant —
POST /api/v1/uploads/presign Get presigned upload URL Clerk —
POST /api/v1/uploads/confirm Confirm upload Clerk + tenant —
GET /api/v1/patients/{id}/documents List documents Clerk + tenant —
GET /api/v1/patients/{id}/events/stream SSE event stream Clerk + tenant —
GET /api/v1/providers List/search providers Public —
GET /api/v1/providers/{id} Provider detail + doctors Public —
GET /health Health check None —

Response Envelope

{
  "data": { ... },
  "meta": {
    "request_id": "correlation-id",
    "timestamp": "2026-04-06T10:30:00Z",
    "api_version": "v1"
  },
  "errors": []
}

Error Code Taxonomy

Prefix Domain Examples
AUTH_* Authentication AUTH_TOKEN_001, AUTH_RBAC_002
TENANT_* Tenancy TENANT_NOT_FOUND_001
INTAKE_* Patient intake INTAKE_VALIDATION_003
FHIR_* Medical records FHIR_RESOURCE_INVALID_005, FHIR_VALIDATION_001
MATCH_* Matching engine MATCH_NO_PROVIDERS_001, MATCH_STRATEGY_INVALID_001
AGENT_* LLM / agents AGENT_LLM_TIMEOUT_001, AGENT_EXTRACTION_FAILED_001
PROVIDER_* Provider data PROVIDER_NOT_FOUND_001
CONSENT_* GDPR / consent CONSENT_NOT_GRANTED_001
GRAPH_* Neo4j GRAPH_QUERY_FAILED_001
STORAGE_* File storage STORAGE_UPLOAD_FAILED_001
NOTIFY_* Notifications NOTIFY_DELIVERY_FAILED_001
SYS_* System / infra SYS_DB_CONNECTION_001