Skip to main content

Notifications

In-app notifications for account-level events — low credit balance, a successful top-up, a subscription change. There's no push/email delivery through this API; it's a read/mark-read surface for whatever the platform has already generated for your org.

Listing​

curl https://convostack.ai/api/notifications \
  -H "Authorization: Bearer cak_live_..."
{
  "notifications": [
    {
      "id": "b681b1c8-a9a4-40fc-a1ca-dc457ac43fc1",
      "organizationPartyId": "0b0a069b-74c6-4794-b195-f622edc418ba",
      "type": "payment_success",
      "title": "Credits purchased",
      "message": "1,000 credits have been added to your account.",
      "isRead": true,
      "metadata": { "amount": 1000, "sessionId": "cs_test_..." },
      "createdAt": "2026-07-16T06:09:16.979Z"
    }
  ],
  "unreadCount": 0
}

Returns your org's most recent notifications (bounded, newest first) plus an unreadCount for a badge. metadata is a free-form, type-specific payload — e.g. low_credit includes { balance, threshold }.

Marking as read​

# One notification
curl -X POST https://convostack.ai/api/notifications/{id}/read \
  -H "Authorization: Bearer cak_live_..."

# Everything at once
curl -X POST https://convostack.ai/api/notifications/read-all \
  -H "Authorization: Bearer cak_live_..."

Both return { "ok": true }. A caller with no resolved org context gets an empty list / { "ok": false } rather than an error — there's nothing to read or mark for an account not scoped to an organization yet.