API Reference — Lantern

Lantern is composed of independent Cloud Run services, each exposing a versioned HTTP API. Every service ships its own OpenAPI 3.0 spec at /openapi.json; the admin portal renders all of them in-house under API Reference.

This document is a map: where to find the live docs, how to use the renderer, what service to look at for which feature, and the cross-cutting conventions every service follows.

Looking for actual endpoint definitions, request/response schemas, or example payloads? Don't read this file — open the admin portal and pick a service. The OpenAPI specs are the source of truth; this page exists only for orientation.

---

Where to view the live API docs

Where	URL	Audience
Admin portal (dev)	https://admin.dev.ourlantern.app → API Reference	Internal — auto-fills your Firebase token
Admin portal (local)	http://localhost:3001 → API Reference	Engineers running the admin app locally
Raw spec per service	https://<service>-…run.app/openapi.json	Tooling: Postman, Insomnia, codegen
Source of spec	services/api/<service>/openapi.json	Editing — checked into the repo

The renderer is the @lantern/api-docs-renderer workspace package. It is the only sanctioned way to render Lantern API docs — there is no Scalar, Swagger UI, Redoc, or hosted alternative anywhere in the codebase.

---

How to use the API Reference page

Every service page in the admin portal gives you the same controls:

1. Server picker (top of the page) — choose the environment you want examples to target. Auto-defaults to the running service URL when present, otherwise the dev Cloud Run URL.
2. Sidebar — endpoints grouped by tag, plus a Schemas section listing every component definition from the spec. Click any schema to jump to its full type breakdown (nested objects, enums, required fields, examples).
3. Operation view — for each endpoint:
   • Summary, description, security (which auth method), parameters, request body, every response shape
   • Code Samples tab — copy-paste ready curl, fetch, and Node snippets generated from the spec
   • Try It tab — fire the request directly from the browser. Auth tokens are pre-filled from your admin session; request bodies auto-fill from the schema's example values so you can edit and send in two clicks
4. Schemas section (sidebar) — the canonical place to see component definitions (#/components/schemas/...). Use this when you're building a client and want to know the exact shape of a Lantern, Wave, Offer, etc.

Bug or missing detail in a doc?

Edit the spec in services/api/<service>/openapi.json, open a PR. The renderer picks up changes automatically — no separate doc build.

---

Service inventory

Source of truth: packages/shared/services/index.js (API_SERVICES).

Service	Slug	Purpose	Local port
Analytics API	analytics-api	Server-side analytics, merchant dashboards, platform metrics	8082
Assistant API	assistant-api	AI chat assistant for the admin portal	8086
Auth API	auth-api	Phone+PIN tokens, admin auth, roles, moderation	8084
Docs API	docs-api	Markdown document management + GitHub integration	8081
Lanterns API	lanterns-api	Lantern presence lifecycle (light, extinguish, schedule, bonfire)	8083
Merchants API	merchants-api	Merchant offer CRUD, campaigns, merchant-scoped resources	8085
Venue API	venue-api	OSM import, enrichment, venue management	8080

Adding a new service? See CLAUDE.md rule #8 — register it here, ship openapi.json, no doc UI.

---

Cross-cutting conventions

These rules apply to every service. Per-endpoint detail lives in the OpenAPI specs.

Authentication

• User & merchant requests: Authorization: Bearer <Firebase ID token> — verified by verifyFirebaseToken middleware
• Admin endpoints: Firebase ID token + admin custom claim (or stronger via requireAdmin)
• Public endpoints: marked security: [] in the spec (e.g. /health, /openapi.json)

Errors

All services emit a uniform shape via the shared errorHandler middleware:

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": { … } } }

Standard HTTP status meanings: 400 invalid payload · 401 missing/expired token · 403 insufficient role · 404 not found · 409 conflict · 429 rate-limited · 5xx server error.

Rate limits

Defaults are defined per service via userRateLimit middleware. Sensitive endpoints (writes, costly aggregations, AI calls) are individually tightened. The OpenAPI description of each endpoint notes any non-default limit.

CORS

All services share ALLOWED_ORIGINS from packages/shared/services/index.js. Admin-only services use the ADMIN_ORIGINS subset.

---

Related docs

• packages/api-docs-renderer — the renderer package itself
• docs/engineering/architecture/api/VENUES.md — Venue API deep-dive (auth, OSM pipeline, geo-fencing)
• docs/engineering/analytics/analytics-infrastructure.md — Analytics API consumers and event taxonomy