Device-side endpoints

These are the routes Herald itself uses on a paired Mac: the stream that delivers notifications, the receipts and replies it sends back, the agent keys and connector approvals it manages, and the reply subscriptions it lists. You need this page to implement a relay or a compatible client, or to script what Settings > Cloud does. A cloud agent never calls these routes. Pairing, the list of Macs, and the mailbox summary, usage and status routes are on Pairing and devices.

Every route here needs the device token that POST /v1/pair returns. Examples use $RELAY from the relay API overview and a variable for the device token.

RELAY="https://herald-relay.example.workers.dev"
DEVICE_TOKEN="hrd_..."

Concepts#

One credential. A device route accepts only the device token. An agent key or access token gets 403 wrong_credential. A missing, malformed or unknown token gets 401 unauthorized. A path under /v1/device that no route matches gets 404 not_found with the message no such device endpoint. That includes a path parameter in the wrong shape and a known path with the wrong method.

Receipts. A notification has a lifecycle on the Mac: it is shown, spoken, answered or held back. Herald reports each step as a receipt, over the stream or with POST /v1/device/receipt, and the relay shows it to the agent that sent the notification. A notification has two ids. The agent's own notificationId names it for the agent. The relay's r_ id, 24 hex characters after the prefix, names it for Herald. Every route on this page that takes id takes the relay's id.

Connectors. An agent that connects with OAuth or the device flow does not hold a key you made. It asks to be approved, and Herald shows a banner. The request reaches Herald as a consent message on the stream and in the list of approval requests. Pressing Approve or Deny sends the decision. An approved connector appears in the list of keys with the kind oauth.

Endpoints#

GET /v1/device/stream#

Opens the WebSocket that Herald keeps open to receive notifications and connector requests. It is the only way notifications reach the Mac, and it is outgoing from the Mac, so the Mac listens on no port. The relay allows one stream per Mac: a newer connection closes the older one.

Request

curl -s -i "$RELAY/v1/device/stream" \
  -H "Authorization: Bearer $DEVICE_TOKEN" \
  -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ=="

Example response

The reply is 101 Switching Protocols. The first message on the stream is welcome.

{"type": "welcome", "ttlSeconds": 86400}

Errors

Notes

• On connect the relay sends welcome, then every notification that is waiting and not yet acknowledged, then every open connector request.
• ttlSeconds is how long an undelivered notification waits. It is 86400 unless the relay's owner changed QUEUE_TTL_HOURS.
• Every text message must be at most 16 KB. The relay ignores a larger one, a binary one, or one that is not valid JSON, and sends no error.
• Herald sends the text ping every 300 seconds and the relay answers pong without waking its storage. The Mac counts as online while it has pinged or sent a message in the last 11 minutes.
• The relay closes a stream with code 4000 when a newer one takes its place, and 4001 when the Mac is unpaired.
• Opening the stream does not count toward the daily request budget. Each message Herald sends counts toward wsMessages in GET /v1/device/usage.

Messages from the relay to Herald:

A consent message with redelivered set is sent on a reconnect for a request Herald already showed. Herald updates its list and shows no new banner. A request that arrived while Herald was away is sent once without the flag. When the same client asks again, the relay reuses the request and sends a fresh consent message with the new code, without the flag.

Messages from Herald to the relay:

POST /v1/device/receipt#

Reports what happened to a notification: shown, spoken, replied or held back. Herald sends this as it happens, and the relay passes it to the agent through the receipt and reply endpoints, and to reply subscriptions. The same receipt can be sent as a receipt message on the stream.

Request

reason and scope apply to suppressed:

curl -s -X POST "$RELAY/v1/device/receipt" \
  -H "Authorization: Bearer $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"r_0123456789abcdef01234567","kind":"displayed"}'

{"ok": true}

Errors

Notes

