Notifications API

Every alert Subscriby sends a creator (a sale, a support backlog, a bot or channel that went silent, a billing or security notice, a pass window, an onboarding nudge) also lands in the Notifications Center: the sidebar entry with its unread count and popover, and the page at /notifications. These endpoints read the same rows and make the same two marks, so a client, a Zap or an agent can show the inbox and clear it.

The rows belong to the creator behind the token, never to a team or a project, so everything lives under /v1/me. account:read lists them; account:write marks them.

Endpoints

GET/v1/me/notificationsList the caller's notifications POST/v1/me/notifications/read-allMark every notification read POST/v1/me/notifications/{notification}/readMark a notification read

List the caller's notifications

GET

curl "https://api.subscriby.net/v1/me/notifications?unread=1&class=support" \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

Newest first, paginated with page and per_page like every list. unread=1 narrows to entries not yet read (unread=0 to the ones already read); class narrows to one class; q to entries whose title or body contains the words.

class is the alert class the creator routes on Settings → Notifications: sales, support, recovery, billing, security, passes or onboarding; class_label is its name in the creator's language.
title and body are the alert's heading and one sentence of context, the same words the email used, in the creator's language at the time it was sent.
route and params name the dashboard screen the entry opens, as a named route and its parameters, for a client that maps routes to screens; url is the same place resolved, for a client that does not. All three are null when the alert points nowhere.
read is whether the creator opened it; read_at says when.

Every creator alert is written to the notification centre beside whatever else it sends (the email, the message on a connected account the creator routed it to on Settings → Notifications). The entry is shaped from the alert's email: its subject becomes the title, its first line the body, its call to action the route and URL. There is no webhook for a new entry; the alerts that matter to an integration already fire their own events (recovery.*, connector.*, support.*), and a Zap that wants the inbox itself polls the notification_received trigger.

Requires ability

account:read

The token must hold this ability, or the call is refused with 403.

MCP tool

list_notifications

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Query Parameters

unread?|

1 narrows to entries not yet read, 0 to the ones already read; omit it for both.

class?|

Narrow to one alert class: sales, support, recovery, billing, security, passes or onboarding. An unknown class is refused.

q?|

Words the title or body must contain, up to 120 characters.

Lengthlength <= 120

page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value

Default1

per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 15.

Range1 <= value <= 100

Default15

sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"

sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

"asc"
"desc"

Responses

200OKapplication/json

The page, newest first.

data*array<>

The items on this page.

links*

Links to the first, last, previous and next pages.

meta*

The paging counters for this page.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when class is not one of the seven classes.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/me/notifications"

{  "data": [    {      "id": "0b1f6e2a-7c3d-4e5f-8a9b-0c1d2e3f4a5b",      "class": "support",      "class_label": "Support",      "title": "Support backlog in Signals",      "body": "Three members are waiting for an answer.",      "route": "projects.inbox",      "params": {        "projectId": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13"      },      "url": "https://app.subscriby.net/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/inbox",      "read": false,      "read_at": null,      "created_at": "2026-09-12T10:05:30Z"    }  ]}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: NotificationResource[];  links: Links;  meta: Meta;}export interface NotificationResource {  id: string;  class: string;  class_label: "Sales" | "Support" | "Recovery" | "Billing" | "Security" | "Passes" | "Onboarding";  title: string;  body: string;  route: string | null;  params: Record<string, string>;  url: string | null;  read: boolean;  read_at: string | null;  created_at: string | null;}export interface Links {  first: string | null;  last: string | null;  prev: string | null;  next: string | null;}export interface Meta {  current_page: number;  from: number | null;  last_page: number;  links: Link[];  path: string | null;  per_page: number;  to: number | null;  total: number;}export interface Link {  url: string | null;  label: string;  active: boolean;}

Mark every notification read

POST

curl -X POST https://api.subscriby.net/v1/me/notifications/read-all \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Answers 200 with how many entries were unread and are read now. A second call marks nothing and answers 0.

Requires ability

account:write

The token must hold this ability, or the call is refused with 403.

MCP tool

mark_all_notifications_read

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Responses

200OKapplication/json

200 with how many rows were marked.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/me/notifications/read-all" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "marked": 3  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: Data;}export interface Data {  marked: number;}

Mark a notification read

POST

curl -X POST https://api.subscriby.net/v1/me/notifications/$NOTIFICATION_ID/read \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

Answers 200 with the entry, read now true. Idempotent: an entry already read keeps its first read_at.

Requires ability

account:write

The token must hold this ability, or the call is refused with 403.

MCP tool

mark_notification_read

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

notification*string

The row, resolved by the route binder as the caller's.

Header Parameters

Idempotency-Key*string

Formatuuid

Responses

200OKapplication/json

200 with the row, read.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. On this endpoint: RESOURCE_NOT_FOUND: for an id that is not one of the caller's entries.

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/me/notifications/string/read" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12"

{  "data": {    "id": "0b1f6e2a-7c3d-4e5f-8a9b-0c1d2e3f4a5b",    "class": "support",    "class_label": "Support",    "title": "Support backlog in Signals",    "body": "Three members are waiting for an answer.",    "route": "projects.inbox",    "params": {      "property1": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "property2": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13"    },    "url": "https://app.subscriby.net/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/inbox",    "read": false,    "read_at": null,    "created_at": "2026-09-12T10:05:30Z"  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: NotificationResource;}export interface NotificationResource {  id: string;  class: string;  class_label: "Sales" | "Support" | "Recovery" | "Billing" | "Security" | "Passes" | "Onboarding";  title: string;  body: string;  route: string | null;  params: Record<string, string>;  url: string | null;  read: boolean;  read_at: string | null;  created_at: string | null;}

Me APIThe caller, with unread_notifications, so a client can draw the sidebar badge without listing the inbox.Alert Destinations APIWhere each class of alert is delivered.Email & NotificationsThe Notifications Center on the dashboard.

Notifications API

EndpointsCopy Anchor Link

List the caller's notificationsCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Mark every notification readCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Mark a notification readCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

Endpoints

List the caller's notifications

Authorization

Query Parameters

Responses

Mark every notification read

Authorization

Header Parameters

Responses

Mark a notification read

Authorization

Path Parameters

Header Parameters

Responses