Doku

Frag, wen du brauchst, von deinem Agenten aus.

Dein Agent beschreibt, was er braucht (ein Formular, eine Umfrage oder ein Ja oder Nein), und bekommt einen Link zurück: für eine Person, für jede Person einer Gruppe oder für alle, mit denen du ihn teilst. Die Leute öffnen ihn auf dem Handy, ohne Anmeldung, und ihre Antworten kommen als validiertes JSON zu dir zurück.

Anfrage erstellen. Rufe createRequest mit einem JSON Schema für ein Formular oder mit einer Begründung für eine Freigabe auf.
Link senden. Übergib sendEmail: true, und wir schicken ihn per E-Mail an jede namentliche Person. Oder verschicke ihn über einen Kanal, den du schon hast (E-Mail, Chat oder SMS), oder poste einen offenen Link, wo du willst.
Antwort erhalten. Bei Builder und Pro bekommt dein MCP-Client jede Antwort sofort per Push. Sie kommt außerdem an deinem Webhook an, per E-Mail mit notifyEmail, oder du liest sie mit getStatus.

Dieselben Tools gibt es auf zwei Wegen: als MCP-Server für Agenten, die MCP sprechen, und als REST API für alles andere. Agenten können diesen Leitfaden in llms.txt lesen.

Schnellstart

Vom API-Schlüssel zur Antwort einer Person in vier Schritten.

1API-Schlüssel holen

Melde dich an mit deiner E-Mail-Adresse und kopiere den Schlüssel aus dem Dashboard. Er beginnt mit sk_live_; bewahre ihn auf deinem Server auf. Du nutzt Claude Code, Codex oder einen anderen MCP-Client? Überspring das: Füge den Server per URL hinzu und melde dich im Client an.

2Anfrage erstellen

Diese Anfrage fragt Jordan nach einer Lieferadresse und einem Liefertermin. Das Schema ist einfaches JSON Schema; was unterstützt wird, steht unter Formularschema.

3Link senden

Die Antwort enthält einen Link pro Person in links[] (oder eine einzelne url für einen offenen Link). Mit "sendEmail": true schicken wir jeder namentlichen Person mit E-Mail-Adresse ihren eigenen Link per E-Mail, im Namen deines Kontos. Das email jedes Links sagt, was passiert ist: "sent", "failed" (die Anfrage existiert trotzdem; rufe später remind auf), "limit" (die E-Mail-Limits des Plans sind erreicht), "no address" oder "off". Den Rest schickst du, wie du willst: per E-Mail, Chat oder SMS.

4Antwort erhalten

Wenn Jordan abschickt, erhält dein webhookUrl ein response.created-Ereignis mit den Daten, bereits gegen dein Schema geprüft. Kein Webhook? Rufe getStatus mit der requestId auf, setze notifyEmail und wir schreiben dir, wenn alles erledigt ist, oder abonniere bei Builder und Pro über MCP, und dein Agent erfährt sofort, wenn Jordan antwortet. Siehe Antworten erhalten.

POST/v1/requests

curl https://runitby.app/v1/requests \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d @request.json

request.json

{
  "mode": "form",
  "title": "Shipping details",
  "requester": "Ava (the Acme support agent)",
  "audience": { "kind": "named", "recipients": [{ "name": "Jordan Lee", "email": "jordan@example.com" }] },
  "schema": {
    "type": "object",
    "properties": {
      "address": { "type": "string", "title": "Street address" },
      "deliveryDate": { "type": "string", "format": "date", "title": "Delivery date" }
    },
    "required": ["address", "deliveryDate"]
  },
  "expiresIn": "48h",
  "sendEmail": true,
  "webhookUrl": "https://example.com/hooks/runitby",
  "metadata": { "ticket": "T-1042" }
}

Antwort · 201

{
  "requestId": "req_8fK2…",
  "links": [{ "recipientId": "rcp_3Qa…", "name": "Jordan Lee", "url": "https://runitby.app/f/Xc81…", "email": "sent" }],
  "expiresAt": "2026-11-14T10:00:00.000Z"
}

Authentifizierung

Jeder MCP- und REST-Aufruf sendet einen API-Schlüssel als Bearer-Token. Derselbe Schlüssel funktioniert für beides. Ein fehlender oder widerrufener Schlüssel führt zu 401. Es gibt zwei Wege, einen zu bekommen.

Im MCP-Client anmelden

