ドキュメント
エージェントから、誰にでも聞く。
エージェントは必要なこと(フォーム、アンケート、または「はい」か「いいえ」)を伝えて、リンクを受け取ります。リンクは1人向けにも、グループの1人ずつにも、共有した相手なら誰でも開けるものにもできます。相手はサインアップなしでスマートフォンからリンクを開き、回答は検証済みのJSONとして返ってきます。
-
リクエストを作成する。フォームにはJSON Schema、承認には理由を指定して、
createRequestを呼び出します。 -
リンクを送る。
sendEmail: trueを渡すと、指名した相手ごとにメールで送ります。メールやチャット、SMSなど、すでにお持ちの手段で送ることも、公開リンクをどこにでも掲載することもできます。 -
回答を受け取る。BuilderとProなら、回答が届いた瞬間にMCPクライアントへプッシュされます。回答はWebhookにも届き、
notifyEmailでメールにも、getStatusで取得することもできます。
同じツールを2通りの方法で使えます。MCPに対応したエージェント向けのMCPサーバーと、それ以外のためのREST APIです。このガイドは llms.txt でエージェントにも読ませられます。
クイックスタート
APIキーから人の回答まで、4ステップ。
1APIキーを取得する
メールアドレスでサインインし、ダッシュボードからキーをコピーします。キーは sk_live_ で始まります。サーバー側で保管してください。Claude CodeやCodex、その他のMCPクライアントを使う場合は、この手順は不要です。URLでサーバーを追加し、クライアントからサインインしてください。
2リクエストを作成する
この例では、Jordanに配送先住所と配送日を尋ねます。スキーマは通常のJSON Schemaです。対応している内容はフォームスキーマをご覧ください。
3リンクを送る
レスポンスの links[] には、1人につき1つのリンクが入ります(公開リンクの場合は単一の url)。"sendEmail": true を指定すると、メールアドレスのある指名した相手1人1人に、アカウント名義で専用のリンクをメールで送ります。各リンクの email には結果が入ります。"sent"、"failed"(リクエスト自体は存在するので、後で remind を呼び出せます)、"limit"(プランのメール上限に達した場合)、"no address"、"off" のいずれかです。残りの人には、メールやチャット、SMSなど、お好きな方法で送ってください。
4回答を受け取る
Jordanが送信すると、webhookUrl に、スキーマで検証済みのデータを含む response.created イベントが届きます。Webhookを使わない場合は、requestId を指定して getStatus を呼び出すか、notifyEmail を設定して完了時にメールで受け取れます。BuilderとProなら、MCPで購読しておくと、Jordanが回答した直後にエージェントへ通知が届きます。詳しくは返信を受け取るをご覧ください。
認証
MCPもRESTも、すべての呼び出しでAPIキーをBearerトークンとして送ります。同じキーが両方で使えます。キーが無い、または失効している場合は 401 が返ります。キーの取得方法は2つあります。
MCPクライアントからサインインする
キーを指定せずに https://runitby.app/mcp を追加すると、クライアントがOAuthでサインインを行います。ブラウザが開き、メールアドレスを入力すると、サインイン用のリンクからアプリの許可を求めるページに戻ります。初めての場合は、同じリンクでアカウントも作成されます。アプリにはその名前のキーが割り当てられ、キーの画面でいつでも失効できます。
-
Claude Code:右のコマンドを実行し、Claude Codeで
/mcpを実行して認証を選びます。 -
Codex:
codex mcp addを実行し、続けてcodex mcp loginを実行します。 - Claude(Webとデスクトップ):設定、コネクタ、カスタムコネクタを追加の順に開き、URLを貼り付けます。
- MCPの認可に対応しているその他のクライアント:ヘッダーなしでURLを追加します。
ダッシュボードでキーを作成する
REST APIやスクリプト、ヘッダーしか受け付けないクライアント向けです。ダッシュボードでキーの作成と失効を行い、キーを Authorization ヘッダーで送ってください。
プランでは、この2つを別々に数えます。Freeはキー1つと連携アプリ1つ、Builderはそれぞれ5つ、Proは必要なだけ使えます。
キーを使う1ファイルのサンプル：Vercel AI SDK、Mastra、LangChain.js、Claude Agent SDK。
ツールとエンドポイント
MCPツールにはそれぞれ、入力も出力も同じREST エンドポイントがあります。すべてのフィールドはAPIリファレンスに載っています。
| MCPツール | REST | できること |
|---|---|---|
createRequest |
POST /requests | フォームまたは承認を作成してリンクを受け取ります。指定すればメールで送信まで行います。 |
previewRequest |
POST /requests/preview | 相手に見えるページのスクリーンショットと指摘を返します。何も作成しません。 |
getStatus |
GET /requests/{id} | ステータス、判定、これまでのすべての回答。 |
listRequests |
GET /requests | リクエストを新しい順に取得します。modeやstatusで絞り込め、cursorでページを送れます。 |
updateRequest |
PATCH /requests/{id} | 内容の変更、宛先の追加、新しい有効期限の設定ができます。 |
remind |
POST /requests/{id}/remind | まだ回答していない人にリンクをメールで送ります。 |
closeRequest |
DELETE /requests/{id} | 回答の受付を終了します。 |
フォームと承認
すべてのリクエストには mode があります。
"form"- データを集めます。
schemaを送ると、相手にはそこから作られたフォームが表示され、あなたにはスキーマに合ったオブジェクトが返ります。 "approval"- 判断をもらいます。
approval.reasonを送ると、相手1人1人に、承認・却下(または独自のラベル)のボタンと任意のコメント欄があるカードが表示されます。1人1人の判断と、全体のverdict(判定)が返ります。
どちらも title(120文字まで)、誰が尋ねているかを示す任意の requester 行、ページとメールのための locale("en"、"es"、"pt"、"fr"、"de"、"it"、"ja"、"zh"。日付の表記に合わせて "es-AR" のように地域も付けられます)、そしてすべてのWebhookとステータスにそのまま返される metadata を受け取ります。タイトルと質問文は同じ言語で書いてください。
誰が回答するか
audience が、誰にリンクを渡すかを決めます。
| kind | 返ってくるもの | 使いどころ |
|---|---|---|
"named" |
recipients の1人につき1つの links[](1〜50人、各 { name, email?, phone? }) |
誰の回答か特定する必要があるとき。承認は必ず指名が必要です。メールアドレスがあれば、sendEmail、リマインダー、メールコードが使えます。 |
"open" |
誰でも開ける url が1つ |
申し込みやアンケート。maxSubmissions で回答数に上限を付けます(既定は1)。 |
使いどころ
modeとaudienceの組み合わせで、フォーム作成ツールやアンケート、日程調整アプリ、メールのやり取りで済ませていたことの大半をカバーできます。
| やりたいこと | リクエスト |
|---|---|
| 1人の情報を集める:配送先住所、顧客の受付、予約の枠 | "form"、指名、宛先は1人 |
| 誰からでも、アンケート、投票、フィードバック、申し込みを集める |
"form"、公開で maxSubmissions を指定。url を好きな場所に掲載します。getStatus がすべての回答を返すので、エージェントが要約できます。 |
| 既知のグループから、出欠、空き状況、シフトの代理、チェックインを集める |
"form"、指名(50人まで)。すべての回答が誰のものかわかり、remind で残りの人に催促できます |
| 承認、最終確認、投票 |
policy を指定した "approval"。お金、アクセス、削除に関わるときは verify: "email" を追加します |
ステータスと有効期限
| status | 意味 |
|---|---|
pending |
まだ誰も回答していません。 |
partial |
指名した相手の一部が回答済みで、残りはまだです。 |
complete |
全員が回答した、maxSubmissions に達した、または承認の判定が出ました。 |
expired |
リンクの有効期限が切れました。 |
closed |
closeRequest を呼び出しました。 |
有効期限。expiresIn には "30m"、"48h"、"7d"、または秒数を指定できます。既定は7日、最大は90日です。
リクエストの変更。updateRequest では、最初の回答が届くまで、タイトル、スキーマ、セクション、理由、テーマを変更できます。宛先の追加、新しい有効期限の設定(今から数えます)、notifyEmail の変更は、リクエストが完了・期限切れ・クローズされるまで可能です。追加した宛先にはメールは送られません。リンクを自分で送るか、recipientIds を指定して remind を呼び出してください。
リマインダー。remind は、まだ回答しておらずメールアドレスのある指名した相手に、リンクをメールで送ります。同じ相手には24時間に1回までです。sendEmail のメールが最初の1回として数えられます。
返信を受け取る。1つだけでも、複数を組み合わせても使えます。
webhookUrl- 回答が届くたびに、サーバーが受け取ります。Webhookをご覧ください。
notifyEmail- アカウント宛てに、要約とダッシュボード上のリクエストへのリンクをメールで送ります。
"each"は回答のたびに送ります(プランのメール上限に達するまで。以降は終了時のみ)。"complete"は、完了または期限切れのときに1回だけ送ります。承認のメールには判断とコメントが含まれ、フォームの回答はダッシュボードで確認します。既定ではオフです。updateRequestで変更できます。 waitを指定したgetStatus- 呼び出しを最大25秒保持し(RESTでは
?wait=25)、誰かが回答するかステータスが変わった時点ですぐに結果を返します。待ち続けたい場合は、もう一度呼び出してください。 - MCPプッシュ(BuilderとPro)
- リクエストはそれぞれMCPリソース
runitby://requests/{requestId}として扱われ、createRequestからリンクされます。読み取るとgetStatusと同じ内容が返ります。BuilderとProでは、2026-07-28プロトコルのクライアントがsubscriptions/listenで購読でき、回答やステータス変更のたびにnotifications/resources/updatedが届きます。同時に開ける購読は、Builderでは1件、Proでは3件までです。Freeでは、subscriptions/listenはエラーを返し、他の受け取り方を案内します。
フォームスキーマ
最上位に type: "object" を持つ通常のJSON Schemaで、フィールドは40個までです。required[] は必ず検証され、title と description がラベルとヘルプテキストになります。
| 型 | キーワード |
|---|---|
string |
format(email、date、time、date-time、tel、uri、duration)、minLength、maxLength、pattern
|
number, integer |
minimum, maximum |
boolean |
const: true を指定すると、チェックが必須の同意ボックスになります |
enum |
固定の選択肢 |
array |
プリミティブまたはenumの配列。minItems、maxItems |
ヒント。フィールドごとのオプションは "x-runitby" に指定します。widget、placeholder、help、columns(1または2)、step、currency が使えます。
セクション。スキーマと並べて sections: [{ title, fields: [...] }] を指定すると、フィールドをグループ化できます。
ネストしたオブジェクト(位置情報フィールドを除く)、oneOf、anyOf、allOf、$ref は、何を変更すべきかを示すメッセージとともに拒否されます。パスワード、PIN、カード番号、CVV、セキュリティコード、SSN、ワンタイムコードを求めるフィールドは受け付けません。
フィールドの種類
入力しにくい内容のために、あらかじめ用意されたフィールドです。どれも通常のJSON Schemaに widget を加えたものなので、回答は他のフィールドと同じように検証されます。
| フィールド | スキーマ | 回答 |
|---|---|---|
| 日付 | string、format は date | "2026-11-12" |
| 時刻 | string、format は time。step は分(1〜60) | "14:30" |
| 日時 | string、format は date-time | "2026-11-12T14:30:00-08:00" |
| 期間 | string、format は duration | "PT1H30M" |
| 時間枠 | date-time の enum の配列、widget は slots | 選ばれた時刻 |
| 日付の範囲 | 2つの日付の配列、widget は daterange | ["2026-11-12", "2026-11-15"] |
| 位置情報 | object、widget は location | { latitude, longitude, accuracy } |
| 金額 | number、currency は "USD" | 1200 |
| スライダー、評価 | number または integer。スライダーには minimum と maximum が必要 | 7 |
| チップ、ラジオボタン、セレクト | enum(チップは enum の配列も使えます) | "M" |
| ランキング | enum の配列、widget は rank | すべての選択肢が、相手が並べた順序で返ります |
| はい・いいえ | boolean、widget は yesno | true |
| 色 | string、widget は color | "#C2410C" |
| 国 | string、widget は country | "US"(ISO 3166-1) |
| 言語 | string、widget は language | "es-AR"(BCP 47) |
| タイムゾーン | string、widget は timezone | "America/New_York" |
国や言語のフィールドに enum を追加すると、選択肢を絞り込めます。
プレビュー
previewRequest は、createRequest と同じフォームまたは承認のフィールド(audience、有効期限、Webhook、metadata は除く)を受け取り、幅390pxと1280pxのスクリーンショットと、読みづらくなりそうな点を示す lint[] を返します。何も作成されません。
sampleData を渡すと入力済みのフォームを確認でき、viewports を渡すと1つのサイズだけを取得できます。同じフォームを何度も送る場合は、先にプレビューしてください。
テーマ
theme を使うと、ページをあなたのプロダクトらしい見た目にできます。指定しない場合は、温かみのある白地にインク色の文字、Figtree フォントに Fraunces の見出し、丸みのある角になります。
| キー | 値 |
|---|---|
accent, background, surface,
text
|
16進数のカラーコード |
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(すべてのフィールドを1ページに表示)または single(1問ずつ表示) |
logoUrl |
ロゴ |
heroText, thankYou |
フォームの上部に表示するあいさつ文と、送信後のメッセージ |
承認のオプション
承認には、指名した相手が必要です。相手1人1人に専用のリンクが渡されるので、すべての判断が誰のものかわかります。判定は "approved"、"declined"、または誰も期限内に判断しなかった場合の "expired" のいずれかで、黙って承認になることはありません。
| approval のフィールド | 既定値 | 備考 |
|---|---|---|
reason必須 |
何を求めているかを300文字まで。 | |
detail |
理由の下に表示する補足を1,000文字まで。 | |
policy |
"all" |
"any"、"all"、"majority"、または { n }。承認が何件必要かを指定します。 |
options |
承認する、却下する | 2〜4個のラベル。最初のものが承認として扱われます。判断はスネークケースで返ります。「Approve with changes」→ "approve_with_changes"。 |
allowComment |
true | 判断にコメントを添えられるようにします。 |
showOthers |
false |
"names" または "counts" を指定すると、他の人の状況を各自に表示します。 |
verify |
false |
"email":各自が、自分のアドレスに届く6桁のコードを確認して初めてボタンが使えるようになります。転送されたリンクで他の人が代わりに判断することはできません。宛先全員にメールアドレスが必要です。お金、アクセス、削除に関わるときに使ってください。 |
Webhook
リクエストに webhookUrl(https)を設定すると、次の2つのイベントでJSONをPOSTします。
response.created- 送信または判断のたびに、回答が
responseに入って届きます。 request.completed- 指名した全員が回答した、
maxSubmissionsに達した、承認の判定が出た、またはリクエストが期限切れになったとき。
署名を検証する。X-Runitby-Signature は、生のリクエストボディを、ダッシュボードにあるアカウントの署名シークレットでHMAC-SHA256にかけた16進数の値です。X-Runitby-Timestamp は、送信時刻をUnix秒で表したものです。
再送。10秒以内に2xxが返れば、配信できたものとして扱います。そうでない場合は、失敗のたびに1分後、5分後、30分後、2時間後の4回、再送します。それでも届かなかった場合でも、回答は getStatus から取得できます。
エラー
エラーは、読みやすい message を含むJSONで返ります。入力が不正な場合は、直すべきフィールドを指す problems[] も付きます。エージェントは多くの場合、メッセージを読むだけでリクエストを修正できます。
| ステータス | 発生する場面 |
|---|---|
400 |
入力またはスキーマが正しくありません。 |
401 |
APIキーが無い、または失効しています。 |
404 |
そのidのリクエストは、アカウントにありません。 |
409 |
この変更はもう行えません。例:最初の回答の後に編集する、クローズ済みのリクエストにリマインダーを送る。 |
429 |
1分間に60件を超える作成、またはプランの月間リクエスト数を使い切りました。 |
プランと上限
| Free | Builder | Pro | |
|---|---|---|---|
| 月間リクエスト数 | 250 | 2,000 | 10,000 |
| 公開リンクあたりの回答数 | 25 | 10,000 | 無制限 |
| APIキー | 1 | 5 | 無制限 |
| 連携アプリ(OAuth) | 1 | 5 | 無制限 |
| 配信後に回答を保持する期間 | 30日 | 90日 | 保持 |
| 月間メール数 | 500 | 4,000 | 20,000 |
| リクエストごとのメール数 | 10 | 10 | 10 |
| MCPプッシュ(同時に開ける購読数) | — | 1 | 3 |
| 月額料金 | $0 | $9 | $29 |
月間の上限を超えると、期間がリセットされるかアップグレードするまで、createRequest は 429 を返します(Proではフェアユースの上限です。それ以上が必要な場合はご連絡ください)。すでに送ったリンクは引き続き使えます。Webhookを使っていない場合は、送信時点から回答を保持します。料金をご覧ください。
こちらから代わりに送るメール(リンク、リマインダー、notifyEmail の通知)は、両方のメール上限に数えられます。どちらかの上限を超えると、リンクは "limit" で返されるのでご自身で送ってください。"each" の通知も止まります。リクエストの終了を知らせるメールは必ず送られ、承認コードは数えられません。
すべてのプラン共通:APIキーあたり1分間に60件まで作成可能、title は120文字まで、approval.reason は300文字、approval.detail は1,000文字、metadata は4 KB未満です。
収集した内容については、あなたがデータ管理者です。作業に必要なことだけを尋ねてください。