List notifications

GET/notifications

As in your inbox, only unread threads unless all is true; view saved or done lists those instead, read or not. Each thread has a reason, why you were told (agent, review_requested, assign, mention, ci_activity, security_alert, state_change, author, comment, manual or subscribed), a severity, the latest activity’s title, and count, how many things have happened on it. Filter by reason or severity, by participating (leaving out what you only watch or subscribed to by hand), by since and before (RFC 3339, the latest activity), or to one repository. A page holds per_page threads, 30 unless you say (at most 100); pass next back as cursor for the next. Threads about repositories you can no longer read are left out. Your own: a personal access token or a session, never a workspace’s.

Unread threads only, unless all=true. Threads that wait on you (an agent, or a review asked of you) have severity warning.

reason	You were told because
agent	An agent is waiting on you: it asked a question, or g1t stopped until a person steps in
review_requested	You were asked to review
assign	You were assigned
mention	Someone mentioned you by @username
ci_activity	Checks, a workflow or a deployment on your work finished
security_alert	A security alert on a repository you look after
state_change	It was closed, reopened or merged
author	You opened it, or asked g1t for it
comment	You commented on it
manual	You subscribed to it by hand
subscribed	You watch its repository

With participating=true, threads you only follow (manual, subscribed) are left out. For the next page, pass next as cursor; next is null on the last.

• Authentication: Required. Send an access token as Authorization: Bearer.
• MCP tool: notifications with action list, and the same inputs
• Scope: An access token needs notifications:read.
• Also at: GET /repos/{owner}/{name}/notifications

Query parameters

Name	Type	Required	Description
all	boolean	No	Read threads too. Left out: only unread ones, in the inbox view.
participating	boolean	No	Only threads you take part in: not those you only watch or subscribed to by hand.
view	string	No	inbox (the default): not done and not snoozed. saved: what you saved. done: what you marked done. One of inbox, saved, done.
reason	string	No	Only threads you were told of for this reason. One of agent, review_requested, assign, mention, team_mention, ci_activity, security_alert, state_change, author, comment, manual, subscribed.
severity	string	No	Only threads of this severity. warning is what is waiting on you: an agent, or a review. One of error, warning, success, info.
since	string	No	RFC 3339: only threads with activity at or after this time.
before	string	No	RFC 3339: only threads whose latest activity was before this time.
cursor	string	No	The next page: the next of the page before.
per_page	integer	No	Threads a page: 30 unless you say, at most 100.

Example request

curl "https://api.g1t.sh/notifications?participating=true" \
  -H "Authorization: Bearer $G1T_TOKEN"

Example response

A successful request answers 200 with:

{
  "items": [
    {
      "id": "ntf_01kp7m2q3r4s5t6v7w8x9y0z1a",
      "reason": "review_requested",
      "severity": "warning",
      "title": "ada asked you to review flagon-io/hello#14",
      "body": "Add a greeting to the README",
      "event": "pull.review_requested",
      "repo": "flagon-io/hello",
      "workspace": "flagon-io",
      "subject": "pull",
      "number": 14,
      "url": "/flagon-io/hello/pull/14",
      "actor": "ada",
      "count": 3,
      "created_at": "2026-10-06T15:02:11.000Z",
      "updated_at": "2026-10-07T09:41:30.000Z",
      "read_at": null,
      "done_at": null,
      "saved": false,
      "snoozed_until": null
    },
    {
      "id": "ntf_01kp7k9a8b7c6d5e4f3g2h1j0k",
      "reason": "ci_activity",
      "severity": "error",
      "title": "Production of hello failed to deploy",
      "body": "The build failed: npm run build exited with 1.",
      "event": "deployment.failed",
      "repo": "flagon-io/hello",
      "workspace": "flagon-io",
      "subject": "deploy",
      "number": null,
      "url": "/flagon-io/hello/deployments/dpl_01kp7k8z7y6x5w4v3t2s1r0q9p",
      "actor": "syntaqx",
      "count": 1,
      "created_at": "2026-10-07T08:12:40.000Z",
      "updated_at": "2026-10-07T08:12:40.000Z",
      "read_at": null,
      "done_at": null,
      "saved": false,
      "snoozed_until": null
    }
  ],
  "next": null
}

Errors

A failed request answers with one of these statuses and a body like {"error": {"code": "not_found", "message": "Repository not found."}}. See errors.

Status	Code	When
401	unauthenticated	A token is required, or the one sent is not valid.
403	forbidden	The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository.
404	not_found	It does not exist, or you cannot see it.
422	invalid	The input is not valid. message says which field and why.