Füge https://runitby.app/mcp ohne Schlüssel hinzu, und der Client meldet dich per OAuth an: Ein Browser öffnet sich, du gibst deine E-Mail-Adresse ein, und der Anmelde-Link bringt dich zu einer Seite zurück, die dich bittet, die App zuzulassen. Zum ersten Mal hier? Derselbe Link legt dein Konto an. Die App hält dann einen eigenen Schlüssel mit ihrem Namen, den du unter Schlüssel widerrufen kannst.

Claude Code: Führe den Befehl rechts aus, gib dann in Claude Code /mcp ein und wähle die Authentifizierung.
Codex: Führe codex mcp add aus, dann codex mcp login.
Claude (Web und Desktop): Einstellungen, Konnektoren, Benutzerdefinierten Konnektor hinzufügen, und füge die URL ein.
Andere Clients, die MCP-Autorisierung unterstützen: Füge die URL ohne Header hinzu.

Schlüssel im Dashboard erstellen

Für die REST API, Skripte und Clients, die nur einen Header akzeptieren: Erstelle und widerrufe Schlüssel im Dashboard und sende den Schlüssel im Authorization-Header.

Die Tarife zählen beides getrennt. Free enthält einen Schlüssel und eine verbundene App, Builder je fünf, Pro so viele, wie du brauchst.

Beispiele in einer Datei mit einem Schlüssel: Vercel AI SDK, Mastra, LangChain.js und das Claude Agent SDK.

Tools und Endpunkte

Jedes MCP-Tool hat einen REST-Endpunkt mit derselben Eingabe und Ausgabe. Die API-Referenz listet jedes Feld auf.

MCP-Tool	REST	Was es macht
`createRequest`	POST /requests	Erstellt ein Formular oder eine Freigabe und liefert die Links, auf Wunsch für dich per E-Mail verschickt.
`previewRequest`	POST /requests/preview	Screenshots und Prüfung dessen, was die Person sehen wird. Erstellt nichts.
`getStatus`	GET /requests/{id}	Status, Entscheidung und alle bisherigen Antworten.
`listRequests`	GET /requests	Deine Anfragen, neueste zuerst. Filtere nach Modus oder Status; blättere mit cursor.
`updateRequest`	PATCH /requests/{id}	Ändert Inhalte, fügt Empfänger hinzu oder setzt ein neues Ablaufdatum.
`remind`	POST /requests/{id}/remind	Schickt den Link per E-Mail an alle, die noch nicht geantwortet haben.
`closeRequest`	DELETE /requests/{id}	Nimmt keine Antworten mehr an.

Formulare und Freigaben

Jede Anfrage hat einen mode:

"form": Daten sammeln. Du sendest ein schema; die Person bekommt ein daraus gebautes Formular, und du erhältst ein Objekt zurück, das dazu passt.
"approval": Eine Entscheidung einholen. Du sendest approval.reason; jede Person bekommt eine Karte mit Freigeben und Ablehnen (oder deinen eigenen Bezeichnungen) und einem optionalen Kommentar. Du erhältst jede Entscheidung und eine Gesamt-verdict.

Beide akzeptieren einen title (bis zu 120 Zeichen), eine optionale requester-Zeile, die sagt, wer fragt, eine locale für die Seite und ihre E-Mails ("en", "es", "pt", "fr", "de", "it", "ja" oder "zh", oder mit Region wie "es-AR" für Datumsangaben) und metadata, die in jedem Webhook und Status unverändert zurückkommen. Schreibe Titel und Fragen in derselben Sprache.

Wer antwortet

audience bestimmt, wer einen Link bekommt.

kind	Du erhältst	Geeignet für
`"named"`	`links[]`, einen pro Person in `recipients` (1 bis 50, jeweils `{ name, email?, phone? }`)	Antworten, die du jemandem zuordnen musst. Freigaben müssen namentlich sein. Mit einer E-Mail-Adresse sind `sendEmail`, Erinnerungen und E-Mail-Codes möglich.
`"open"`	Eine `url`, die jeder öffnen kann	Anmeldungen und Umfragen. `maxSubmissions` begrenzt die Antworten (Standard 1).

Wofür du es nutzen kannst

Ein Modus und eine Zielgruppe decken das meiste ab, wofür du sonst einen Formular-Builder, eine Umfrage, eine Terminplanungs-App oder einen E-Mail-Verlauf brauchst.

