ink.branchline.listNotifications

branchline.ink

Documentation

List unread notifications for the authenticated viewer. Requires a valid session cookie; responds 401 otherwise. Notifications are derived from indexed records (no separate notification table) and grouped by subject; a group counts as unread when its latestAt is newer than the viewer's stored readAt for that group (see ink.branchline.markNotificationsRead). Three kinds are emitted: 'continuation' (someone grew one of the viewer's buds), 'seedGrant' (someone gave the viewer a seed), and 'bookmarkGrowth' (new buds on a story the viewer bookmarked).

main query

List unread notifications for the authenticated viewer. Requires a valid session cookie; responds 401 otherwise. Notifications are derived from indexed records (no separate notification table) and grouped by subject; a group counts as unread when its latestAt is newer than the viewer's stored readAt for that group (see ink.branchline.markNotificationsRead). Three kinds are emitted: 'continuation' (someone grew one of the viewer's buds), 'seedGrant' (someone gave the viewer a seed), and 'bookmarkGrowth' (new buds on a story the viewer bookmarked).

Parameters

limit integer Optional

No description available.

Output

Encodingapplication/json
notifications array Required

No description available.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Base URL for XRPC calls (e.g., https://api.bsky.social)
Parameters
View raw schema 
{
  "type": "query",
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "notifications"
      ],
      "properties": {
        "notifications": {
          "type": "array",
          "items": {
            "refs": [
              "#continuationView",
              "#seedGrantView",
              "#bookmarkGrowthView"
            ],
            "type": "union",
            "closed": true
          }
        }
      }
    },
    "encoding": "application/json"
  },
  "parameters": {
    "type": "params",
    "properties": {
      "limit": {
        "type": "integer",
        "default": 20,
        "maximum": 50,
        "minimum": 1
      }
    }
  },
  "description": "List unread notifications for the authenticated viewer. Requires a valid session cookie; responds 401 otherwise. Notifications are derived from indexed records (no separate notification table) and grouped by subject; a group counts as unread when its latestAt is newer than the viewer's stored readAt for that group (see ink.branchline.markNotificationsRead). Three kinds are emitted: 'continuation' (someone grew one of the viewer's buds), 'seedGrant' (someone gave the viewer a seed), and 'bookmarkGrowth' (new buds on a story the viewer bookmarked)."
}
actor object

No description available.

Properties

did string did Required

A decentralized identifier (DID).

displayName string Optional

No description available.

handle string handle Optional

An AT Protocol handle (e.g., alice.bsky.social).

View raw schema 
{
  "type": "object",
  "required": [
    "did"
  ],
  "properties": {
    "did": {
      "type": "string",
      "format": "did"
    },
    "handle": {
      "type": "string",
      "format": "handle"
    },
    "displayName": {
      "type": "string"
    }
  }
}
bookmarkGrowthView object

A story the viewer bookmarked received new buds past the viewer's last dismissal.

Properties

actorCount integer Required

No description available.

minimum: 1
actors array of ref#actor Required

No description available.

maxLength: 10 items
groupKey string Required

Format: 'bookmarkGrowth:{rootUri}'.

latestAt string datetime Required

createdAt of the most recent qualifying new bud on this story.

newBudCount integer Required

Number of new buds since the viewer last dismissed this group (bounded for display).

minimum: 1
rootTitle string Required

No description available.

rootUri string at-uri Required

Root bud AT-URI of the bookmarked story.

View raw schema 
{
  "type": "object",
  "required": [
    "groupKey",
    "latestAt",
    "rootUri",
    "rootTitle",
    "newBudCount",
    "actors",
    "actorCount"
  ],
  "properties": {
    "actors": {
      "type": "array",
      "items": {
        "ref": "#actor",
        "type": "ref"
      },
      "maxLength": 10
    },
    "rootUri": {
      "type": "string",
      "format": "at-uri",
      "description": "Root bud AT-URI of the bookmarked story."
    },
    "groupKey": {
      "type": "string",
      "description": "Format: 'bookmarkGrowth:{rootUri}'."
    },
    "latestAt": {
      "type": "string",
      "format": "datetime",
      "description": "createdAt of the most recent qualifying new bud on this story."
    },
    "rootTitle": {
      "type": "string"
    },
    "actorCount": {
      "type": "integer",
      "minimum": 1
    },
    "newBudCount": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of new buds since the viewer last dismissed this group (bounded for display)."
    }
  },
  "description": "A story the viewer bookmarked received new buds past the viewer's last dismissal."
}
continuationView object

One of the viewer's buds received at least one child bud since the group was last read.

Properties

actorCount integer Required

No description available.

minimum: 1
actors array of ref#actor Required

Up to 10 unique actors who wrote qualifying child buds, most-recent actor first.

maxLength: 10 items
groupKey string Required

Stable identifier used with ink.branchline.markNotificationsRead. Format: 'continuation:{parentUri}'.

latestAt string datetime Required

Timestamp of the most recent child bud in this group. Drives sort order.

parentTitle string Required

No description available.

parentUri string at-uri Required

AT-URI of the viewer's bud that was extended.

View raw schema 
{
  "type": "object",
  "required": [
    "groupKey",
    "latestAt",
    "parentUri",
    "parentTitle",
    "actors",
    "actorCount"
  ],
  "properties": {
    "actors": {
      "type": "array",
      "items": {
        "ref": "#actor",
        "type": "ref"
      },
      "maxLength": 10,
      "description": "Up to 10 unique actors who wrote qualifying child buds, most-recent actor first."
    },
    "groupKey": {
      "type": "string",
      "description": "Stable identifier used with ink.branchline.markNotificationsRead. Format: 'continuation:{parentUri}'."
    },
    "latestAt": {
      "type": "string",
      "format": "datetime",
      "description": "Timestamp of the most recent child bud in this group. Drives sort order."
    },
    "parentUri": {
      "type": "string",
      "format": "at-uri",
      "description": "AT-URI of the viewer's bud that was extended."
    },
    "actorCount": {
      "type": "integer",
      "minimum": 1
    },
    "parentTitle": {
      "type": "string"
    }
  },
  "description": "One of the viewer's buds received at least one child bud since the group was last read."
}
seedGrantView object

Someone granted the viewer a seed.

Properties

grantor ref #actor Required

No description available.

groupKey string Required

Format: 'seedGrant:{seedUri}'.

latestAt string datetime Required

createdAt of the seed.

seedUri string at-uri Required

An AT Protocol URI (e.g., at://did:plc:xyz/app.bsky.feed.post/abc).

View raw schema 
{
  "type": "object",
  "required": [
    "groupKey",
    "latestAt",
    "seedUri",
    "grantor"
  ],
  "properties": {
    "grantor": {
      "ref": "#actor",
      "type": "ref"
    },
    "seedUri": {
      "type": "string",
      "format": "at-uri"
    },
    "groupKey": {
      "type": "string",
      "description": "Format: 'seedGrant:{seedUri}'."
    },
    "latestAt": {
      "type": "string",
      "format": "datetime",
      "description": "createdAt of the seed."
    }
  },
  "description": "Someone granted the viewer a seed."
}

Lexicon Garden

@