A valid request URL is required to generate request examples{
"notifications": [
{
"notificationId": "<string>",
"kind": "needs_user_control",
"title": "<string>",
"artifact": {
"kind": "run",
"agentRunId": "<string>"
},
"actionRequired": true,
"createdAt": "2023-11-07T05:31:56Z",
"readAt": "2023-11-07T05:31:56Z",
"body": "<string>"
}
],
"actionRequiredUnread": 123,
"nextBefore": "<string>"
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}The bell, and the list behind it
What has happened that a person might want to know about: a run that needs somebody, and what became of an order.
actionRequiredUnread is the number to put on the bell. It counts the org’s unread notifications that need somebody to act, across everything and not just this page, so it does not drop to zero when somebody scrolls. An arrival is not counted: nothing is being asked of anybody.
READ STATE IS PER PERSON. A colleague opening the bell does not clear it for you. An API key has no person behind it, so it reads the org’s notifications with readAt null on all of them, and it cannot mark anything read.
One kind is computed rather than stored. An order that has gone past its estimate has no event behind it, only a clock passing a recorded instant, so it appears on the FIRST page with an id prefixed derived:. It is marked read like any other item, and it does not repeat on later pages.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"notifications": [
{
"notificationId": "<string>",
"kind": "needs_user_control",
"title": "<string>",
"artifact": {
"kind": "run",
"agentRunId": "<string>"
},
"actionRequired": true,
"createdAt": "2023-11-07T05:31:56Z",
"readAt": "2023-11-07T05:31:56Z",
"body": "<string>"
}
],
"actionRequiredUnread": 123,
"nextBefore": "<string>"
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Query Parameters
How many to return, 1 to 100. Defaults to 50. Above the maximum is refused, never quietly reduced: page with the cursor instead.
1 <= x <= 100Opaque cursor from a previous page's nextBefore. Treat it as opaque: its form is not part of this contract. Send it only when you have one, because an empty value is refused rather than read as no cursor. Computed notifications appear on the first page only, so a later page carries stored rows alone.
Response
One page of notifications, newest first, and the bell's number.