Du willst	Anfrage
Angaben einer Person: eine Lieferadresse, Kundenaufnahme, einen Buchungstermin	`"form"`, namentlich, ein Empfänger
Eine Umfrage, Abstimmung, Feedback oder Anmeldungen von beliebigen Leuten	`"form"`, offen mit `maxSubmissions`. Poste die eine `url`, wo du willst; `getStatus` liefert jede Antwort, die dein Agent zusammenfassen kann.
Zusagen, Verfügbarkeit, Schichtvertretung oder Check-ins einer bekannten Gruppe	`"form"`, namentlich (bis zu 50), damit jede Antwort zugeordnet ist und `remind` bei den Übrigen nachhakt
Freigaben, Abnahmen und Abstimmungen	`"approval"` mit einer `policy`; füge `verify: "email"` für Geld, Zugriff oder Löschung hinzu

Status und Ablauf

status	Bedeutet
`pending`	Noch niemand hat geantwortet.
`partial`	Einige der namentlichen Personen haben geantwortet, andere nicht.
`complete`	Alle haben geantwortet, `maxSubmissions` wurde erreicht oder eine Freigabe hat ihre Entscheidung.
`expired`	Die Zeit des Links ist abgelaufen.
`closed`	Du hast `closeRequest` aufgerufen.

Ablauf. expiresIn akzeptiert "30m", "48h", "7d" oder Sekunden. Der Standard sind 7 Tage, das Maximum 90.

Eine Anfrage ändern. updateRequest ändert Titel, Schema, Abschnitte, Begründung oder Design, bis die erste Antwort eintrifft. Empfänger hinzufügen, ein neues Ablaufdatum setzen (ab jetzt gezählt) und notifyEmail ändern funktionieren, bis die Anfrage abgeschlossen, abgelaufen oder geschlossen ist. Hinzugefügte Empfänger bekommen keine E-Mail; schick ihre Links oder rufe remind mit ihren recipientIds auf.

Erinnerungen. remind schickt den Link per E-Mail an namentliche Personen, die noch nicht geantwortet haben und eine E-Mail-Adresse haben, höchstens einmal alle 24 Stunden pro Person. Die sendEmail-E-Mail zählt als erste.

Antworten erhalten. Nutze einen Weg oder kombiniere mehrere:

webhookUrl: Dein Server bekommt jede Antwort, sobald sie eintrifft. Siehe Webhooks.
notifyEmail: Wir schicken deinem Konto eine Zusammenfassung und einen Link zur Anfrage im Dashboard: "each" bei jeder Antwort (bis die E-Mail-Limits des Plans erreicht sind, danach nur noch zum Abschluss) oder "complete" einmal, wenn sie abgeschlossen wird oder abläuft. E-Mails zu Freigaben enthalten die Entscheidung und den Kommentar; Formularantworten bleiben im Dashboard. Standardmäßig aus; updateRequest kann das ändern.
getStatus mit wait: Hält den Aufruf bis zu 25 Sekunden offen (REST: ?wait=25) und antwortet, sobald jemand antwortet oder sich der Status ändert. Ruf ihn erneut auf, um weiter zu warten.
MCP-Push (Builder und Pro): Jede Anfrage ist die MCP-Ressource runitby://requests/{requestId}, verlinkt von createRequest; Lesen liefert dasselbe wie getStatus. Bei Builder und Pro können Clients mit dem Protokoll vom 2026-07-28 per subscriptions/listen abonnieren und bei jeder Antwort oder Statusänderung notifications/resources/updated bekommen, mit einem gleichzeitig offenen Abonnement bei Builder und bis zu drei bei Pro. Bei Free antwortet subscriptions/listen mit einem Fehler, der die anderen Wege nennt, Antworten zu erhalten.

Formularschema

Einfaches JSON Schema mit type: "object" ganz oben und bis zu 40 Feldern. required[] wird durchgesetzt, und title und description werden zu Label und Hilfetext.

Typ	Schlüsselwörter
`string`	`format` (email, date, time, date-time, tel, uri, duration), `minLength`, `maxLength`, `pattern`
`number`, `integer`	`minimum`, `maximum`
`boolean`	`const: true` ergibt ein Einwilligungsfeld, das angekreuzt werden muss
`enum`	Eine feste Liste von Auswahlmöglichkeiten
`array`	Aus Primitiven oder aus einem enum; `minItems`, `maxItems`

Hinweise. Lege Optionen pro Feld in "x-runitby" ab: widget, placeholder, help, columns (1 oder 2), step und currency.

