Stacks

These endpoints show which banners are stacked, open or close a stack, and set how Herald groups banners into stacks. Use them to inspect what is on screen or to control stacking from a script. The examples use the $HERALD and $TOKEN variables from Connect.

What a stack is#

When several notifications that belong together are on screen, Herald folds them into one stack: a single card with a count, so that ten emails do not cover the screen. Clicking a stack opens it into a list.

What "belong together" means is the stacking level.

There is one global level, and each app can override it. The concept is explained in full, with examples, in the stacking reference.

A closed stack. The card on top is the newest notification and the badge counts the notifications in the stack.

Endpoints#

GET /v1/stacks#

Lists the stacks that are on screen now, with the notifications in each.

Request

curl -s "$HERALD/v1/stacks?app=example.bidbot" -H "Authorization: Bearer $TOKEN"

{
  "stacks": [
    {
      "level": "bySender",
      "app": "example.bidbot",
      "group": "acme",
      "count": 2,
      "expanded": false,
      "members": [
        {
          "app": "example.bidbot",
          "id": "bid-43",
          "title": "Counter-offer from Acme",
          "group": "acme",
          "deliveredAt": "2026-10-02T13:02:11.000Z"
        },
        {
          "app": "example.bidbot",
          "id": "bid-42",
          "title": "Bid accepted",
          "group": "acme",
          "deliveredAt": "2026-10-02T13:00:04.237Z"
        }
      ],
      "frame": {"x": 1508, "y": 44, "width": 400, "height": 96}
    }
  ]
}

Response fields

Notes

• When nothing is stacked the reply is an empty list.

POST /v1/stacks/expand#

Opens a stack into a list of its banners, or closes it back into one card. This is what a click on the stack does.

Request

curl -s -X POST "$HERALD/v1/stacks/expand" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "group": "acme", "expanded": true}'

{"ok": true}

Errors

GET /v1/settings/stacking#

Returns the global stacking level and the levels you can choose from.

Request

No parameters.

curl -s "$HERALD/v1/settings/stacking" -H "Authorization: Bearer $TOKEN"

{"level": "bySender", "levels": ["byApp", "byIssuer", "bySender", "never"]}

PUT /v1/settings/stacking#

Sets the global stacking level. Apps with their own level keep it.

Request

curl -s -X PUT "$HERALD/v1/settings/stacking" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"level": "byIssuer"}'

{"level": "byIssuer", "levels": ["byApp", "byIssuer", "bySender", "never"]}

Errors

Notes

• The same value is the stacking key of PUT /v1/settings. Use either.
• To give one app its own level, set stacking with PUT /v1/apps/settings.

Related#

• Stacking reference: the levels explained with examples, and how a stack looks.
• Notifications API: POST /v1/dismissAll with a group closes one stack.
• stackBadge component: show the count in your own template.