Cloud relay (local)

These endpoints control the cloud relay from this Mac: deploy it to your Cloudflare account, pair this Mac with it, create and revoke the keys agents use, and watch its state. They are what the Settings > Cloud tab calls. Use them to script a relay setup or to let a local agent do it for the user. The examples use the $HERALD and $TOKEN variables from Connect.

What these endpoints manage#

A cloud agent cannot reach your Mac. The relay is a small service in your own Cloudflare account that holds a mailbox for your Mac: agents put notifications in, and Herald, which keeps one outgoing connection to the relay, takes them out. The whole design is explained in Cloud relay.

Four things exist around a relay, and each has endpoints here.

No endpoint returns a secret that was stored earlier. A new agent key is shown once, in the reply that creates it. The Cloudflare token, the pairing secret and the device token can be written or used, never read back.

Show the whole capture

Settings > Cloud with a relay that is paired and online. The address, the agent keys and today's usage shown here come from the endpoints on this page.

Errors shared by the relay routes#

Besides the errors every endpoint shares, the relay routes use these.

A failure reported by Cloudflare during a deploy comes back with Cloudflare's own status and message.

Pair and status#

GET /v1/relay/status#

Returns the pairing, the connection, the agent keys, the Macs on the relay and the most recent notifications that came through it. It is the first call to make: it tells you whether there is a relay and whether it is working.

Request

No parameters.

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

{
  "paired": true,
  "online": true,
  "state": "Online",
  "relayURL": "https://herald-relay.example.workers.dev",
  "mcpURL": "https://herald-relay.example.workers.dev/mcp",
  "deviceId": "d_4f1c2a9e",
  "lastSeenAt": "2026-10-02T13:14:19.111Z",
  "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"
    }
  ],
  "devices": [
    {
      "id": "d_4f1c2a9e",
      "name": "Studio Mac",
      "online": true,
      "lastSeenAt": "2026-10-02T13:14:19.137Z",
      "thisDevice": true,
      "removable": false
    }
  ],
  "log": [
    {
      "id": "r_13cb91ec8efd0eab",
      "key": "build-bot",
      "title": "Build finished",
      "receivedAt": "2026-10-02T13:00:04.000Z",
      "displayed": true,
      "spoken": false,
      "replied": false,
      "duplicate": false
    }
  ],
  "setup": {
    "state": "online",
    "hasToken": true,
    "paired": true,
    "online": true,
    "relayURL": "https://herald-relay.example.workers.dev",
    "mcpURL": "https://herald-relay.example.workers.dev/mcp",
    "workersDevURL": "https://herald-relay.example.workers.dev",
    "customDomainRecommended": true,
    "bundledVersion": "3f2a9c0e",
    "deployedVersion": "3f2a9c0e",
    "updateAvailable": false,
    "steps": []
  }
}

Response fields

Each entry of devices:

Each entry of log:

Notes

• With several Macs on one relay, use devices to tell the user which Mac will show a banner.
• This endpoint never fails for a missing relay. It answers with paired: false.

GET /v1/relay/setup#

Returns where the setup stands as one state, with the facts behind it. Use it to decide the next step: ask for a token, deploy, wait, or report a problem.

Request

No parameters.

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

{
  "state": "online",
  "hasToken": true,
  "paired": true,
  "online": true,
  "relayURL": "https://herald-relay.example.workers.dev",
  "mcpURL": "https://herald-relay.example.workers.dev/mcp",
  "workersDevURL": "https://herald-relay.example.workers.dev",
  "customDomainRecommended": true,
  "bundledVersion": "3f2a9c0e",
  "deployedVersion": "3f2a9c0e",
  "updateAvailable": false,
  "steps": [],
  "usage": {
    "day": "2026-10-02",
    "requests": 34,
    "requestsPercent": 1,
    "notifications": 1,
    "queued": 0,
    "storageBytes": 90112,
    "wsMessages": 6,
    "pollSeconds": 0,
    "audioUploads": 0,
    "audioBytes": 0,
    "budgetExhausted": false
  }
}

Response fields

The state values:

