Lumen API documentation

Endpoints reference

Chat completions

POST /v1/chat/completions — OpenAI-compatible. Routes autonomously unless you pass a specific model.

Request body:

  • messages (required): OpenAI-format message list
  • model (optional): "auto" (default) or a specific tier name (nano, small, mid, high) or model id
  • quality_floor (optional, default 0.75): minimum quality threshold the chosen tier must clear
  • max_cost_usd (optional): hard ceiling on estimated cost for this request
  • brand_pref (optional, Pro+): "anthropic" to prefer Claude tiers
  • temperature, tools, tool_choice, response_format, stream — passthrough

Response: standard OpenAI shape PLUS a lumen object:

{
  "choices": [...],
  "usage": {...},
  "lumen": {
    "tier": "small",
    "model": "gpt-4o-mini",
    "difficulty_score": 0.42,
    "audit_hash": "...",
    "cost_per_1k": 0.003,
    "cache_hit": false,
    "elapsed_sec": 0.84
  }
}

Models

GET /v1/models — list available tiers + costs + quality floors + context windows. Public.

Plans

GET /v1/plans — public plan catalog (Free / Starter / Pro / Scale / Enterprise) with limits and prices.

Usage

GET /v1/usage?days=30 — your own usage rollup. Auth required.

Audit verification

GET /v1/audit/{hash} — fetch the audit entry for any hash returned in a lumen.audit_hash. Returns the chain context (previous hash + payload) for verification.

Feedback

POST /v1/feedback — score a previous request to improve future routing.

{ "audit_hash": "...", "rating": 5, "notes": "perfect" }

Billing

  • POST /v1/me/checkout — create Stripe checkout session for plan upgrade (session-auth)
  • POST /v1/me/portal — create Stripe billing portal session (session-auth)
  • POST /v1/checkout/session — public version (admin-key bypass)

Self-service (session-auth)

  • GET /v1/me — current account
  • POST /v1/me/keys — issue API key
  • DELETE /v1/me/keys/{id} — revoke own key
  • GET /v1/me/usage — usage report

Health

GET /healthz — service heartbeat (version, tier counts, cache/db/stripe status).