Connect your agent
One short code, and every transcript waits in a small inbox until your agent picks it up.
Pairing
- In Ramble on your iPhone, open Settings → Your agent and tap Connect your agent.
- Tap Copy and paste the message to your agent. It holds a code like
K7QX-MP4D-HN3Rthat connects one agent and expires in 10 minutes. - Wait for it to connect. Then talk to your watch, and your agent picks up each note.
Your agent can only pick up its own copies of your transcripts. Tap Disconnect on the same screen to cut it off; anything still waiting for it is deleted.
Or add it as a connector
If your agent supports remote MCP servers (often called custom connectors), you can add Ramble there instead of pasting the message. Your agent’s platform then calls Ramble for it, so this also works when the agent’s own sandbox can’t reach ramble-transcription-proxy.jpoliachik.workers.dev.
- In your agent’s settings, add a custom connector with the URL
https://ramble-transcription-proxy.jpoliachik.workers.dev/mcp. - A Ramble page opens. In the Ramble app, open Settings → Your agent → Connect, copy the message, and paste it there.
- You’re back in your agent, connected. It shows up in Your agent like any other, and Disconnect works the same.
The agent gets three tools: list_new_notes (newest first, with a preview), get_note (the full transcript) and mark_handled (removes it from the list). It reads notes when you ask, or on whatever schedule your platform runs it.
Instructions for the agent
This is the whole loop. If your agent asks how the connection works, paste this in.
Ramble connection
Relay: https://ramble-transcription-proxy.jpoliachik.workers.dev
There are two ways to connect. Pick the one your platform supports:
- The API below: you pair with my code and check the inbox yourself.
- A connector: if your platform lets me add a remote MCP server (a "custom
connector", OAuth), tell me to add https://ramble-transcription-proxy.jpoliachik.workers.dev/mcp and paste the same code on
the sign-in page that opens. You then get the tools list_new_notes,
get_note and mark_handled, and can skip steps 1, 2 and 4. This also works
when your sandbox can't reach ramble-transcription-proxy.jpoliachik.workers.dev, because your platform calls
Ramble for you. Mark each note handled once you've dealt with it.
1. Pair. When I give you a code like K7QX-MP4D-HN3R, POST
{"code": "<the code>", "name": "<your name>"}
to /pair/exchange. Save the returned "token" right away: a code gives its
token once. The name is optional and shows in my Ramble app. A 400 means
the code is wrong or expired, and a 409 means it was already used (for
example, a retry after a lost response), so ask me for a new one.
The token is a password to my transcripts: anyone who has it can read and
delete them. Store it the way your platform stores secrets, and keep it out
of chat, memory, and logs.
2. Separate checking from acting. Most checks find nothing, so the cost of this
connection is the empty checks, not the transcripts. Make the check as cheap
as you can: a small script, hook, or scheduled HTTP fetch that runs without
you, calls GET /inbox with "Authorization: Bearer <token>", and wakes you
only when "items" is not empty. Every 1 to 5 minutes is fine for a check
like that. Only if your platform can't run anything without you, schedule
your own run instead. Hourly or even daily is fine (nothing expires for
30 days), and tell me how often you'll check.
If you can receive webhooks (an HTTPS URL that starts a run), also register
it: PATCH /agent with {"hook": {"url": "<your URL>", "headers":
{"Authorization": "<what your webhook needs>"}}}. The relay then pings that
URL when a new note is waiting, and you check, act, and ack as usual.
3. Act. For each item, do what I asked in "transcription". "created_at" is when
I started recording, in my local time, which can be hours before you see it
(my watch may have been offline). Read relative times like "in an hour" or
"tomorrow" from created_at. If that time has already passed, treat it as
overdue and tell me.
4. Ack. POST {"ids": [...]} to /inbox/ack with the ids you handled. That deletes
them. Anything not acked comes back on the next check. If "has_more" is
true, check again right away.
5. Only 401 means stop. 401 means I disconnected you: stop checking and tell
me. A 429 means slow down: wait the seconds in the Retry-After header.
Anything else (403, 5xx, a timeout) is temporary: retry after 2, 5, then
15 seconds, and keep your schedule.
Send a User-Agent header on every request (any name, like my-agent/1.0).
Full reference and examples: https://ramble.watch/docsChecking cheaply
An empty inbox is the common case, so what this connection costs is mostly empty checks. The HTTP request is tiny. Waking a whole agent to make it is not. The cheap shape is a watcher that checks on its own and wakes the agent only when something is waiting:
- Best: a script, hook, or scheduled fetch your platform runs without the model, like the one below. Every 1 to 5 minutes is fine.
- Fallback: if the agent can only run as itself on a schedule, check less often. Hourly or even daily works, since nothing expires for 30 days. Tell the user the interval.
- No polling at all: if your agent has an HTTPS URL that starts a run, register it as a wake-up hook and the relay calls it when something is waiting.
#!/bin/sh
# Run every few minutes from cron, a hook, or any scheduler. Prints the inbox
# only when there's something for the agent; wire that output to whatever
# wakes your agent. Silent otherwise, so empty checks cost nothing.
RELAY=https://ramble-transcription-proxy.jpoliachik.workers.dev
out=$(curl -sS --retry 3 -A "ramble-watcher/1.0" -w '\n%{http_code}' \
"$RELAY/inbox" -H "Authorization: Bearer $RAMBLE_TOKEN") || exit 0
status=$(printf '%s\n' "$out" | tail -n 1)
body=$(printf '%s\n' "$out" | sed '$d')
case "$status" in
200) case "$body" in *'"items":[]'*) exit 0 ;; esac ;; # nothing waiting
401) ;; # disconnected: tell the agent
*) exit 0 ;; # temporary: next run retries
esac
echo "$body"Wake-up hook (optional)
If your platform gives the agent a webhook URL (a webhook-triggered routine or automation), the agent can register it once after pairing. The relay then calls it whenever a new note is waiting, so the agent doesn’t need frequent checks. The user doesn’t set anything up in the app.
PATCH /agent
Authorization: Bearer rmba_…
{"hook": {"url": "https://your-platform.example/run/abc",
"headers": {"Authorization": "Bearer <your webhook key>"}}}
→ {"name": "My agent",
"hook": {"url": "https://your-platform.example/run/abc", "header_names": ["Authorization"],
"last_ping_at": "2026-11-06T09:12:00.000Z", "last_status": 200}}
Each ping the relay sends (POST, with your headers):
{"event": "ramble.notes_waiting",
"text": "New Ramble notes are waiting. Pull them from …/inbox …",
"pull_url": "https://ramble-transcription-proxy.jpoliachik.workers.dev/inbox"}- Test ping. Registering sends one ping right away with
"event": "ramble.test"and the text “Ramble test ping: your wake-up hook works. Nothing new to pick up, no action needed.”last_statusis its HTTP status: 2xx means it worked, 0 means no response. If your webhook key changes, sendPATCH /agentagain with the new one. - No transcript in the ping. No text, note ids, or counts. When pinged, check the inbox, act, and ack as usual.
- One ping per batch. After a ping, the next waits until the agent checks the inbox, or 10 minutes pass, so a burst of notes is one run.
- Best effort. One try, a 5-second timeout, no redirects, sent with
User-Agent: Ramble-Relay/1 (+https://ramble.watch/docs). Keep a slow scheduled check (daily is fine) as a backup. - Limits.
https://with a public hostname, up to 8 headers and 4 KB.Host,Content-Type,Content-Length,Connection,Transfer-Encoding,User-AgentandCookiecan’t be set. Header values are stored only encrypted and never shown again.{"hook": null}removes the hook, andGET /agentshows what’s registered, with header names only.
API
Three JSON calls. Every path is relative to https://ramble-transcription-proxy.jpoliachik.workers.dev. A check returns up to 50 items, oldest first.
POST /pair/exchange
{"code": "K7QX-MP4D-HN3R", "name": "My agent"}
→ 201 {"token": "rmba_…"} (the same code again: 409 "code_used", no token)
GET /inbox
Authorization: Bearer rmba_…
→ {"items": [{"id": 41, "recording_id": "6F1C…", "created_at": "2026-11-01T14:00:00-05:00",
"received_at": "2026-11-02T00:00:00.000Z", "duration": 8.2,
"transcription": "Remind me to book the dentist."}],
"has_more": false}
POST /inbox/ack
Authorization: Bearer rmba_…
{"ids": [41]}
→ {"deleted": 1}- Timestamps.
created_atis when the user started recording, taken from the watch or iPhone clock, with that device’s UTC offset (so-05:00means the user is 5 hours behind UTC).received_atis when the relay accepted the audio, in UTC. The two can be hours apart if the watch was offline. Read relative times like “tomorrow” fromcreated_atin that offset, and if the moment has passed, treat it as overdue rather than moving it. - Duration.
durationis the length in seconds, measured by the relay. - Acks.1 to 500 integer ids per call. Acking an id that’s already gone, or isn’t yours, does nothing;
deletedcounts what was actually removed. Anything never acked comes back on every check and is deleted 30 days after it was made. - Pairing. A code makes one connection and gives its token once, so save it right away. Sending a used code again, even after a lost response, gets
409and no token: ask the user for a new code (it expires 10 minutes after it was made). Codes ignore case, spaces, and dashes.nameis optional, 1 to 40 characters; an invalid one is dropped.
Tokens and connections
- The token doesn’t expire. It works until the user disconnects the agent in Ramble.
- The token reads and acks only your own copies. It can’t pair agents, upload notes, or read anyone else’s.
- Each code makes its own connection, so several agents can be connected at once. Each gets its own copy of every transcript, and acking deletes only your copy. Pairing a new agent leaves the others alone.
- You get notes that reach the relay after you paired. Notes with no speech go to no one. Notes from the watch reach you without the iPhone nearby.
- The user sees every connected agent in Settings → Your agent, with its name (if it sent one), when it last checked in, how many notes are waiting for it, and whether its wake-up hook is answering.
Making requests
Send a User-Agent. Any name works, like my-agent/1.0. Some HTTP stacks get filtered before they reach the relay; Python’s built-in urllib is one, and gets a 403 (error code: 1010). curl, requests, httpx, and fetch are fine as they are. If you see 403s or dropped connections with a valid token, set a User-Agent or switch clients.
| Status | Means | Do |
|---|---|---|
| 401 | You were disconnected, or the token is wrong | Stop checking and tell the user. This is the only status that means stop. |
| 400 on /pair/exchange | The code is wrong or expired | Ask the user for a new code. |
| 409 on /pair/exchange | The code was already used, maybe by your own earlier try | Ask the user for a new code. |
| 400 elsewhere | The request is malformed | Fix it. The error message says what's wrong. |
| 403 | Filtered before it reached the relay, or an endpoint agents can't use | Set a User-Agent or use another HTTP client, then retry. Not a token problem. |
| 405 | Wrong HTTP method | The error message names the right one. |
| 429 | Too many requests | Wait the seconds in Retry-After, then carry on. Your token still works. |
| 5xx, timeout, dropped connection | Temporary | Retry after 2, 5, then 15 seconds. Keep your schedule. |
Errors are JSON: {"error": "..."}, with a "reason" code where it helps (like code_used). Every call except POST /pair/exchange is safe to retry; a code works once. Agent calls and pairing have no rate limit; if you ever get a 429, wait the seconds in Retry-After.
RELAY=https://ramble-transcription-proxy.jpoliachik.workers.dev
# Pair (once; the code works once, so no --retry). Save the token.
curl -sS -X POST "$RELAY/pair/exchange" \
-H "Content-Type: application/json" \
-d '{"code": "K7QX-MP4D-HN3R", "name": "My agent"}'
# Check
curl -sS --retry 3 "$RELAY/inbox" -H "Authorization: Bearer $TOKEN"
# Ack what you handled
curl -sS --retry 3 -X POST "$RELAY/inbox/ack" -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"ids": [41]}'import json, time, urllib.error, urllib.request
RELAY = "https://ramble-transcription-proxy.jpoliachik.workers.dev"
def call(method, path, body=None, token=None):
# Python's default urllib User-Agent is blocked at the network edge. Set your own.
headers = {"User-Agent": "my-agent/1.0", "Content-Type": "application/json"}
if token:
headers["Authorization"] = f"Bearer {token}"
data = json.dumps(body).encode() if body is not None else None
for wait in (2, 5, 15, None):
try:
req = urllib.request.Request(RELAY + path, data=data, headers=headers, method=method)
with urllib.request.urlopen(req, timeout=20) as res:
return json.load(res)
except urllib.error.HTTPError as err:
if err.code == 429 and wait is not None:
time.sleep(int(err.headers.get("Retry-After", "60")))
continue
if err.code < 500 or wait is None:
raise # 400/409: bad, expired or used code. 401: the user disconnected you.
except OSError: # timeout or dropped connection
if wait is None:
raise
time.sleep(wait)
# Once; save the token. A code gives its token once: a 409 here means ask for a new code.
pair = {"code": "K7QX-MP4D-HN3R", "name": "My agent"}
token = call("POST", "/pair/exchange", pair)["token"]
inbox = call("GET", "/inbox", token=token)
for item in inbox["items"]:
print(item["transcription"]) # handle it
if inbox["items"]:
call("POST", "/inbox/ack", {"ids": [i["id"] for i in inbox["items"]]}, token=token)Which way to connect
Ramble can deliver to an agent three ways. None is better in general; pick what your agent supports, or use more than one.
- Relay API (this page). The agent pulls. The relay holds each transcript for up to 30 days until the agent acks it, so nothing is lost if the agent is down for a while. The agent needs to make outbound HTTPS calls on a schedule, or have a wake-up hook.
- Connector (MCP). The same inbox, read through tools instead of HTTP calls. No code or token handling for the agent, and it works from sandboxes that block ramble-transcription-proxy.jpoliachik.workers.dev. The agent reads notes when it runs; nothing wakes it.
- Webhook. The iPhone POSTs each transcript to your HTTPS URL once it has it. There’s no polling. If the URL is down, Ramble tries 3 times in total (30 seconds, then 2 minutes apart), then marks the note “Didn’t send” and the user can retry it. Best when the agent has an always-on URL that wakes it.
Delivery timing
A note goes from the watch (or iPhone) straight to Ramble’s server, is transcribed there, and waits for your agent. The watch sends over the iPhone, Wi-Fi, or cellular, whichever it has. Most notes are ready within seconds of the upload. Some take longer:
- No connection. Notes wait on the watch and send once it has one.
- Away from the iPhone. The watch sends while the app is open or soon after a recording stops. In Low Power Mode, watchOS turns off Wi-Fi and cellular away from the iPhone, so notes wait until the iPhone is back or the app is opened.
- In the background. watchOS decides when background uploads run, so a note can wait for the next window or for the app to open.
- Transcription services down. Ramble keeps retrying for up to 20 hours before it gives up on a note.
So notes can arrive late and out of order. Go by created_at, not arrival time, and don’t read an empty inbox as “nothing was recorded”. A late note isn’t lost: the watch keeps each one until Ramble’s server has it.
Platform notes
Everything above works for any agent. These are the specifics we know about.
- Muse. Use a hook: a small script watches the inbox and wakes the agent when something arrives. Avoid a scheduled agent run every few minutes.
- Grok Bot. Add a routine with a webhook trigger, and register its URL and key as a wake-up hook with the header
Authorization: Bearer <key>. The routine’s Webhook section shows both. The key lets anyone start that routine, so give it to Grok through a secure secret card rather than ordinary chat. Add a daily scheduled check as a backup. Each routine run uses Grok usage, so avoid a schedule every few minutes. - Agents in a sandbox with a network allowlist. Add
ramble-transcription-proxy.jpoliachik.workers.devto the allowed hosts, or every request fails before it leaves the sandbox. If you can’t change the allowlist, add Ramble as a connector instead.
What the relay keeps
Ramble's server is a relay, not an archive. Your audio is sent to a transcription provider and deleted as soon as the transcript is ready. Transcripts are deleted when your agent picks them up, or after 30 days. Your full history lives only on your iPhone. Ramble also keeps basic usage stats for each note, like its length and whether it came from your watch or iPhone, under a random ID. Never your audio or your words.
Every detail is in the privacy policy.