GET /v1/relay/usage#

Returns today's traffic through the relay for this Mac. The relay runs on Cloudflare's free plan, so each Mac has daily limits. Use this to see how close you are. The limits are explained in How the relay works.

Request

No parameters.

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

{
  "day": "2026-10-02",
  "requests": 34,
  "requestsPercent": 1,
  "notifications": 1,
  "queued": 0,
  "storageBytes": 90112,
  "wsMessages": 6,
  "pollSeconds": 0,
  "audioUploads": 0,
  "audioBytes": 0,
  "budgetExhausted": false
}

Response fields

Errors

POST /v1/relay/pair#

Pairs this Mac with the relay at the configured address. Herald asks the relay for a one-time code, redeems it, and stores the device token it receives. Nothing is shown on screen.

You rarely call this yourself: POST /v1/relay/deploy pairs at the end of a deploy. Use it for a relay that Herald did not deploy.

Request

No parameters. Send an empty body.

curl -s -X POST "$HERALD/v1/relay/pair" -H "Authorization: Bearer $TOKEN"

{"paired": true, "code": "482913", "deviceId": "d_4f1c2a9e"}

Response fields

Errors

POST /v1/relay/unpair#

Ends the pairing. The relay wipes this Mac's mailbox, which revokes every agent key and connector and discards waiting notifications and voice replies. Herald forgets the device token.

Request

No parameters.

curl -s -X POST "$HERALD/v1/relay/unpair" -H "Authorization: Bearer $TOKEN"

{"unpaired": true}

Notes

• The relay program stays in your Cloudflare account. Remove it with POST /v1/relay/delete.

Agent keys and connectors#

An agent reaches the relay with one of two credentials. An agent key is a secret string that you create here and paste into the agent. A connector is an agent that signed in through OAuth and that you approved on the Mac; the relay stores it as a key of kind oauth. Both can only send notifications and read back what they sent. See Connect a cloud agent and Connect ChatGPT.

GET /v1/relay/keys#

Lists every agent key and connector of this Mac, including revoked ones. It never returns a secret.

Request

No parameters.

curl -s "$HERALD/v1/relay/keys" -H "Authorization: Bearer $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",
      "displayName": "ChatGPT",
      "client": "other",
      "scope": "notify",
      "kind": "oauth",
      "createdAt": "2026-10-02T08:27:58.940Z",
      "lastUsedAt": "2026-10-02T08:28:03.969Z"
    }
  ]
}

Response fields

POST /v1/relay/keys#

Creates an agent key. The reply holds the key itself and a ready configuration block for the agent. This is the only time the key is shown: the relay keeps only a hash of it.

Request

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

Example response

The status is 201.

{
  "id": "0a1b2c3d",
  "name": "build-bot",
  "client": "claude",
  "scope": "notify",
  "key": "hrk_...",
  "mcpURL": "https://herald-relay.example.workers.dev/mcp",
  "connectorConfig": "claude mcp add --transport http herald https://herald-relay.example.workers.dev/mcp --header \"Authorization: Bearer hrk_...\""
}

Response fields

Errors

DELETE /v1/relay/keys/{id}#

Revokes an agent key or a connector at once. The agent's next request is refused.

Request

curl -s -X DELETE "$HERALD/v1/relay/keys/0a1b2c3d" -H "Authorization: Bearer $TOKEN"

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

Errors

Notes

• Revoking a connector also ends its reply subscriptions.
• The app cloud.<name> and its History stay. Remove them with DELETE /v1/apps/{id}.

GET /v1/relay/connectors#

Lists the connectors that signed in through OAuth, and the requests that are waiting for the user's approval. Use it to tell the user which request belongs to which agent.

Request

No parameters.

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

{
  "connectors": [
    {
      "id": "4e5f6a7b",
      "name": "chatgpt",
      "displayName": "ChatGPT",
      "client": "other",
      "scope": "notify",
      "kind": "oauth",
      "createdAt": "2026-10-02T08:27:58.940Z",
      "lastUsedAt": "2026-10-02T08:28:03.969Z"
    }
  ],
  "pending": [
    {
      "id": "c_7d2e41",
      "clientName": "My cloud agent",
      "expiresAt": "2026-10-02T13:25:00.000Z",
      "userCode": "BDFG-HJKM"
    }
  ]
}

