List the caller's notifications

curl "https://api.example.test/v1/me/notifications?unread=1&class=approvals" \  -H "Authorization: Bearer $TOKEN"

Newest first, paginated with page and per_page like every list (15 by default). 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 person routes on Account Settings → Notifications: approvals, assignments, mentions, planning, sprints, code, testing, releases, deployments, incidents, support, security, digest, onboarding or budget; class_label is its name in the person's language.
title and body are the alert's heading and one sentence of context, the same words the email used, in the person's language at the time it was sent.
route and params name the app 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 person opened it; read_at says when.

Every alert is written to the Notifications Center beside whatever else it sends (the email, the Telegram message the person routed it to). There is no webhook for a new entry; the alerts that matter to an integration already fire their own events.

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 in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

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, such as approvals or incidents. 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"

limit?integer

Alias of per_page, kept for clients that send it. per_page wins when both are sent.

Range1 <= value <= 100

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 (a zg_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 registered a row answers FORBIDDEN 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 role code already taken or a team the caller does not own, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: when class is not one of the alert 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": "approvals",      "class_label": "Approvals",      "title": "CRM-142 is waiting for your approval",      "body": "Priya Patel submitted the story for review.",      "route": "projects.backlog",      "params": {        "projectId": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",        "show": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f70"      },      "url": "https://app.example.test/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/backlog?show=d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f70",      "read": false,      "read_at": null,      "created_at": "2026-11-12T10:05:30+00:00"    }  ]}

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: "Approvals" | "Assignments" | "Mentions" | "Planning" | "Sprints" | "Code" | "Testing" | "Releases" | "Deployments" | "Incidents" | "Support" | "Security" | "Digest" | "Onboarding" | "AI budget";  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;}

List the caller's notifications

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Query Parameters

Responses