API reference

Lucairn gateway API

Generated from the canonical OpenAPI spec. The same spec the gateway tests are wired against.

Most-used endpoints

Public scan + verify

  • POST/api/v1/scan

    PII scan only, no LLM call. Free, rate-limited 1200/hr global.

  • GET/api/v1/veil/certificate/{id}/summary

    Public HTML summary of a Lucairn Certificate. No auth.

  • GET/.well-known/veil-keys.json

    Witness Ed25519 public keys for offline verification.

Authenticated proxy (Bearer lcr_live_*)

  • POST/v1/messages

    Anthropic SDK shape. Drop-in for the Anthropic SDK base_url.

  • POST/v1/chat/completions

    OpenAI SDK shape. Drop-in for the OpenAI SDK base_url.

  • POST/api/v1/proxy/messages

    Lucairn-native shape. Multi-provider routing per request.

  • POST/api/v1/mcp/messages

    MCP-stdio gateway. Used by @lucairn/mcp-server.

Account + audit

  • POST/api/v1/register

    Mint a new lcr_live_* API key. Returns the key once.

  • GET/api/v1/usage

    Per-month token + request counts for your key.

  • GET/api/v1/account/audit

    Audit-event query for the authenticated key (any tier). Filters by request_id, day, etc.

  • GET/api/v1/veil/certificate/{id}

    Full JSON certificate (Pro and Enterprise). Free-tier callers can use the auth-less /public-summary suffix instead. Includes signable + signature.

Authentication

Every authenticated endpoint expects two headers: Authorization: Bearer lcr_live_* (your Lucairn key, mints from the dashboard) and X-Upstream-Key: sk-* (your upstream LLM provider key — Anthropic, OpenAI, Mistral, etc.). The free tier is BYOK only; Pro and Enterprise can use a shared upstream pool.

Error shape

All gateway errors return JSON with this shape:

{
  "error": "scanner_unavailable",
  "message": "Sanitizer is unreachable; failing closed.",
  "request_id": "req_01HABC..."
}

Full reference

The Redoc viewer below is rendered against the canonical openapi.yaml shipped with the website. It includes every endpoint, every error code, every example. Raw OpenAPI YAML.

Related

Want to see this in action?

Book a working session — we'll walk through your use case together.

Contact us