RambleRamble
← Back to Ramble

Connect your agent

One short code, and every transcript waits in a small inbox until your agent picks it up.

Pairing

  1. In Ramble on your iPhone, open Settings → Your agent and tap Connect your agent.
  2. Tap Copy and paste the message to your agent. It holds a code like K7QX-MP4D-HN3R that connects one agent and expires in 10 minutes.
  3. 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.

  1. In your agent’s settings, add a custom connector with the URL https://ramble-transcription-proxy.jpoliachik.workers.dev/mcp.
  2. A Ramble page opens. In the Ramble app, open Settings → Your agent → Connect, copy the message, and paste it there.
  3. 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.

Paste to your agent
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/docs

Checking 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.
watcher.sh
#!/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_status is its HTTP status: 2xx means it worked, 0 means no response. If your webhook key changes, send PATCH /agent again 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-Agent and Cookiecan’t be set. Header values are stored only encrypted and never shown again. {"hook": null} removes the hook, and GET /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:00 means 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” from created_at in that offset, and if the moment has passed, treat it as overdue rather than moving it.
  • Duration. duration is 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; deleted counts 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 409 and no token: ask the user for a new code (it expires 10 minutes after it was made). Codes ignore case, spaces, and dashes. name is 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.

StatusMeansDo
401You were disconnected, or the token is wrongStop checking and tell the user. This is the only status that means stop.
400 on /pair/exchangeThe code is wrong or expiredAsk the user for a new code.
409 on /pair/exchangeThe code was already used, maybe by your own earlier tryAsk the user for a new code.
400 elsewhereThe request is malformedFix it. The error message says what's wrong.
403Filtered before it reached the relay, or an endpoint agents can't useSet a User-Agent or use another HTTP client, then retry. Not a token problem.
405Wrong HTTP methodThe error message names the right one.
429Too many requestsWait the seconds in Retry-After, then carry on. Your token still works.
5xx, timeout, dropped connectionTemporaryRetry 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.

curl
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]}'
Python (standard library)
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.dev to 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.