API Reference

All authenticated routes live under /v1 and use database-backed API keys with scoped permissions.

X-API-Key: <your-api-key>

When USE_AUTH=true and the api_keys table is empty on first boot, core bootstraps an admin key from the GREENLIGHT_API_KEY environment variable. Create replacement keys via POST /v1/keys/new and revoke the bootstrap key.

Path verbs

Scopes

Middleware checks any-of required scopes per route. The admin scope grants all permissions.

Presets (for POST /v1/keys/new):

• admin → ['admin']
• agent → channels, prompts, messages read+write (no settings/keys/status)
• readonly → all *:read scopes including status:read

Endpoints

Platforms: telegram, slack, teams, discord, gchat, whatsapp, messenger.

GET /v1/status

Deep health for operators and the Admin UI dashboard.

Response 200

{
  "status": "ok",
  "database": "ok",
  "channels_active": 2,
  "prompts_pending": 1,
  "prompts_answered_24h": 4,
  "platforms": {
    "telegram": 1,
    "slack": 1
  }
}

GET /v1/settings / PATCH /v1/settings

Data retention configuration. PATCH body uses the same fields as the GET response (except updated_at is ignored). Days must be 1–3650 when the corresponding toggle is enabled.

POST /v1/keys/new

Request body

Response 200

API key metadata plus key (plaintext, shown once).

POST /v1/prompts/new

Accepts application/json or multipart/form-data.

JSON body

Multipart form

Same fields as form parts. Send attachments as file. options may be a JSON string. Do not combine file and media_url.

Response 200

{
  "prompt_id": "#123",
  "channel_id": "my-telegram-prompts",
  "message_id": 456
}

GET /v1/prompts

Query

POST /v1/channels/new

See Channels for the full schema and Platforms for credentials.

Response 201

{ "status": "Channel ops-slack registered." }

GET /v1/channels

Query

PATCH /v1/channels/{id}

Path id is the channel slug (channel_id from create).

Update target_chat_id, credentials, and/or callback_url. Reactivates a deactivated channel. platform and channel_type cannot be changed.

Response 200

{ "status": "Channel ops-slack updated." }

GET /v1/prompts/{id}

Returns prompt state including answer, timestamps, and options. Encode # as %23.

GET /v1/messages

Query

Outbound messages include api_key_id when stored.

GET /v1/messages/{id}

Returns a single message record by UUID.

POST /v1/messages/send

Deliver plain chat text on a MESSAGE channel. When retention allows, returns the full stored message record (201). When zero retention is enabled, returns { "status": "sent", "stored": false, ... }.

Request body

Common errors