Agent endpoints

These are the plain HTTPS routes a cloud agent uses to reach a user's Mac through the relay: queue a notification, read what happened to it, wait for the user's answer, and ask whether the Mac is reachable. Read this page if you are writing an agent or an integration that talks to the relay without MCP. Every route except /health and the signed audio links needs the agent's credential. The same four actions are also offered as MCP tools.

All examples use two variables. $RELAY is the relay's origin and $KEY is the credential the agent holds.

RELAY="https://herald-relay.example.workers.dev"
KEY="hrk_..."

Before you start#

• You hold an agent key (hrk_...) or a connector access token (hra_...). Both are sent as Authorization: Bearer $KEY. See Relay API for how credentials are made and how they differ.
• Send a custom User-Agent header, as the examples do. On a relay without a custom domain, Cloudflare's Browser Integrity Check can reject a default library agent before the request reaches the relay.

Concepts#

An approved connector works until the user revokes it. Agent keys and access tokens never expire and are never rotated, so an agent keeps one credential for as long as the user keeps it. A revoked key or token is refused with 401 at once.

An agent sees only the notifications its own credential sent. Two keys, or a key and a connector, never see each other's receipts or replies. A credential can send notifications and read what it sent. It cannot change a setting, a quiet hour or anything else on the Mac.

A connector cannot send buttons, commands, scripts or any code. The relay accepts a fixed list of text and presentation fields and refuses everything else, as Forbidden fields shows.

The receipt#

A receipt is a set of separate facts, each set by whoever knows it. The notify call, the receipt read and the get_receipt and send_notification MCP tools all return this object. A reply read from the replies endpoint shares its reply fields.

Response fields

The reply fields (repliedAt, reply, text, transcript, transcriptNote, audioUrl, audioUrlExpiresInSeconds, durationSeconds) are present only after the user has replied.

The reason values are:

Notifications#

POST /v1/notify#

Queues a notification for the user's Mac and returns its receipt. The relay stores the notification until Herald takes it, which is at once when the Mac is online. Use it to tell the user something, and set expectReply when you want an answer.

The body carries text and presentation only. The relay checks it against a whitelist, and Herald checks the notification again when it receives it.

Request

Only title is required. Every field goes in the JSON body. The text fields:

The presentation fields. None of them can run or open anything.

The speech fields. Herald speaks on the Mac, so these only choose what is said and how.

The reply fields:

curl -s -X POST "$RELAY/v1/notify" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d '{
    "notificationId": "build-214",
    "title": "Build finished",
    "body": "All 214 tests passed.",
    "status": "done",
    "project": "web",
    "link": "https://example.com/builds/214",
    "speak": true,
    "expectReply": true
  }'

Example response

The reply is 202 for a new notification. It is the receipt plus a duplicate flag.

{
  "duplicate": false,
  "notificationId": "build-214",
  "received": true,
  "receivedAt": "2026-10-02T13:00:04.000Z",
  "queued": true,
  "displayed": false,
  "spoken": false,
  "replied": false,
  "expectReply": true,
  "suppressed": false
}

Response fields

Errors

Every error body has error and message. See Limits and errors for the shared errors.

Notes

• A notification with a notificationId that this key sent in the last 24 hours is not queued again. The relay answers 200 with the first notification's receipt and duplicate: true, so a retry is safe. A duplicate does not count toward the 60 per 10 minutes limit.
• The relay allows 60 notifications per 10 minutes per key. A 429 carries retryAfterSeconds and a Retry-After header, except queue_full, which carries neither.
• The body may be 32 KB. A data: icon is the one exception: it may add up to 256 KB, and everything else must still fit in 32 KB. An icon larger than 256 KB is a 400 that names icon.
• Speech turns on when voice, speed, or a presentation of voice or both is set. An explicit speak: false turns it off again, whatever else is set.
• Quiet hours and mute are enforced on the Mac, not by the relay. Read the receipt to see whether Herald held a notification back.
• expectReply does not change how the banner looks. Use status for a badge.
• The relay stores group and passes it on. Herald applies it on the Mac.
• The relay checks the credential, then the daily request budget, then the body, so a key with a spent budget gets 503 even for a body that is invalid.

Forbidden fields#

A field outside the accepted list makes the whole request fail. Nothing is queued, and the error names every rejected field. The error text calls out some names because they would run or open something on the Mac. Use link for a URL and imageURL for a picture.

{
  "error": "forbidden_fields",
  "message": "rejected fields: buttons. Cloud notifications carry text and presentation only (buttons would run or open something on the Mac and is never accepted). Accepted fields: notificationId, title, subtitle, body, status, project, session, task, tool, duration, link, group, priority, speak, expectReply, allowVoiceReply, persistent, timeoutSeconds, sound, voice, speed, presentation, icon, imageURL, tags.",
  "fields": ["buttons"]
}

An unknown key inside a speak object is refused the same way and reported as speak.<key>.

Receipts and replies#

GET /v1/receipts/{notificationId}#

Returns what has happened to a notification this credential sent: whether the relay has it, whether the Mac showed it, spoke it, got a reply, or held it back. Use it after sending to learn the outcome. To read the reply itself, or to wait for it, use GET /v1/replies/{notificationId}.

