API Reference

Endpoints, middleware, application bootstrap, and code map. For architecture diagrams, see Architecture. For design rationale, see Design Decisions.

API Surface

Classification

Request (POST /api/v1/classify):

{
  "message": "I am experiencing side effects from my medication",
  "channel": "chat",
  "metadata": {}
}

Response:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00Z",
  "category": "safety_compliance",
  "confidence": 0.92,
  "decision_path": "Message reports medication side effects - safety compliance",
  "next_step": {
    "action": "pharmacist_review",
    "description": "Flagged for pharmacist review due to reported adverse reaction",
    "priority": "high",
    "requires_human_review": true,
    "external_system": "compliance_system"
  },
  "processing_time_ms": 312.5
}

Health and Readiness

The health endpoint always returns 200 if the process is alive. The readiness endpoint checks whether the OpenAI API key is configured and returns degraded if critical dependencies are not available.

Documentation

Middleware Stack

Middleware is applied in order. The outermost middleware executes first:

Application Bootstrap

The application is assembled through a factory pattern (app/factory.py):

1. Load settings from environment variables via pydantic-settings.
2. Configure logging (human-readable in development, structured JSON in production).
3. Create the FastAPI app with middleware, exception handlers, and route registration.
4. On startup (lifespan event): load prompt templates from YAML files into the prompt registry.

The factory pattern ensures the application can be created identically in production, tests, and local development, with only environment variables differing.

Code Map