Back to API Overview

Notifications API

Your notifications: list them, read one, dismiss them.

4 endpoints

Endpoints

POST
/api/v1/notifications/list

List this person's notifications in one tab, newest first, 50 a page. Params: tab ("needs_you": open items someone has to act on, such as an automation that keeps failing; "updates": open news addressed to this person, such as a new status of a problem report or idea they sent; "history": items already cleared, newest cleared first), cursor (optional: the nextCursor of the page before). Returns { items: [{ id, kind, tab, title, subject: { kind, id, name }, step: { label } | null, words, href, repeatCount, firstAt, lastAt, clearedAt, clearedHow, canDismiss }], nextCursor } (null on the last page). words says what happened; href is the dashboard page where it is fixed; repeatCount is how many times it happened while open. Each person sees only the items they may fix (for an automation that keeps failing: whoever may change that flow, function or agent) and the items addressed to them. Only reads.

Parameters

tabstringrequired

Allowed values: needs_you, updates, history

cursorstring

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/notifications/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tab": "example",
  "cursor": "example"
}'
POST
/api/v1/notifications/summary

How many open "needs you" notifications this person has, and the newest three. No params. Returns { needsYou, top: [{ kind, title, href }] }: needsYou stops at 99; each title is a fixed sentence for the kind (call notifications_list for the details). Each person sees only the items they may fix (for an automation that keeps failing: whoever may change that flow, function or agent) and the items addressed to them. Only reads.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/notifications/summary \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'
POST
/api/v1/notifications/forSubject

List the open notifications about one flow, function, agent, problem report or idea, for example before or after fixing it. Params: subject { kind ("flow", "function", "agent", "report" or "idea"), id }. Returns { items } with the same fields as notifications_list (an empty list when nothing about it is open or none of it is for this person). Each person sees only the items they may fix (for an automation that keeps failing: whoever may change that flow, function or agent) and the items addressed to them. Only reads.

Parameters

subjectobjectrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/notifications/forSubject \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": {}
}'
POST
/api/v1/notifications/dismiss

Dismiss one open notification so it leaves the open list and moves to history (nothing else changes: an automation that keeps failing is not fixed by this, and it is raised again if it fails again). Param: id (from notifications_list or notifications_forSubject). A "needs you" item may be dismissed only by someone who may fix it, an update only by the person it is for; canDismiss in the list says which. An id this person cannot see, or one already cleared, reads "not found". Returns { dismissed: true }.

Parameters

idstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/notifications/dismiss \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example"
}'