• A displayed, spoken or replied receipt is recorded once. The first time stays: a second displayed does not move the time, and a second reply does not change the stored text.
• A suppressed receipt is not kept once. A later one overwrites the stored reason and scope.
• Every receipt marks the notification as received by the Mac, so the relay stops resending it.
• The first replied receipt also queues the notification.reply event for the sender's subscriptions. The event kind is text when the receipt has text and voice otherwise.
• The field notificationId is accepted in place of id, and it must still hold the relay's r_ id.
• A suppressed receipt with the scope all ends a waiting GET /v1/replies/{notificationId}. With the scope speech the wait continues.

POST /v1/device/reply#

Reports the user's reply. It is the same as sending a replied receipt, and it is the route Herald uses for the Reply and Record buttons.

Request

At least one of text, transcript or a prior audio upload is needed. Limits and trimming are those of POST /v1/device/receipt.

curl -s -X POST "$RELAY/v1/device/reply" \
  -H "Authorization: Bearer $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"r_0123456789abcdef01234567","text":"Ship it."}'

{"ok": true}

Errors

PUT /v1/device/reply/{replyId}/audio#

Uploads the voice message of a reply. Herald uploads the audio first, then sends the reply with its transcript, so the reply can point to the audio. The relay stores the audio in its audio bucket, and the agent downloads it with a signed link from the receipt or reply.

Request

curl -s -X PUT "$RELAY/v1/device/reply/r_0123456789abcdef01234567/audio" \
  -H "Authorization: Bearer $DEVICE_TOKEN" \
  -H "Content-Type: audio/mp4" \
  --data-binary @reply.m4a

{"ok": true, "bytes": 53214}

Errors

Notes

• A replyId that is not r_ and 24 hex characters does not match this route and gets 404 not_found with the message no such device endpoint.
• The relay checks the declared length, the daily count, the body size, the daily bytes and the content type, in that order. A 429 carries retryAfterSeconds and a Retry-After header that run to midnight UTC.
• A second upload for the same notification takes the place of the first.
• The relay keeps stored audio for 7 days.

GET /v1/device/keys#

Lists the agent keys and connector approvals of this Mac, including revoked ones, oldest first. It never returns a secret.

Request

No parameters.

curl -s "$RELAY/v1/device/keys" -H "Authorization: Bearer $DEVICE_TOKEN"

{
  "keys": [
    {
      "id": "0a1b2c3d",
      "name": "build-bot",
      "client": "claude",
      "scope": "notify",
      "kind": "static",
      "createdAt": "2026-10-01T09:30:00.000Z",
      "lastUsedAt": "2026-10-02T13:00:04.000Z"
    },
    {
      "id": "4e5f6a7b",
      "name": "chatgpt",
      "client": "other",
      "scope": "notify",
      "kind": "oauth",
      "displayName": "ChatGPT",
      "createdAt": "2026-10-02T08:00:00.000Z"
    }
  ]
}

Response fields

POST /v1/device/keys#

Makes an agent key. The reply holds the key in full once. Only its hash is stored, so a lost key cannot be read back and has to be replaced.

Request

curl -s -X POST "$RELAY/v1/device/keys" \
  -H "Authorization: Bearer $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"build-bot","client":"claude"}'

Example response

The reply is 201.

{
  "id": "0a1b2c3d",
  "name": "build-bot",
  "client": "claude",
  "scope": "notify",
  "kind": "static",
  "key": "hrk_...",
  "createdAt": "2026-10-01T09:30:00.000Z"
}

Errors

Notes

• A key sends notifications and reads what it sent. It carries no other scope, and the relay refuses to make one.
• A revoked key does not hold its name, so the name can be used again.
• The 20-key limit counts connector approvals as well as keys.

DELETE /v1/device/keys/{keyId}#

Revokes an agent key or a connector approval. A revoked key stops working at once, and a connector's tokens and reply subscriptions end with it. The key stays in the list with a revokedAt time.

Request

curl -s -X DELETE "$RELAY/v1/device/keys/0a1b2c3d" \
  -H "Authorization: Bearer $DEVICE_TOKEN"

{"revoked": true, "id": "0a1b2c3d"}

Errors

Notes

