Developers

The OpenAPI file, the MCP registry entries, examples and a Claude Code plugin are also on GitHub, which is where an issue about any of this goes.

The address and the secret

Each connection has its own address and its own secret:

https://api.routinerun.com/v1/in/<connection id>
Authorization: Bearer rr_…

The secret is shown in the app, never by the relay, which keeps only a fingerprint of it. Every request below goes to the address with one of the paths after it, and a JSON body. Tools that already speak another format can send it as they are: see [From other tools](#from-other-tools).

There is no account and no API key for the whole service: an address reaches the one phone that made it, and nothing else. Removing the connection in the app stops the address at once.

What you can send

What you can read

A read is answered by the phone, so it needs the phone reachable; one that does not answer in about 20 seconds is 504 phone_did_not_answer.

A routine is found by its id, or by its name in any case. Two routines with the same name are neither.

For example:

curl -X POST https://api.routinerun.com/v1/in/<connection id>/runs \
  -H "Authorization: Bearer rr_…" \
  -H "content-type: application/json" \
  -d '{"routine": "Morning"}'

What comes back

Every request is answered at once with 202 and a command id:

{"command": "896ea5dc-1477-4edd-8a77-18333032f8f6", "accepted": true}

202 means the relay handed it to Apple for the phone, not that it was done. The phone is the only place that knows the routines, so only the phone can say. Ask it:

GET /v1/in/<connection id>/commands/<command id>

status is one of the words below, and where the command started or found a run, run is its id — what /runs/{run}/… takes next:

{"command": "896ea5dc-…", "status": "done", "run": "3f0c2b1e-…"}

How long a command waits

A command is not done if the phone gets it after this long:

On iOS 27 with the Routine Run bridge, a command is carried out within seconds, with the phone locked. On iOS 26, or without the bridge, it is carried out when the person taps the notification or opens the app.

Errors

An address belongs to the copy of the app that made it. When a different build replaces it on the phone — a TestFlight build over one from Xcode, or the other way round — the phone gets a new push token, and older addresses answer 410 or are accepted and never arrive. Make the connection again on the phone and use the new address and secret.

MCP

The same connection, for an assistant: https://api.routinerun.com/mcp, Streamable HTTP without sessions. Sign-in is OAuth 2.1 with PKCE (S256), clients registered dynamically or named by a client metadata URL; the metadata is at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. Signing in shows a code the person types on their phone, or offers a demo library. How each assistant adds it: Connect Claude, ChatGPT and others.

start_run, start_new_run and plan_run take ask_first: the run then waits in In hand for the person's Start, and the receipt is asked until they answer — done or refused. A connection set to Ask before starting does this for every run. get_run carries the run's notes and values only where the person has turned on Read notes and values for that assistant. The server also offers prompts — review_my_week, plan_tomorrow, checklist_now, tidy_a_routine, where_am_i — which clients show as commands.

Reads are answered by the phone, so they need it reachable; a phone that does not answer in about 20 seconds is said to have not answered.

Writing a routine, with no sign-in

https://api.routinerun.com/mcp/public is a second MCP server for an assistant helping somebody who has connected nothing, or does not have the app yet. Nothing on it is anybody's, so it needs no sign-in.

The routine sent to routine_link is turned into a link and not kept. 60 calls a minute from one address.

PagerDuty

In PagerDuty, add a Generic Webhook (V3) subscription to the service, with the address followed by /pagerduty and a custom header Authorization set to Bearer and the secret. An incident's title becomes the event's title and its id the event's id, so a page that is sent twice starts one run.

From other tools

These tools send to the address as they are, with nothing written for Routine Run on their side. Each event goes to the connection's Sources like any other, so which routine it starts is set on the phone — or said by the alert itself, where it says routine.

A notification that something has cleared — an Alertmanager or Grafana group that resolved, an Events API resolve or acknowledge — is answered and not passed on: nothing on the phone answers a recovery, and passed on it would read as a second page.

A repeat of the same alert within five minutes is one event (the phone's own policy, which can be changed). A repeat after that, while the run it started is still going, is queued behind it rather than ending it. If a tool repeats an unresolved alert every few hours, give the Routine Run route a long repeat interval.

Prometheus Alertmanager

receivers:
  - name: routinerun
    webhook_configs:
      - url: https://api.routinerun.com/v1/in/<connection id>/alertmanager
        http_config:
          authorization:
            credentials: rr_…
route:
  routes:
    - receiver: routinerun
      matchers: [severity="page"]
      repeat_interval: 24h

The title is [FIRING:2] HighLatency, the body the summary and description annotations, and the event's id the group's labels, so the run is called after the group. An annotation routine: When something breaks on the alert rule starts that routine whatever the Sources say.

Grafana

Alerting › Contact points › Webhook. URL: the address followed by /grafana. Under Optional settings, Authorization header scheme Bearer and credentials the secret. Read as Alertmanager's, with Grafana's own title.

Anything that pages PagerDuty

Alertmanager, Grafana, Uptime Kuma and Zabbix let the PagerDuty address be changed, and then the secret goes where the integration key goes:

payload.summary is the title, custom_details the body, dedup_key the event's id. custom_details.routine names the routine to start.

Uptime Kuma, Healthchecks and other webhooks

Any tool with a plain webhook works with /events and a header. Uptime Kuma: Notification type Webhook, Post URL the address followed by /events, body application/json, and Additional Headers {"Authorization": "Bearer rr_…"}; its msg becomes the title. Healthchecks: integration Webhook, method POST, the same URL and header, and any body — its first line is the title.

Apprise, and everything built on it

jsons://api.routinerun.com/v1/in/<connection id>/events?+Authorization=Bearer%20rr_…

A script

curl https://api.routinerun.com/v1/in/<connection id>/events \
  -H "Authorization: Bearer rr_…" \
  -d "Backup failed on nas01"

What the relay keeps

The connection's address and name, when it was last used, a token for reaching the phone, and a fingerprint of the secret. Not the body of anything you send: it is passed to the phone and not kept, and Apple holds it until the phone is reachable, a day at most. A command too long for one push waits on the relay sealed under a key that goes only to the phone, until the phone takes it or the command expires: an hour for a run, a day for anything else. The phone's answer, one word, is kept for about an hour. The privacy page says the rest.

The whole of it in OpenAPI: openapi.json.