Events

Events stores one-line notices from apps (a deploy finished, a sale, a site down) per source and streams them to readers: apps that list and stream events with a read key. Apps publish with a publish key or through a webhook URL.

Quick example

Publish one event. The key in ALBASTAR_EVENTS_KEY decides the source. Python and JavaScript versions of the same request: Publish an event.

curl https://api.albastov.com/v1/events \
  -H "Authorization: Bearer $ALBASTAR_EVENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "deploy.failed",
    "severity": "error",
    "text": "Deploy **failed** `9f3c2e1`",
    "subject": "web"
  }'

The stored event, with the fields the API adds:

{
  "id": "evt_01M6GDQMFEV5K3M9N4P6R2T8YC",
  "cursor": "1734",
  "source": "vercel",
  "source_name": "Vercel",
  "source_color": "#000000",
  "source_icon": "vercel",
  "type": "deploy.failed",
  "severity": "error",
  "text": "Deploy **failed** `9f3c2e1`",
  "detail": null,
  "subject": "web",
  "url": null,
  "occurred_at": "2026-11-03T10:02:03Z",
  "received_at": "2026-11-03T10:02:03Z",
  "display": null,
  "data": null,
  "dismissed_at": null
}

What you can build

Key concepts

• Source: A named stream of events, such as vercel or stripe, with a slug [a-z0-9-]{2,48}, a name, an icon and a colour.
• Event: One notice in one source: a type, a severity and one line of text.
• Reader: An app that lists or streams events with a read key, such as a dashboard or a desktop widget.
• Publish key: An abk_ key with the events:publish scope, bound to one source. POST /v1/events and POST /v1/events/batch publish into that source only.
• Read key: An abk_ key with the events:read scope, granted every source or a list of sources. Dismissals belong to the key.
• Webhook URL: https://api.albastov.com/v1/events/hooks/in/{token}, which turns another app's HTTP requests into events of one source.
• Issuing: Albastar Corp. creates sources and issues publish keys, read keys and webhook URLs. An account key without an events scope fails with 403 scope_missing.

Next steps