Templates

These endpoints store and inspect templates: save one, list them, copy, rename, pick the default, move them between Macs as bundles, and render a preview image. They also serve the lookups a template author needs: the component schema, SF Symbol names and the installed Shortcuts. The examples use the $HERALD and $TOKEN variables from Connect.

What a template is#

A template is a saved layout for one app's banners. It is a grid of cells, and each cell holds a component such as text, an image or a row of buttons. A component is bound to a field of the notification, for example {title}, so one template draws every notification the app sends.

A template belongs to one app and has a name. A notification picks its template in this order:

1. The template named in the notification.
2. The defaultTemplate of the app's manifest.
3. One of the four built-in layouts: builtin.imageLeft, builtin.imageRight, builtin.hero, builtin.compact.

You can design a template by hand in the Designer or send its JSON to this API. The fields of the template object are documented in Grid and layout; this page covers only the endpoints.

1234567

The Designer edits the same template object these endpoints store. A template saved here appears in the Designer at once.

Endpoints#

Store templates#

GET /v1/templates#

Lists the templates saved for one app, or for every app. Each item is the full template object.

Request

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

{
  "items": [
    {
      "name": "bid-won",
      "app": "example.bidbot",
      "layoutVersion": 2,
      "collapseEmpty": true,
      "grid": {
        "rows": 2,
        "cols": 2,
        "rowSizes": ["auto", "auto"],
        "colSizes": ["48", "fill"],
        "gap": 8,
        "padding": 14,
        "width": 400
      },
      "cells": [
        {"id": "icon", "row": 0, "col": 0, "rowSpan": 2, "component": {"type": "issuerIcon"}},
        {"id": "title", "row": 0, "col": 1, "component": {"type": "text", "binding": "{title}", "style": "title"}},
        {"id": "body", "row": 1, "col": 1, "component": {"type": "text", "binding": "{body}", "style": "body"}}
      ]
    }
  ]
}

Notes

• The four builtin.* layouts are not listed. They always exist.
• Templates whose names start with _ are scratch templates, such as the one the Designer writes for Send test. They work by name and are never listed.

PUT /v1/templates#

Saves a template. If the app already has a template with the same name, it is replaced. The template is validated before it is stored, so a bad layout is refused here and not when a notification arrives.

Request

The body is one template object. These two fields are required; the rest are in Grid and layout.

curl -s -X PUT "$HERALD/v1/templates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "bid-won",
    "app": "example.bidbot",
    "layoutVersion": 2,
    "collapseEmpty": true,
    "grid": {"rows": 2, "cols": 2, "rowSizes": ["auto", "auto"], "colSizes": ["48", "fill"],
             "gap": 8, "padding": 14, "width": 400},
    "cells": [
      {"id": "icon", "row": 0, "col": 0, "rowSpan": 2, "component": {"type": "issuerIcon"}},
      {"id": "title", "row": 0, "col": 1,
       "component": {"type": "text", "binding": "{title}", "style": "title"}},
      {"id": "body", "row": 1, "col": 1,
       "component": {"type": "text", "binding": "{body}", "style": "body", "maxLines": 3}}
    ]
  }'

{"ok": true}

Errors

Notes

• A validation message names the cell and the path of each problem, separated by semicolons, for example invalid template: grid.rowSizes: rowSizes has 1 entries but rows is 2; grid.gap: gap must be 0 to 64. A problem inside a cell starts with cell <id>:.
• Templates are files: templates/<app>/<name>.json in Herald's support folder.

DELETE /v1/templates#

Deletes one saved template.

Request

curl -s -X DELETE "$HERALD/v1/templates?app=example.bidbot&name=bid-won" \
  -H "Authorization: Bearer $TOKEN"

{"ok": true}

Errors

Copy, rename and choose the default#

POST /v1/templates/duplicate#

Copies a saved template or a built-in layout. Use it to start a new design from an existing one, or to give another app the same layout.

Request

curl -s -X POST "$HERALD/v1/templates/duplicate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "name": "builtin.hero", "newName": "bid-hero"}'

{
  "ok": true,
  "app": "example.bidbot",
  "name": "bid-hero",
  "copiedFrom": {"app": "example.bidbot", "name": "builtin.hero"}
}

Errors

Notes

• Without newName the copy is named after the original: bid-won copy, then bid-won copy 2 when that is taken.
• A template name cannot be empty, contain / or :, start with . or _, start with builtin., or be longer than 128 bytes.

