Core API Reference¶

All products share these endpoints from the haagsman_core library.

System Endpoints¶

Health Check¶

GET /health

Returns overall health status with component checks.

Response:

{
  "status": "healthy",
  "product": "haagsman-document-search",
  "version": "1.0.0",
  "uptime_seconds": 3600,
  "checks": {
    "vectorstore": "ok"
  }
}

Liveness Probe¶

GET /health/live

Simple alive check. Returns 200 if the process is running.

Readiness Probe¶

GET /health/ready

Returns 200 if the service is ready to accept traffic. Returns 503 if any dependency is down.

Prometheus Metrics¶

GET /metrics

Returns metrics in Prometheus exposition format.

Authentication¶

Headers¶

Header	Format	Description
`Authorization`	`Bearer <jwt_token>`	JWT access token
`X-API-Key`	`hai_<key>`	API key

At least one must be provided. API keys take precedence if both are present.

Common Error Responses¶

Status	Meaning
`400`	Bad request — invalid input, unsupported file type
`401`	Authentication required — missing or invalid credentials
`403`	Forbidden — insufficient permissions for this action
`404`	Not found — resource doesn't exist
`413`	Payload too large — file exceeds max upload size
`429`	Rate limited — too many requests
`502`	LLM service unavailable — provider error or timeout

Error response format:

{"detail": "Human-readable error message"}

Security Headers¶

Every response includes:

Header	Value
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`X-XSS-Protection`	`1; mode=block`
`Strict-Transport-Security`	`max-age=63072000; includeSubDomains`
`Cache-Control`	`no-store`
`Server`	`haagsman.ai`
`X-Request-ID`	Unique request identifier