Response fields

Notes

• The 6-digit approval code is never returned. Approving happens on the Mac, in the banner or in Settings > Cloud > Connector approvals.
• No endpoint approves a request.

GET /v1/relay/instructions#

Returns ready-made instructions to give to an agent or its user, with this relay's address filled in.

Request

curl -s "$HERALD/v1/relay/instructions?client=claude" -H "Authorization: Bearer $TOKEN"

{
  "client": "claude",
  "text": "Claude Code / Codex CLI (a static key)\n\nClaude Code:\nclaude mcp add --transport http herald https://herald-relay.example.workers.dev/mcp --header \"Authorization: Bearer <key>\""
}

Errors

Notes

• chatgpt gives the OAuth connector steps, claude and codex give the agent-key steps, and device gives the device-flow sequence for an agent with no browser.

Reply subscriptions#

A connector can ask the relay to call a web address the moment you reply to one of its notifications, so that it does not have to keep asking. That request is a reply subscription. The approval of the connector is what authorises it; nothing more is asked on the Mac. See Reply events.

GET /v1/relay/events#

Lists the live reply subscriptions: which connector is told about replies, and at which host.

Request

No parameters.

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

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

Response fields

Errors

DELETE /v1/relay/events/subscriptions/{id}#

Ends one reply subscription. The connector stays approved and can subscribe again.

Request

curl -s -X DELETE "$HERALD/v1/relay/events/subscriptions/sub_0123456789abcdef0123" \
  -H "Authorization: Bearer $TOKEN"

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

Errors

Set up and deploy#

These endpoints do what the Enable relay sheet does. The order is: get the token page, store the token, deploy. The guided version with screenshots is Set up the cloud relay.

GET /v1/relay/token-url#

Returns a link to Cloudflare's token page with the needed permissions already selected, the reason for each permission, and the steps to tell the user. Herald needs a Cloudflare API token to deploy the relay into the user's own account.

Request

No parameters.

curl -s "$HERALD/v1/relay/token-url" -H "Authorization: Bearer $TOKEN"

Example response

The permissions and steps lists are shortened here.

{
  "url": "https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=%5B%5D&name=Herald%20relay",
  "signUpURL": "https://dash.cloudflare.com/sign-up",
  "permissions": [
    {
      "key": "workers_scripts",
      "type": "edit",
      "title": "Workers Scripts: Edit",
      "why": "upload the relay, switch on its workers.dev address, set its variables and secrets"
    }
  ],
  "steps": [
    "Open the link (a free Cloudflare account is enough; sign up first if you have none)."
  ]
}

Response fields

Notes

• Three permissions are needed to deploy. The other six are used only for a custom domain. The full list is in Set up the cloud relay.

POST /v1/relay/token#

Stores the Cloudflare API token in Herald's secret store on this Mac. The token is sent only to Cloudflare's API and is never returned by any endpoint.

Request

curl -s -X POST "$HERALD/v1/relay/token" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"token\": \"$CLOUDFLARE_API_TOKEN\"}"

{"stored": true}

Errors

POST /v1/relay/deploy#

Deploys the relay into the user's Cloudflare account, waits until it answers, and pairs this Mac with it. If a relay already exists, the same call updates it in place and keeps its data, its keys and its secrets. The request returns when the work is done, which can take a minute.

Request

No parameters.

curl -s -X POST "$HERALD/v1/relay/deploy" -H "Authorization: Bearer $TOKEN" --max-time 300

Example response

The steps list is shortened here to two entries.

{
  "deployed": true,
  "upgraded": false,
  "relayURL": "https://herald-relay.example.workers.dev",
  "workersDevURL": "https://herald-relay.example.workers.dev",
  "paired": true,
  "online": true,
  "warnings": [],
  "steps": [
    {"step": "verifyToken", "title": "Check the API token", "phase": "done", "detail": ""},
    {"step": "upload", "title": "Upload the relay", "phase": "done", "detail": ""}
  ]
}