POST /v1/templates/rename#

Renames a saved template. If it was the app's default template, the manifest follows the new name.

Request

curl -s -X POST "$HERALD/v1/templates/rename" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "name": "bid-hero", "newName": "bid-accepted"}'

{
  "ok": true,
  "app": "example.bidbot",
  "name": "bid-accepted",
  "renamedFrom": "bid-hero",
  "isDefault": false,
  "note": "Command, script and Shortcut approvals belong to the old name; the user is asked again the first time they run."
}

Errors

Notes

• Approvals to run commands, scripts and Shortcuts are tied to the template's name. After a rename the user is asked again the first time one runs.
• Built-in layouts cannot be renamed. Duplicate one instead.

PUT /v1/templates/default#

Sets the template an app uses when a notification names none, or clears it. The default is stored in the app's manifest as defaultTemplate, so the app must have a manifest.

Request

curl -s -X PUT "$HERALD/v1/templates/default" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "name": "bid-accepted"}'

{"ok": true, "app": "example.bidbot", "defaultTemplate": "bid-accepted"}

Errors

PUT /v1/templates/follow-up#

Sets the follow-up of a template, or switches it off. A follow-up runs one action when a banner is left unattended (see Follow-ups). The route edits the template for you, so you do not read and rewrite it. It never approves code. When the action runs code, the result says the person still has to approve it at the Mac.

Request

Give exactly one of shortcut, script, command and actionRef, unless enabled is false.

curl -s -X PUT "$HERALD/v1/templates/follow-up" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "template": "Bid won", "after": "10m",
       "shortcut": "Forward to phone", "input": "{title}"}'

{
  "saved": true,
  "app": "example.bidbot",
  "template": "Bid won",
  "createdTemplate": false,
  "followUp": {"after": 600, "action": {"id": "follow-up", "label": "Forward to phone",
               "kind": "shortcut", "shortcut": "Forward to phone", "input": "{title}"}},
  "action": {"id": "follow-up", "label": "Forward to phone",
             "kind": "shortcut", "shortcut": "Forward to phone", "input": "{title}"},
  "origin": "template",
  "approval": "needs-approval",
  "needsApproval": true,
  "note": "Approval stays with the person at the Mac: the banner asks the first time the action would run, and Always allow lets later follow-ups run unattended. Nothing was approved here. list_shortcuts names the installed Shortcuts."
}

Response fields

The approval values:

Errors

Notes

• Priority is template, then notification, then manifest. A template follow-up wins over the issuer's.
• "enabled": false also switches off a follow-up that the issuer declares.
• With actionRef, the action may be one the issuer offers. It then runs under the app's permission and origin is issuer.
• Approval is bound to the template's name and its code. Changing the Shortcut asks again.
• A built-in layout is read-only. Duplicate it first, or leave out template to use the app's default.

Move templates between Macs#

A bundle is one .heraldtemplate file that holds a template and the Rive animations it uses. Export a bundle to share a design, and import it on another Mac or into another app. How bundles treat assets is explained in Rive: packaging with a template.

GET /v1/templates/export#

Packs a template and its Rive files into a bundle. Herald either writes the bundle to a path you give, or returns it in the reply as base64.

Request

curl -s -G "$HERALD/v1/templates/export" -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "app=example.bidbot" --data-urlencode "name=bid-accepted" \
  --data-urlencode "path=$HOME/Desktop/bid-accepted.heraldtemplate"

{
  "ok": true,
  "app": "example.bidbot",
  "name": "bid-accepted",
  "file": "bid-accepted.heraldtemplate",
  "bytes": 18432,
  "assets": ["confetti.riv"],
  "warnings": [],
  "path": "/Users/you/Desktop/bid-accepted.heraldtemplate"
}

Response fields

Errors

POST /v1/templates/import#

Installs a bundle: saves its template and stores its Rive files. You choose what happens when a template with the same name already exists.

Request

Give exactly one of base64 and path.

curl -s -X POST "$HERALD/v1/templates/import" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"path": "~/Desktop/bid-accepted.heraldtemplate", "app": "example.bidbot", "onConflict": "keepBoth"}'

{
  "ok": true,
  "app": "example.bidbot",
  "name": "bid-accepted 2",
  "renamedFrom": "bid-accepted",
  "replaced": false,
  "installedAssets": ["confetti.riv"],
  "reusedAssets": [],
  "missingAssets": [],
  "warnings": []
}

