Notifications API
Found this helpful? Share it:
Found this helpful? Share it:
The Notifications API notifies workspace members from any script, CI
job, or external tool, and reads or manages the caller's own inbox.
Everything lives under /api/v1/notifications and needs a
key with the notifications scope 🔔
POST /api/v1/notifications. Required: workspace_id, title(1 to 120 characters), message(1 to 500), and either target(one
of all_members, admins, owner)
or recipient_ids(up to 1000). target and recipient_ids are mutually exclusive.
curl https://idapt.app/api/v1/notifications \
-H "Authorization: Bearer uk_..." \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "WORKSPACE_ID",
"target": "all_members",
"title": "Build passed",
"message": "Deploy to staging succeeded.",
"channels": ["in_app", "web_push"],
"deep_link": { "kind": "chat", "chat_id": "CHAT_ID" },
"dedup_key": "deploy-1421"
}'The response is { recipient_count, deduped, deep_link }. When you
pass a deep link, the resolved form comes back as { kind, path, url }: the in-app path and the absolute
URL used by email and push.
Pass dedup_key to make retries safe: the same key from
the same sender is deduplicated for 24 hours per recipient.
Attach a deep_link to send the recipient to a specific
resource when they open the notification. Each of the 11 kinds accepts
its own id field:
{ "kind": "chat", "chat_id": "...", "message_id": "..." }: message_id is optional and scrolls to that message.
{ "kind": "file", "file_id": "..." }, { "kind": "agent", "agent_id": "..." }, { "kind": "computer", "computer_id": "..." }
{ "kind": "workspace", "workspace_id": "...", "section": "agents" }: section is optional.
{ "kind": "settings", "section": "notifications" }, { "kind": "billing" }, { "kind": "usage" }, { "kind": "support-ticket", "ticket_id": "..." }
{ "kind": "hub", "section": "skills" }, { "kind": "home" }
Deep links carry no access tokens. Recipients sign in normally and the destination enforces the usual access controls, so a link to something a recipient cannot see lands on the access-denied screen.
The channels array is a preference, not a command. idapt
intersects it with each recipient's per-type settings and quiet hours,
so a user who turned off email never receives email even if you asked
for it. Only a few critical alerts bypass quiet hours: computer.auto_termination, usage.threshold_90, and computer.workflow_error.
The caller must be a member of the target workspace: a send to a
workspace you do not belong to returns 403. Non-member
recipient ids are dropped silently.
Read and update your own inbox. A PATCH accepts { is_read: true }to mark a notification read (there
is no mark-unread) and { archived: true }or { archived: false }to archive or unarchive it.
| Endpoint | What it does |
|---|---|
GET /notifications | List notifications. |
GET /notifications/preferences | Get notification preferences. |
PATCH /notifications/preferences | Bulk update notification preferences. |
GET /notifications/config | Get notification config (toasts, sound, quiet hours). |
PATCH /notifications/config | Update notification config. |
GET /notifications/:id | Get a notification. |
POST /notifications | Send a notification. |
PATCH /notifications/:id | Update a notification (mark read, …). |
DELETE /notifications/:id | Delete a notification. |
POST /notifications/read-all | Mark all notifications read. |
100 successful sends per 24 hours per principal.
500 per hour to any single recipient across the platform.
Automation webhook fires are capped separately at 60 per hour: see Automations and webhooks.
Related articles
Was this helpful?