Notifications

Compose and send broadcast notifications to platform users — in-app, and to any other channel your notification preferences fan out to. A notification is created as a draft, edited, and then sent; sent notifications become read-only delivery history.

Concept

Draft, edit, and send

create (draft) → update (title, body, recipients, actions) → send
             ↘ delete

A notification cannot be sent until it has at least one recipient subject and a non-empty body.

# Create a draft
curl -sf -X POST "https://api.falcata.io/api/v1/notifications" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New lesson published","body":"A new lesson is now available."}' \
  | jq '.data.id'

# Add recipients and a call-to-action
curl -sf -X PATCH "https://api.falcata.io/api/v1/notifications/$NOTIF_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientSubjects": ["sub_alice","sub_bob"],
    "actions": [{"label":"View","url":"https://example.com/lesson"}]
  }'

# Send
curl -sf -X PATCH "https://api.falcata.io/api/v1/notifications/$NOTIF_ID/send" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

Add rich content for a digest

content accepts {kind:"sdl", document} — a compact, static SDL document. Rich content is display-only; keep navigation in actions.

curl -sf -X PATCH "https://api.falcata.io/api/v1/notifications/$NOTIF_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "1 filed, 1 needs you",
    "content": {
      "kind": "sdl",
      "document": {
        "sdl": 1,
        "meta": {"title": "Mail triage digest"},
        "root": "summary",
        "nodes": {
          "summary": {"type": "Alert", "props": {
            "tone": "warning",
            "title": "Waiting on you",
            "description": "Parcel pickup deadline 13 August"
          }}
        }
      }
    }
  }'

Keep body non-empty and readable on its own — lists, toasts, and device notifications fall back to it when rich content can't render.

Find recipients

# Search by name or email (max 10 results)
curl -sf "https://api.falcata.io/api/v1/notifications/users/search?q=alice" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data[] | {subject, email, name}'

# Resolve known subjects to user records
curl -sf -X POST "https://api.falcata.io/api/v1/notifications/users/by-subjects" \
  -H "Authorization: Bearer $FURNACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subjects":["sub_alice","sub_bob"]}' | jq '.data[] | {subject, email, name}'

Manage drafts

# List everything, newest first
curl -sf "https://api.falcata.io/api/v1/notifications" \
  -H "Authorization: Bearer $FURNACE_TOKEN" | jq '.data[] | {id, title, status}'

# Delete an unsent draft
curl -sf -X DELETE "https://api.falcata.io/api/v1/notifications/$NOTIF_ID" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

Everything else — single-notification retrieval and status fields — in the full reference.