Request

curl -s "$RELAY/v1/receipts/build-214" \
  -H "Authorization: Bearer $KEY" \
  -H "User-Agent: Herald-Agent/1.0"

{
  "notificationId": "build-214",
  "received": true,
  "receivedAt": "2026-10-02T13:00:04.000Z",
  "queued": false,
  "displayed": true,
  "displayedAt": "2026-10-02T13:00:05.210Z",
  "spoken": true,
  "spokenAt": "2026-10-02T13:00:08.870Z",
  "replied": true,
  "repliedAt": "2026-10-02T13:02:41.402Z",
  "reply": "Ship it.",
  "text": "Ship it.",
  "expectReply": true,
  "suppressed": false
}

The fields are those of The receipt.

Errors

Notes

• The relay keeps an id for 24 hours. After that the receipt is gone and the same id can be sent again as a new notification.
• Receipt and reply reads share one limit of 600 per 10 minutes per key. A 429 carries retryAfterSeconds: 60 and Retry-After: 60.

GET /v1/replies/{notificationId}#

Returns the user's reply to a notification and can wait for it. Use it when you sent expectReply: true and want the answer. With wait, the relay holds the request open until the user answers or the time runs out, so you do not have to poll.

Request

curl -s "$RELAY/v1/replies/build-214?wait=30" \
  -H "Authorization: Bearer $KEY" \
  -H "User-Agent: Herald-Agent/1.0"

Example response

A voice reply:

{
  "notificationId": "build-214",
  "replied": true,
  "repliedAt": "2026-10-02T13:02:41.402Z",
  "reply": "Looks good, ship it.",
  "transcript": "Looks good, ship it.",
  "transcriptNote": "transcribed on the user's Mac; may be imperfect",
  "audioUrl": "https://herald-relay.example.workers.dev/v1/audio/a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718/r_0123456789abcdef01234567.m4a?exp=1790000000&sig=9f2c",
  "audioUrlExpiresInSeconds": 3600,
  "durationSeconds": 4.2,
  "suppressed": false
}

When no reply arrives within wait:

{
  "notificationId": "build-214",
  "replied": false,
  "timedOut": true,
  "suppressed": false
}

Response fields

Errors

Notes

• The answer is 200 in every case. A missing reply is replied: false, not an error.
• The request ends early when the user replies, or when the notification is suppressed with scope all, because no reply can follow.
• A request without wait, or with wait=0, never sets timedOut.
• While a request waits, the Mac's mailbox is awake and counts against the Mac's daily poll seconds, 3000 by default. When that allowance is spent, wait is treated as 0 and the relay answers at once.
• A typed answer is text. A voice answer has transcript and audioUrl. reply holds whichever exists.
• To be told when the user answers instead of polling, subscribe to the reply event.

Status and health#

GET /v1/status#

Tells an agent whether the user's Mac is reachable and whether quiet hours are on. It exposes nothing else about the Mac. Use it before you rely on a quick answer.

Request

No parameters.

curl -s "$RELAY/v1/status" \
  -H "Authorization: Bearer $KEY" \
  -H "User-Agent: Herald-Agent/1.0"

{
  "online": true,
  "lastSeenAt": "2026-10-02T13:14:19.111Z",
  "quietHours": {
    "active": true,
    "until": "2026-10-03T07:30:00Z"
  }
}

Response fields

Errors

Notes

• Herald pings the relay every 5 minutes. online tolerates two missed pings.
• A status request counts toward the Mac's daily request budget but not toward the 600 reads limit.

GET /health#

Reports that the relay is running. It needs no credential and touches no storage, so a monitor can call it.

Request

No parameters.

curl -s "$RELAY/health" -H "User-Agent: Herald-Agent/1.0"

{
  "service": "herald-relay",
  "ok": true,
  "bundle": "3f2a9c0e"
}

Response fields

Notes

• /healthz answers the same way. GET / returns a small HTML page for a person who opened the address, and any other method on / returns this JSON.
• The reply is the same on every host name the relay answers on.

Voice replies#

GET /v1/audio/{deviceId}/{replyId}.m4a#

Downloads the voice message a user recorded as a reply. The audioUrl in a reply or receipt is this address with its signature, so an agent does not build it by hand. The signed link is the credential: the route needs no bearer token and works until the link expires.

Request

curl -s -o reply.m4a "$AUDIO_URL" -H "User-Agent: Herald-Agent/1.0"

Example response

The reply is the audio file itself, with no JSON body. These are its status line and headers.

HTTP/2 200
content-type: audio/mp4
cache-control: private, no-store
content-length: 53214

Errors

Notes

• A link is valid for 3600 seconds from the read that made it.
• The audio is AAC in an m4a container, at most 1 MB. The relay keeps it for 7 days and deletes it earlier when the Mac unpairs.
• A link works only for its own clip. Changing the path invalidates the signature.

Related#

• Relay API: credentials, token shapes and the error format.
• MCP endpoint: the same four actions as MCP tools.
• Events: be told when the user replies instead of polling.
• Limits and errors: every limit and error code.
• Cloud relay: what the relay is and how to set it up.