Chimely
Api

Create direct notifications (1–100 recipients, fan-out on write)

Creates one notification per recipient in a single transaction together with counter bumps and the outbox job. The `idempotency_key` covers the **whole request**: a retry never partially re-runs the batch. `deliver_at` schedules delivery (max 13 months out): the notification is durable immediately but invisible to the subscriber until then; counters and real-time hints fire at `deliver_at`. Recipients that don't exist yet are lazily created as subscribers. Need more than 100 recipients? That's a broadcast.

POST
/v1/notifications

Creates one notification per recipient in a single transaction together with counter bumps and the outbox job. The idempotency_key covers the whole request: a retry never partially re-runs the batch.

deliver_at schedules delivery (max 13 months out): the notification is durable immediately but invisible to the subscriber until then; counters and real-time hints fire at deliver_at.

Recipients that don't exist yet are lazily created as subscribers. Need more than 100 recipients? That's a broadcast.

Authorization

ApiKeyBearer
AuthorizationBearer <token>

Environment-scoped management API key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Exactly one of subscriber_id / subscriber_ids is required.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/notifications" \  -H "Content-Type: application/json" \  -d '{    "category": "payment.failed"  }'
{
  "idempotency_key": "string",
  "notifications": [
    {
      "id": "notif_01h455vb4pex5vsknk084sn02q",
      "subscriber_id": "string"
    }
  ]
}
{
  "idempotency_key": "string",
  "notifications": [
    {
      "id": "notif_01h455vb4pex5vsknk084sn02q",
      "subscriber_id": "string"
    }
  ]
}
{
  "error": {
    "code": "invalid_request",
    "message": "string"
  }
}
{
  "error": {
    "code": "invalid_request",
    "message": "string"
  }
}
{
  "error": {
    "code": "invalid_request",
    "message": "string"
  }
}

Create a broadcast (one row, fan-out on read) POST

One row per announcement targeting the whole environment, regardless of subscriber count. Visible to each subscriber only if the broadcast is created at or after that subscriber's `created_at`.

Unread and unseen counts GET

`unread` drives list styling; `unseen` drives the bell badge (cleared by mark-all-seen when the inbox opens). Served from maintained counters (Redis cache, Postgres authoritative) — O(1), not O(rows).