# ink.branchline.listNotifications

> Published by [branchline.ink](https://lexicon.garden/identity/did:plc:brvu7akhdvsqcomb67pafw25)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:brvu7akhdvsqcomb67pafw25/ink.branchline.listNotifications)
- [Documentation](https://lexicon.garden/lexicon/did:plc:brvu7akhdvsqcomb67pafw25/ink.branchline.listNotifications/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:brvu7akhdvsqcomb67pafw25/ink.branchline.listNotifications/examples)

## Definitions

### `ink.branchline.listNotifications`

**Type**: `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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `limit` | `integer` | No |  |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `notifications` | `array` | Yes |  |

### `ink.branchline.listNotifications#actor`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `did` | `string` (did) | Yes |  |
| `handle` | `string` (handle) | No |  |
| `displayName` | `string` | No |  |

### `ink.branchline.listNotifications#seedGrantView`

**Type**: `object`

Someone granted the viewer a seed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `grantor` | `ref` → `#actor` | Yes |  |
| `seedUri` | `string` (at-uri) | Yes |  |
| `groupKey` | `string` | Yes | Format: 'seedGrant:{seedUri}'. |
| `latestAt` | `string` (datetime) | Yes | createdAt of the seed. |

### `ink.branchline.listNotifications#continuationView`

**Type**: `object`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `actors` | `array` | Yes | Up to 10 unique actors who wrote qualifying child buds, most-recent actor first. |
| `groupKey` | `string` | Yes | Stable identifier used with ink.branchline.markNotificationsRead. Format: 'continuation:{parentUri}'. |
| `latestAt` | `string` (datetime) | Yes | Timestamp of the most recent child bud in this group. Drives sort order. |
| `parentUri` | `string` (at-uri) | Yes | AT-URI of the viewer's bud that was extended. |
| `actorCount` | `integer` | Yes |  |
| `parentTitle` | `string` | Yes |  |

### `ink.branchline.listNotifications#bookmarkGrowthView`

**Type**: `object`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `actors` | `array` | Yes |  |
| `rootUri` | `string` (at-uri) | Yes | Root bud AT-URI of the bookmarked story. |
| `groupKey` | `string` | Yes | Format: 'bookmarkGrowth:{rootUri}'. |
| `latestAt` | `string` (datetime) | Yes | createdAt of the most recent qualifying new bud on this story. |
| `rootTitle` | `string` | Yes |  |
| `actorCount` | `integer` | Yes |  |
| `newBudCount` | `integer` | Yes | Number of new buds since the viewer last dismissed this group (bounded for display). |

## Raw Schema

```json
{
  "id": "ink.branchline.listNotifications",
  "defs": {
    "main": {
      "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": {
      "type": "object",
      "required": [
        "did"
      ],
      "properties": {
        "did": {
          "type": "string",
          "format": "did"
        },
        "handle": {
          "type": "string",
          "format": "handle"
        },
        "displayName": {
          "type": "string"
        }
      }
    },
    "seedGrantView": {
      "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."
    },
    "continuationView": {
      "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."
    },
    "bookmarkGrowthView": {
      "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."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```