• With purge=1 the reply also holds "purged": true, and the key is not in the list.
• Revoking a key that is already revoked succeeds and changes nothing.
• A key id that is not 8 hex characters does not match this route and gets 404 not_found with the message no such device endpoint.

GET /v1/device/consents#

Lists the connector approval requests of the last day, newest first, up to 20. Herald shows them under Connector approvals.

Request

No parameters.

curl -s "$RELAY/v1/device/consents" -H "Authorization: Bearer $DEVICE_TOKEN"

{
  "consents": [
    {
      "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718aabbccddeeff001122334455",
      "clientId": "hc_3fa91c0de27b45a6d1180123456789ab",
      "clientName": "My cloud agent",
      "redirectHost": "",
      "scope": "notify",
      "code": "482913",
      "status": "pending",
      "createdAt": "2026-10-02T13:00:00.000Z",
      "expiresAt": "2026-10-02T13:10:00.000Z",
      "flow": "device",
      "userCode": "BDFG-HJKM"
    }
  ]
}

Response fields

Notes

• A pending request that has run out is deleted when the Mac reads the list, so expired is never listed. It reaches Herald as a consent_resolved message.
• superseded means the same client asked again, or another Mac decided the request.

POST /v1/device/consent#

Approves or denies a connector request. Herald calls it when the user presses Approve or Deny on the banner. It also closes the same client's open requests on every other paired Mac.

Request

curl -s -X POST "$RELAY/v1/device/consent" \
  -H "Authorization: Bearer $DEVICE_TOKEN" -H "Content-Type: application/json" \
  -d '{"id":"a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718aabbccddeeff001122334455","decision":"approve"}'

{"status": "approved"}

Response fields

Errors

Notes

• Approving makes one connector key for the client. If the same client was approved before, the earlier key is revoked first, so a client holds one key at a time.
• Denying revokes nothing that already works.
• Both decisions send a consent_resolved message on the stream.
• For the browser flow the redirect of an approval carries the one-time code, and the redirect of a denial carries error=access_denied. See OAuth.

GET /v1/device/events#

Lists the reply subscriptions on this Mac. Herald shows them under Reply subscriptions.

Request

No parameters.

curl -s "$RELAY/v1/device/events" -H "Authorization: Bearer $DEVICE_TOKEN"

{
  "restrictedTo": [],
  "subscriptions": [
    {
      "id": "sub_3fa91c0de27b45a6d118",
      "event": "notification.reply",
      "host": "agent.example.com",
      "key": {"id": "4e5f6a7b", "name": "chatgpt", "displayName": "ChatGPT"},
      "createdAt": "2026-10-02T08:05:00.000Z",
      "pending": 0
    }
  ]
}

Response fields

Notes

• restrictedTo lists the hosts in the relay's EVENT_CALLBACK_HOSTS variable. The relay's owner sets that variable. When it is empty, callbacks may go to any public https host.
• Subscriptions do not lapse. They end when the agent unsubscribes, when the connector is revoked, or when you end one. See MCP Events.

DELETE /v1/device/events/subscriptions/{subscriptionId}#

Ends a reply subscription and drops the events still waiting for it. Use it when the user presses End next to a subscription.

Request

curl -s -X DELETE "$RELAY/v1/device/events/subscriptions/sub_3fa91c0de27b45a6d118" \
  -H "Authorization: Bearer $DEVICE_TOKEN"

{"removed": true, "id": "sub_3fa91c0de27b45a6d118"}

Errors

Notes

• The call succeeds when no subscription has that id.
• The connector keeps its approval and can subscribe again.

Related#

• Pairing and devices: pair a Mac, manage the Macs, read the mailbox summary and usage.
• Agent endpoints: what an agent sees of the receipts and replies reported here.
• OAuth and Device flow: how a connector reaches the approval request.
• MCP Events: the subscriptions listed here.
• Limits and errors: every limit and error code.
• Cloud relay: the relay in Settings > Cloud.
• Reply events: be told when the user replies.