API Reference

Greenlight exposes an HTTP API on the core service (default port 8100).

Base URL

Environment	Example
Local Docker	`http://localhost:8100`
Production	`https://api.example.com` (`PUBLIC_WEBHOOK_URL`)

Auth summary

Surface	Header	When
`/v1/*`	`X-API-Key`	When `USE_AUTH=true`
Health / webhooks / OpenAPI	None	Public

API keys are stored in Postgres with scoped permissions. On first boot, if api_keys is empty and GREENLIGHT_API_KEY is set, core bootstraps a full-admin key.

Error shape

Most application errors return:


{ "detail": "Invalid or missing API key" }

Zod validation failures from @hono/zod-validator may return structured Zod issues with status 400.

Sections

API reference — /v1 routes, scopes, and payloads
Webhooks — inbound platform endpoints
OpenAPI — machine-readable spec

Interactive OpenAPI document (when enabled on core): GET /openapi.json (ENABLE_DOCS=true). A static copy ships with this docs site at /openapi.json.