文档
从你的智能体出发，想问谁就问谁。
你的智能体描述它需要什么（一份表单、一份调查，或者一个“是”或“否”），然后拿到一个链接：可以给一个人、给群组里的每个人，或给你分享到的任何人。大家在手机上打开，不用注册，回复会以经过校验的 JSON 返回给你。
-
创建请求。调用
createRequest，表单传入 JSON Schema，审批则传入理由。 -
发送链接。传入
sendEmail: true，我们会把链接用邮件发给每位指定收件人；你也可以通过现成的渠道发送（邮件、聊天或短信），或者在任何地方发布一个公开链接。 -
拿到回复。在 Builder 和 Pro 套餐上，每条回复一到，就会推送给你的 MCP 客户端。回复也会发到你的 Webhook，用
notifyEmail发邮件通知，或者用getStatus读取。
同样的工具有两种用法：给会说 MCP 的智能体用的 MCP 服务器，以及适用于其他一切场景的 REST API。智能体可以在 llms.txt 里读到这份指南。
快速开始
从 API 密钥到对方的回复，只要四步。
1获取 API 密钥
用你的邮箱登录，在控制台里复制密钥。它以 sk_live_ 开头，请放在你的服务器上保管。用的是 Claude Code、Codex 或其他 MCP 客户端？跳过这一步：通过地址添加服务器，并在客户端里登录即可。
2创建请求
这个请求向 Jordan 询问收货地址和送货日期。schema 就是普通的 JSON Schema，支持哪些内容请看表单 schema。
3发送链接
响应的 links[] 里每人一个链接（公开链接则是单个 url）。设置 "sendEmail": true 后，我们会以你账号的名义，把各自的链接用邮件发给每位有邮箱的指定收件人。每个链接的 email 会说明发生了什么："sent"、"failed"（请求仍然存在，之后可以调用 remind）、"limit"（已达到套餐的邮件上限）、"no address" 或 "off"。其余的人你想怎么发都行：邮件、聊天或短信。
4拿到回复
Jordan 提交后，你的 webhookUrl 会收到一个带有数据的 response.created 事件，数据已经按你的 schema 校验过。没有 Webhook？用 requestId 调用 getStatus，或者设置 notifyEmail，完成时我们给你发邮件；在 Builder 和 Pro 套餐上还可以通过 MCP 订阅，Jordan 一回复你的智能体就会收到通知。详见收到回复。
身份验证
每次 MCP 和 REST 调用都要把 API 密钥作为 bearer token 发送，同一个密钥两边通用。缺少或已吊销的密钥会返回 401。获取密钥有两种方式。
从你的 MCP 客户端登录
不带密钥添加 https://runitby.app/mcp，客户端会通过 OAuth 让你登录：浏览器会打开，你输入邮箱，登录链接会把你带回一个页面，请你允许该应用。第一次用？同一个链接会为你创建账号。之后应用会持有一个以它命名的专属密钥，你可以在密钥页面吊销。
-
Claude Code：运行右侧的命令，然后在 Claude Code 里输入
/mcp并选择进行身份验证。 -
Codex：运行
codex mcp add，然后运行codex mcp login。 - Claude（网页版和桌面版）：设置、连接器、添加自定义连接器，然后粘贴地址。
- 其他支持 MCP 授权的客户端：添加地址，不带任何请求头。
在控制台里创建密钥
对于 REST API、脚本，以及只接受请求头的客户端：在控制台里创建和吊销密钥，并把密钥放在 Authorization 请求头里发送。
套餐会把这两种方式分开计数。Free 包含一个密钥和一个已连接的应用，Builder 各五个，Pro 按你需要的数量。
使用密钥的单文件示例：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 | 你的请求，最新的在前。可按模式或状态筛选，用 cursor 翻页。 |
updateRequest |
PATCH /requests/{id} | 修改内容、添加收件人或设置新的过期时间。 |
remind |
POST /requests/{id}/remind | 把链接用邮件发给还没回复的人。 |
closeRequest |
DELETE /requests/{id} | 停止接收回复。 |
表单与审批
每个请求都有一个 mode：
"form"- 收集数据。你发送一个
schema，对方会得到据此生成的表单，你会拿回一个与之匹配的对象。 "approval"- 拿到决定。你发送
approval.reason，每个人会看到一张带有“批准”和“拒绝”（或你自定义的标签）以及可选评论的卡片。你会拿到每个人的决定和一个总的verdict。
两者都接受 title（最多 120 个字符）、一个可选的 requester 行（说明是谁在问）、用于页面及其邮件的 locale（"en"、"es"、"pt"、"fr"、"de"、"it"、"ja" 或 "zh"，也可以带地区，如 "es-AR"，用于日期格式），以及会在每次 Webhook 和状态查询中原样返回的 metadata。标题和问题请用同一种语言来写。
谁来回复
audience 决定谁会拿到链接。
| kind | 你会得到 | 适用于 |
|---|---|---|
"named" |
links[]，recipients 里每人一个（1 到 50 人，每人 { name, email?, phone? }） |
需要确定是谁回复的场景。审批必须指定收件人。有了邮箱就能使用 sendEmail、提醒和邮件验证码。 |
"open" |
任何人都能打开的一个 url |
报名和调查。maxSubmissions 限制回复数量（默认 1）。 |
适用场景
一个模式加一个受众，就能覆盖你原本要用表单工具、投票、排期应用或邮件往来来做的大部分事情。
| 你想要 | 请求 |
|---|---|
| 一个人的详细信息：收货地址、客户信息收集、预约时段 | "form"，指定收件人，一位收件人 |
| 面向任何人的调查、投票、反馈或报名 |
"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 可以修改标题、schema、分组、理由或主题。添加收件人、设置新的过期时间（从现在起算）和修改 notifyEmail，在请求完成、过期或关闭之前都可以做。新添加的收件人不会收到邮件；请自己发送他们的链接，或者带上他们的 recipientIds 调用 remind。
提醒。remind 会把链接用邮件发给还没回复且有邮箱的指定收件人，每人每 24 小时最多一次。sendEmail 发的那封邮件算第一次。
收到回复。可以选其一，也可以组合使用：
webhookUrl- 你的服务器会实时收到每条回复。详见 Webhook。
notifyEmail- 我们会给你的账号发一封摘要邮件，附带控制台里该请求的链接：
"each"表示每条回复都发（直到达到套餐的邮件上限，之后只在结束时发），"complete"表示只在完成或过期时发一次。审批邮件包含决定和评论；表单的回复则保留在控制台里。默认关闭，可以用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 同一时间可打开一个订阅，Pro 最多可打开三个。在 Free 套餐上，subscriptions/listen会返回一个错误，其中列出其他获知回复的方式。
表单 schema
就是普通的 JSON Schema，顶层为 type: "object"，最多 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。
分组。在 schema 旁边用 sections: [{ title, fields: [...] }] 把字段分组。
嵌套对象（位置字段除外）、oneOf、anyOf、allOf 和 $ref 会被拒绝，并附上说明该怎么改的消息。询问密码、PIN、银行卡号、CVV、安全码、社保号或一次性验证码的字段会被拒绝。
字段类型
为人们觉得不好输入的内容准备的现成字段。每一种都是普通的 JSON Schema 加一个 widget，所以回复和其他字段一样会被校验。
| 字段 | Schema | 回复 |
|---|---|---|
| 日期 | 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 相同的表单或审批字段（不含受众、过期时间、Webhook 和 metadata），返回 390 px 和 1280 px 宽度的截图，以及列出所有读起来不顺的地方的 lint[]。不会创建任何东西。
传入 sampleData 可以看到填好的表单，传入 viewports 则只获取一种尺寸。同一份表单要发很多次时，先预览。
主题
theme 能让页面看起来像你的产品。不设置的话，页面是暖白底色上的墨色文字，字体为 Figtree，标题用 Fraunces，圆角。
| 键 | 取值 |
|---|---|
accent, background, surface,
text
|
十六进制颜色 |
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（所有字段在同一页）或 single（一次一个问题） |
logoUrl |
你的 logo |
heroText, thankYou |
表单上方的欢迎语和提交之后的消息 |
审批选项
审批需要指定收件人：每个人都有自己的链接，所以每个决定都能对应到本人。审批结果是 "approved"、"declined"，或者在没人及时决定时为 "expired"；绝不会是默默的同意。
| 审批字段 | 默认值 | 说明 |
|---|---|---|
reason必填 |
你要请对方批准的事项，最多 300 个字符。 | |
detail |
理由下方的补充说明，最多 1,000 个字符。 | |
policy |
"all" |
"any"、"all"、"majority" 或 { n }：需要多少人批准。 |
options |
批准、拒绝 | 两到四个标签；第一个算作批准。决定会以 snake_case 返回：“Approve with changes” → "approve_with_changes"。 |
allowComment |
true | 允许对方在决定时附上评论。 |
showOthers |
false |
"names" 或 "counts" 会让每个人看到其他人的进度。 |
verify |
false |
"email"：每个人要先确认发到自己邮箱的 6 位验证码，按钮才能用，所以转发出去的链接没法替他做决定。每位收件人都需要有邮箱。涉及金钱、访问或删除时使用。 |
Webhook
在请求上设置 webhookUrl（https），我们就会针对两种事件向它 POST JSON：
response.created- 每次提交或决定，回复内容在
response里。 request.completed- 每位指定收件人都已回复、已达到
maxSubmissions、审批已有审批结果，或者请求已过期。
验证签名。X-Runitby-Signature 是用你账号的签名密钥（在控制台里）对原始请求体计算的十六进制 HMAC-SHA256。X-Runitby-Timestamp 是以 Unix 秒表示的发送时间。
重试。10 秒内返回任意 2xx 即视为送达。否则会重试 4 次，分别在每次失败后的 1 分钟、5 分钟、30 分钟和 2 小时。之后，回复仍然可以通过 getStatus 查到。
错误
错误以 JSON 返回，带有可读的 message；对于无效输入，还有 problems[]，指向每个需要修改的字段。智能体通常只看消息就能修正请求。
| 状态 | 何时出现 |
|---|---|
400 |
输入或 schema 无效。 |
401 |
缺少 API 密钥，或密钥已被吊销。 |
404 |
你的账号下没有该 id 的请求。 |
409 |
不再允许这项修改，例如在第一条回复之后编辑，或提醒已关闭的请求。 |
429 |
每分钟创建超过 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 密钥每分钟最多创建 60 个请求，title 最多 120 个字符，approval.reason 最多 300 个，approval.detail 最多 1,000 个，metadata 不超过 4 KB。
对于你所收集的数据，你是数据控制者。只询问任务需要的内容。