Response fields

Errors

Notes

• An update never changes the relay's signing secret, so this Mac's pairing and every agent key keep working.
• Deploying over a relay that was deleted creates new secrets. Herald then pairs again by itself and says so in warnings. Agent keys and connectors made before must be created again.

GET /v1/relay/settings#

Returns the advanced settings of the relay: where it is deployed and its limits.

Request

No parameters.

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

{
  "settings": {
    "accountId": "0123456789abcdef0123456789abcdef",
    "workerName": "herald-relay",
    "subdomain": "example",
    "bucket": "herald-relay-audio",
    "audioRetentionDays": 7,
    "queueTTLHours": 24,
    "notificationsPerDay": 500,
    "maxQueue": 100,
    "bodyLimitBytes": 32768,
    "ratePerKey": 60,
    "maxDevices": 5,
    "deviceName": "",
    "pingSeconds": 300,
    "deployedHash": "3f2a9c0e",
    "deployedAt": "2026-10-01T09:20:14.000Z"
  },
  "pairingSecretSet": true,
  "errors": {},
  "redeployed": false,
  "steps": [],
  "warnings": []
}

Response fields

PUT /v1/relay/settings#

Changes advanced settings. A change to a value that lives in the relay program, such as a limit, redeploys the relay, so the request can take a minute.

Request

Relay setting keys#

curl -s -X PUT "$HERALD/v1/relay/settings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" --max-time 300 \
  -d '{"notificationsPerDay": 1000, "deviceName": "Studio Mac"}'

Example response

The reply has the shape of GET /v1/relay/settings. The settings part is shortened here.

{
  "settings": {"notificationsPerDay": 1000, "deviceName": "Studio Mac", "workerName": "herald-relay"},
  "pairingSecretSet": true,
  "errors": {},
  "redeployed": true,
  "steps": [{"step": "upload", "title": "Upload the relay", "phase": "done", "detail": ""}],
  "warnings": []
}

Errors

Notes

• Setting customDomain redeploys and attaches the address. The steps and their effects are in Use a custom domain.
• deployedHash and deployedAt are read-only.

GET /v1/relay/zones#

Lists the domains in the user's Cloudflare account that the stored token can see. Use it to offer a choice for a custom domain.

Request

No parameters.

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

{
  "zones": [
    {
      "id": "0123456789abcdef0123456789abcdef",
      "name": "example.com",
      "status": "active",
      "suggestedHostname": "herald.example.com"
    }
  ]
}

Errors

POST /v1/relay/test#

Tests the whole path. Herald checks that the relay answers, then sends a notification through it with a temporary key and waits for the receipt. The test notification, the key and their traces are removed afterwards.

Request

No parameters.

curl -s -X POST "$HERALD/v1/relay/test" -H "Authorization: Bearer $TOKEN" --max-time 60

{
  "healthy": true,
  "paired": true,
  "online": true,
  "roundTrip": true,
  "receipt": "displayed",
  "detail": "A test notification went through the relay and was shown on this Mac.",
  "browserCheckActive": true
}

Response fields

Errors

Notes

• The test shows a banner titled Relay test for a moment.
• When browserCheckActive is true, agents must send a custom User-Agent header. See Use a custom domain.

POST /v1/relay/delete#

Deletes the relay from the user's Cloudflare account: the program, every mailbox and every key. The storage bucket is deleted when it is empty.

Request

curl -s -X POST "$HERALD/v1/relay/delete" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"confirm": true}'

{"deleted": true, "note": "The bucket herald-relay-audio still holds voice replies and was kept."}

Errors

Notes

• Cloudflare refuses to delete a bucket that still holds files. The note says so when that happens.
• A custom domain's DNS record and rules stay in the Cloudflare account. Delete them there.

Related#

• Cloud relay: what the relay is and how to set it up by hand.
• How the relay works: the security model and the limits.
• Relay API: what the relay itself serves to cloud agents.
• MCP relay tools: the same operations for a local agent.