Abschnitte. Gruppiere Felder mit sections: [{ title, fields: [...] }] neben dem Schema.

Verschachtelte Objekte (außer dem Ortsfeld), oneOf, anyOf, allOf und $ref werden mit einer Meldung abgelehnt, die sagt, was zu ändern ist. Felder, die nach Passwörtern, PINs, Kartennummern, CVVs, Sicherheitscodes, Sozialversicherungsnummern oder Einmalcodes fragen, werden abgelehnt.

Feldtypen

Vorgefertigte Felder für Dinge, die Leute ungern eintippen. Jedes ist normales JSON Schema plus ein widget, sodass die Antwort wie jedes andere Feld validiert wird.

Feld	Schema	Antwort
Datum	string, format date	"2026-11-12"
Uhrzeit	string, format time; step = Minuten (1–60)	"14:30"
Datum und Uhrzeit	string, format date-time	"2026-11-12T14:30:00-08:00"
Dauer	string, format duration	"PT1H30M"
Zeitfenster	array of date-time enum, widget slots	die gewählten Zeiten
Datumsbereich	array of 2 dates, widget daterange	["2026-11-12", "2026-11-15"]
Ort	object, widget location	{ latitude, longitude, accuracy }
Geldbetrag	number, currency "USD"	1200
Schieberegler, Bewertung	number oder integer; slider braucht minimum und maximum	7
Chips, Radio, Select	enum (chips akzeptiert auch ein array of enum)	"M"
Rangfolge	array of enum, widget rank	alle Optionen, in der Reihenfolge der Person
Ja oder Nein	boolean, widget yesno	true
Farbe	string, widget color	"#C2410C"
Land	string, widget country	"US" (ISO 3166-1)
Sprache	string, widget language	"es-AR" (BCP 47)
Zeitzone	string, widget timezone	"America/New_York"

Füge einem Länder- oder Sprachfeld ein enum hinzu, um die Auswahl einzuschränken.

Vorschau

previewRequest akzeptiert dieselben Formular- oder Freigabefelder wie createRequest (ohne Zielgruppe, Ablauf, Webhook oder Metadaten) und liefert Screenshots mit 390 px und 1280 px Breite sowie lint[] mit allem, was schlecht lesbar sein wird. Es wird nichts erstellt.

Übergib sampleData, um das ausgefüllte Formular zu sehen, und viewports, um nur eine Größe zu bekommen. Erstelle zuerst eine Vorschau, wenn dasselbe Formular oft verschickt wird.

Designs

theme lässt die Seite wie dein Produkt aussehen. Ohne es sind die Seiten dunkle Schrift auf warmem Weiß, Figtree mit Fraunces-Überschriften, runde Ecken.

Schlüssel	Werte
`accent`, `background`, `surface`, `text`	Hex-Farben
`font`, `headingFont`	system, Figtree, Geist, Inter, DM Sans, Manrope, Work Sans, Space Grotesk, IBM Plex Sans, Fraunces, Lora, Source Serif 4
`radius`	sharp, soft, round
`density`	compact, comfortable
`layout`	stacked (alle Felder auf einer Seite) oder single (eine Frage nach der anderen)
`logoUrl`	Dein Logo
`heroText`, `thankYou`	Die Begrüßung über dem Formular und die Nachricht nach dem Absenden

Freigabeoptionen

Freigaben brauchen eine namentliche Zielgruppe: Jede Person bekommt ihren eigenen Link, sodass jede Entscheidung ihr zugeordnet ist. Die Entscheidung lautet "approved", "declined" oder "expired", wenn niemand rechtzeitig entschieden hat; nie ein stilles Ja.

approval-Feld	Standard	Hinweise
`reason`erforderlich		Worum du bittest, bis zu 300 Zeichen.
`detail`		Kontext unter der Begründung, bis zu 1.000 Zeichen.
`policy`	"all"	`"any"`, `"all"`, `"majority"` oder `{ n }`: wie viele Freigaben nötig sind.
`options`	Freigeben, Ablehnen	Zwei bis vier Bezeichnungen; die erste zählt als Freigabe. Entscheidungen kommen in snake_case zurück: „Mit Änderungen freigeben“ → `"approve_with_changes"`.
`allowComment`	true	Lass Leute ihrer Entscheidung einen Kommentar hinzufügen.
`showOthers`	false	`"names"` oder `"counts"` zeigt jeder Person, wie die anderen stehen.
`verify`	false	`"email"`: Jede Person bestätigt einen 6-stelligen Code, der an ihre eigene Adresse geschickt wurde, bevor die Buttons funktionieren, sodass ein weitergeleiteter Link nicht für sie entscheiden kann. Jeder Empfänger braucht eine E-Mail-Adresse. Nutze es bei Geld, Zugriff oder Löschung.

