Events

Citadel Events stores short notices from apps (a deploy finished, a sale, a site down) and streams them to readers such as Pager. The API implements the Ambient protocol, version ambient/1.

Base URL: https://citadel.albastov.com/v1/events. The owner creates sources and mints keys in the admin panel.

Quick start

Publish one event with a publish key:

curl https://citadel.albastov.com/v1/events \
  -H "Authorization: Bearer $CITADEL_EVENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"backup.done","text":"Backup **done** · 412 MB","idempotency_key":"backup-2026-10-31"}'

{"id":"evt_01JBX7Q2W8V5K3M9N4P6R2T8YC","cursor":"1734","source":"backups","source_name":"Backups","source_color":null,"source_icon":null,"type":"backup.done","severity":"info","text":"Backup **done** · 412 MB","detail":null,"subject":null,"url":null,"occurred_at":"2026-10-31T10:02:03Z","received_at":"2026-10-31T10:02:03Z","display":null,"data":null,"dismissed_at":null}

Read the newest events with a read key:

curl "https://citadel.albastov.com/v1/events?limit=5" -H "Authorization: Bearer $CITADEL_EVENTS_READ_KEY"

The examples are not run by the example checker: the checker holds an API key, not an events key.

Reference

Ways in and out

Every event enters one store and reaches every stream whose grant includes its source. Publishing and webhooks apply the same field validation and the same idempotency_key dedupe; webhooks also drop a repeated body within 10 minutes (Duplicates).

Events

Citadel adds id, cursor, source, source_name, source_color, source_icon, received_at and, for a reader, dismissed_at.

Lifetime and sticky

display.lifetime sets how long a reader shows an event: whole seconds 1..86400, or "sticky". A sticky event stays on screen until a reader dismisses it. Use "sticky" for states that last until someone acts: a site down, a failed deploy. Without lifetime, the reader's default applies (Pager: 60 s). Dismissal is per read key: one reader dismissing an event leaves the event open for every other reader.

Citadel's own sources

The built-in webhooks are ordinary webhooks with seeded mappings; see Built-in webhooks. The uptime checker, citadel, generations, members and crashes are written by Citadel itself, not received as webhooks, and take no webhook and no publish key.

Do not publish deploy, CI or sale events that GitHub, Coolify or Stripe already report.

Pager

Pager is the macOS reader for ambient/1 hubs. Pager connects with a read key, calls GET /v1/events/info, reads open sticky events with GET /v1/events?sticky=open, and holds GET /v1/events/stream open. Pager draws each event as one line beside its source's name, icon and color, applies display hints, and dismisses sticky events with POST /v1/events/{id}/dismiss. See Receiving events.

Agent guide

GET /v1/events/docs returns this section (the four Events pages) as one text/markdown document, without authentication. A publish key's brief links to it.

Limits

Changelog

• 2026-10-31: Every webhook, GitHub, Coolify, Stripe, HOSTKEY and remote uptime included, runs through one receiver with a mapping stored as data. Signatures can be required per source; refused requests are counted. New webhooks start pending and publish after review. A delivery without an idempotency key or delivery header dedupes on its body for 10 minutes.
• 2026-10-30: Webhooks for any source: POST /v1/events/hooks/in/{token} with a mapping.
• 2026-10-15: ambient/1: publish, batch, list, stream, dismiss, sources, info.