Response fields

Errors

Notes

• keepBoth saves the import under a new numbered name. replace overwrites. fail refuses.
• A request body is limited to 1 MB, so use path for any bundle with animations in it.

Preview a template#

POST /v1/preview#

Renders a template to a PNG image with the same code that draws real banners, without showing anything on screen. Use it to check a design, including how it looks with long text, missing fields, in dark mode or as a stack.

Request

curl -s -X POST "$HERALD/v1/preview" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "app": "example.bidbot",
    "template": "bid-accepted",
    "data": {"title": "Bid accepted", "body": "Acme accepted your bid of $4,200."},
    "appearance": "dark"
  }' -o preview.png

Example response

The reply is the image itself, with Content-Type: image/png. The command above saves it as preview.png.

preview.png: PNG image data, 800 x 196, 8-bit/color RGBA

Errors

Notes

• Without template, Herald uses the app's default template, or builtin.imageLeft.
• data: "sample" uses the sample values of the app's manifest. data: "last" uses the app's most recent notification. An object is read like the body of POST /v1/notify: leave a field out to see how the template collapses without it.
• A preview cannot play a rive component and draws a labelled placeholder in its place. Menus are drawn as static labels, and symbol effects do not animate.

Confirmation kinds#

Herald sometimes asks a question inside a banner before it acts, for example before it runs a command for the first time. confirmation draws such a question so that you can check how it looks. Send a kind as a string, or an object with a kind and optional text.

The object form accepts these optional strings to fill in the question's text. Each has a sample default.

{
  "app": "example.bidbot",
  "template": "bid-accepted",
  "confirmation": {"kind": "command", "command": "open -a Numbers ~/Bids/acme.numbers"}
}

GET /v1/preview#

The quick form of the preview: renders a saved template with the manifest's sample data. It is convenient in a browser-free check such as curl -o, because everything is in the URL.

Request

curl -s "$HERALD/v1/preview?app=example.bidbot&template=bid-accepted&appearance=dark" \
  -H "Authorization: Bearer $TOKEN" -o preview.png

Example response

The reply is a PNG image, as for POST /v1/preview.

preview.png: PNG image data, 800 x 196, 8-bit/color RGBA

Errors

Look things up#

GET /v1/components#

Returns the component schema: every component type with its properties, allowed values and defaults, the binding rules, the action kinds, and worked examples. It is static data made for programs and agents that write templates. The human-readable version is the components reference.

Request

No parameters.

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

Example response

The document is long. This is its outline, with the content of each part left out and the description shortened.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Herald banner template, layoutVersion 2",
  "schemaVersion": 2,
  "description": "A Herald banner is drawn from a GRID.",
  "type": "object",
  "required": ["name", "app", "layoutVersion", "grid", "cells"],
  "properties": {},
  "definitions": {},
  "components": {},
  "bindings": {},
  "actions": {},
  "examples": [],
  "workflow": []
}

Response fields

GET /v1/symbols#

Searches the SF Symbol names available on this Mac. Use a returned name as a component's symbol value. See the SF Symbols reference.

Request

curl -s "$HERALD/v1/symbols?q=bell&limit=3" -H "Authorization: Bearer $TOKEN"

{
  "total": 28,
  "offset": 0,
  "limit": 3,
  "symbols": [
    {"name": "bell", "categories": ["multicolor", "objectsandtools"]},
    {"name": "bell.fill", "categories": ["multicolor", "objectsandtools"]},
    {"name": "bell.circle", "categories": ["multicolor", "objectsandtools", "variable"]}
  ],
  "categories": [
    {"key": "all", "title": "All", "icon": "square.grid.2x2", "count": 7779},
    {"key": "communication", "title": "Communication", "icon": "message", "count": 222}
  ]
}

Response fields

Errors

GET /v1/shortcuts#

Lists the names of the Apple Shortcuts installed on this Mac. Use a name in a template action of kind shortcut.

Request

No parameters.

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

{"items": ["Create follow-up", "Log Entry"]}

Errors

Related#

• Follow-ups: the timer, the approval and what the banner shows.
• Forward a notification you missed: a follow-up that forwards a banner.
• Templates guide: what to put in a template and why.
• Design a banner in the Designer: the same work by hand.
• Grid and layout: every field of the template object.
• Components: what each cell can hold.
• MCP tools for templates: the same operations for an agent.