Webhooks

Setze webhookUrl (https) bei einer Anfrage, und wir senden per POST JSON an diese Adresse, und zwar für zwei Ereignisse:

response.created: Jede Einreichung oder Entscheidung, mit der Antwort in response.
request.completed: Jede namentliche Person hat geantwortet, maxSubmissions wurde erreicht, eine Freigabe hat ihre Entscheidung oder die Anfrage ist abgelaufen.

Signatur prüfen. X-Runitby-Signature ist der HMAC-SHA256 des rohen Bodys als Hex, berechnet mit dem Signaturgeheimnis deines Kontos aus dem Dashboard. X-Runitby-Timestamp ist der Sendezeitpunkt in Unix-Sekunden.

Wiederholungen. Jedes 2xx innerhalb von 10 Sekunden gilt als zugestellt. Andernfalls versuchen wir es 4-mal erneut, nach 1 Min., 5 Min., 30 Min. und 2 Std. nach jedem Fehlschlag. Danach ist die Antwort weiterhin in getStatus abrufbar.

response.created

{
  "event": "response.created",
  "requestId": "req_8fK2…",
  "mode": "form",
  "respondedAt": "2026-11-12T16:20:41.000Z",
  "recipient": { "id": "rcp_3Qa…", "name": "Jordan Lee" },
  "response": { "data": { "address": "221 Pine St, Portland, OR", "deliveryDate": "2026-11-15" } },
  "status": { "state": "complete", "responses": 1, "pending": 0 },
  "metadata": { "ticket": "T-1042" }
}

Prüfen · Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

function verified(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest()
  const given = Buffer.from(signature, 'hex')
  return given.length === expected.length && timingSafeEqual(given, expected)
}

Fehler

Fehler sind JSON mit einer lesbaren message und, bei ungültiger Eingabe, problems[], das auf jedes zu ändernde Feld zeigt. Agenten können die Anfrage meist allein anhand der Meldung korrigieren.

Status	Wann
`400`	Die Eingabe oder das Schema ist ungültig.
`401`	Fehlender oder widerrufener API-Schlüssel.
`404`	Keine Anfrage mit dieser ID in deinem Konto.
`409`	Die Änderung ist nicht mehr erlaubt, z. B. Bearbeiten nach der ersten Antwort oder Erinnern bei einer geschlossenen Anfrage.
`429`	Mehr als 60 Erstellungen pro Minute, oder die monatlichen Anfragen des Tarifs sind aufgebraucht.

Tarife und Limits

	Free	Builder	Pro
Anfragen pro Monat	250	2,000	10,000
Antworten pro offenem Link	25	10,000	Unbegrenzt
API-Schlüssel	1	5	Unbegrenzt
Verbundene Apps (OAuth)	1	5	Unbegrenzt
Aufbewahrung der Antworten nach Zustellung	30 Tage	90 Tage	Dauerhaft
E-Mails pro Monat	500	4,000	20,000
E-Mails pro Anfrage	10	10	10
MCP-Push (offene Abonnements)	—	1	3
Preis pro Monat	$0	$9	$29

Nach Erreichen des Monatslimits liefert createRequest 429, bis sich der Zeitraum zurücksetzt oder du upgradest (bei Pro gilt das Fair-Use-Limit, schreib uns für mehr); bereits gesendete Links funktionieren weiter. Ohne Webhook werden Antworten ab der Einreichung aufbewahrt. Siehe Preise.

Die E-Mails, die wir für dich senden (Links, Erinnerungen und notifyEmail-Updates), zählen für beide E-Mail-Limits. Ist eines davon erreicht, kommen Links als "limit" zurück, damit du sie selbst schickst, und "each"-Updates hören auf. Die E-Mail zum Ende einer Anfrage geht immer raus, und Freigabecodes zählen nicht.

In jedem Tarif: 60 Erstellungen pro Minute und API-Schlüssel, title bis zu 120 Zeichen, approval.reason 300, approval.detail 1.000 und metadata unter 4 KB.

Du bist der Verantwortliche für die Daten, die du sammelst. Frag nur nach dem, was die Aufgabe braucht.