Assets

These endpoints manage the files an app's templates draw: Rive animations and images. Upload a file, list what an app has, and delete what you do not need. The examples use the $HERALD and $TOKEN variables from Connect.

What an asset is#

An asset is a file Herald keeps for one app so that its templates can use it. There are two kinds.

A notification can already carry a picture in its image field. Upload an image as an asset when the same picture is part of the design, such as a logo, and should not be sent with every notification.

Rive files can also be declared in the app's manifest, which installs them when the manifest is saved. Uploading here is the direct way and needs no manifest.

Endpoints#

GET /v1/assets#

Lists the Rive files and images stored for one app, and for each Rive file which templates use it.

Request

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

{
  "app": "example.bidbot",
  "folder": "/Users/you/Library/Application Support/Herald/assets/example.bidbot",
  "limits": {"bytes": 10485760, "riveFiles": 32},
  "assets": [
    {
      "kind": "rive",
      "id": "confetti",
      "file": "confetti.riv",
      "path": "/Users/you/Library/Application Support/Herald/assets/example.bidbot/confetti.riv",
      "bytes": 48211,
      "declared": false,
      "usedBy": ["bid-accepted"],
      "component": {"type": "rive", "path": "confetti.riv"}
    },
    {
      "kind": "image",
      "file": "logo.png",
      "path": "/Users/you/Library/Application Support/Herald/assets/example.bidbot/images/logo.png",
      "bytes": 9120
    }
  ]
}

Response fields

Errors

POST /v1/assets#

Stores a Rive animation or an image for an app. Uploading a file with the name of an existing one replaces it.

Request

Give the file in exactly one of two ways: path for a file that is already on this Mac, or base64 for content sent in the request.

curl -s -X POST "$HERALD/v1/assets" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "example.bidbot", "path": "~/Designs/confetti.riv"}'

{
  "ok": true,
  "kind": "rive",
  "app": "example.bidbot",
  "id": "confetti",
  "file": "confetti.riv",
  "path": "/Users/you/Library/Application Support/Herald/assets/example.bidbot/confetti.riv",
  "bytes": 48211,
  "replaced": false,
  "component": {"type": "rive", "path": "confetti.riv"}
}

Response fields

Errors

Notes

• A request body is limited to 1 MB, so base64 suits files up to about 700 KB. Use path for anything larger.
• Images are checked by their bytes, not their names. PNG, JPEG, GIF, WebP, HEIC, TIFF and BMP are accepted.
• An app can hold 32 Rive files and 100 images, each up to 10 MB.

DELETE /v1/assets#

Deletes one stored file. Templates are not changed, so the reply tells you which templates still refer to a deleted animation.

Request

curl -s -X DELETE "$HERALD/v1/assets?app=example.bidbot&file=confetti.riv" \
  -H "Authorization: Bearer $TOKEN"

{"ok": true, "deleted": "confetti.riv", "stillReferencedBy": ["bid-accepted"]}

Errors

Notes

• A template that plays a deleted animation draws a labelled placeholder in its place.

Related#

• Rive in Herald: preparing an animation and driving it from notification fields.
• rive component and image component.
• Template bundles: move a template together with its Rive files.
• MCP tools for templates: the same operations for an agent.