REST API

The HTTP API the backend exposes. For the auto-generated reference of the qfa Python package, see Python API reference instead.

The live, always-current OpenAPI reference is served by FastAPI itself:

• Swagger UI — GET /docs on a running instance

• OpenAPI JSON — GET /openapi.json on a running instance

For local dev, that’s http://localhost:8000/docs.

Quick reference

All endpoints except GET /v1/health require Authorization: Bearer <key>.

Method	Path	Purpose
POST	/v1/analyze	Free-text analysis of submitted feedback records
POST	/v1/summarize	Per-record summaries with quality scores
POST	/v1/summarize-aggregate	Single aggregate summary with judge score
POST	/v1/assign_codes	Hierarchical code assignment
GET	/v1/usage	Aggregate stats for the caller’s tenant
GET	/v1/usage/all	Cross-tenant stats (requires is_superuser=true)
GET	/v1/health	Liveness probe; no auth

curl examples

A minimal analyze call:

curl -X POST http://localhost:8000/v1/analyze \
  -H "Authorization: Bearer $LOCAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback_records": [
      {"id": "r-1", "text": "The coordination was good but shelter access was difficult."}
    ],
    "prompt": "Identify the top themes."
  }'

Error envelope

Every error response shares this shape:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "req_…",
    "fields": [
      {"field": "feedback_records[0].text", "issue": "..."}
    ]
  }
}

fields only appears on 422. request_id is always present and matches the X-Request-ID response header. See Cross-cutting concerns § Error → HTTP mapping for the full mapping.

Breaking changes

API field names changed in 0.14.0 (the ubiquitous-language migration). See the migration guide for 0.14.0.