Public API

为伺服器设计,而非浏览器

Public API 供你掌控的基础设施使用 — cron 排程、后端服务、CI pipeline。它可管理 Forms 与 Fields,并读取与处理 Submissions。它与 Form Submission API 是两个不同方向的 API:后者负责从网站接收表单数据;若你要的是接收数据,请前往 Form Submission API 文件。

可执行的操作

每个操作都由 API Key 的 scope 与该 Key 获授权的 Form 共同限制。

• 管理 Forms — 列出、创建、更新与删除表单,分别由 forms:read、forms:create、forms:update、forms:delete scope 管理。
• 定义 Fields — 在 forms:read 与 forms:update scope 下读取与更新表单的字段设置。
• 读取 Submissions — 在 submissions:read 与 submissions:mark_read scope 下逐 Form 列出提交并标记已读。
• 存取 Files — 取得 Submission 附件经授权且短效的下载存取。
• 操作 Workflows — 查看与编辑 draft、validate 与 publish Version、执行 dry test、查看 Runs，并重试符合条件的失败工作。

最小 request 示意

每个呼叫都以 Bearer API Key 放在 Authorization header 中进行验证。Key 的格式为 smto_live_<key_id>_<secret> — 这只是格式示意,不是可用的 Key。

Authorization: Bearer smto_live_<key_id>_<secret>
Accept: application/json

請先呼叫GET /v1/capabilities確認此 Key 的可用能力:

curl https://api.submeto.com/v1/capabilities \
  -H "Authorization: Bearer smto_live_<key_id>_<secret>" \
  -H "Accept: application/json"

限制存取范围，并为轮替做好准备

API Key 是独立的 server credential。修改密码不会撤销 Key，因此应明确管理它的 scope、有效期与撤销流程。

• 从 selected Forms、read scopes 与 90-day expiry 开始；只有 automation 确实需要时才扩大权限。
• plaintext Key 只显示一次。遗失时请创建替代 Key，不要尝试恢复原 Key。
• 若怀疑 Key 泄漏，请立即撤销并轮替 runtime secret。
• 停用 Public API 会永久撤销所有 active Keys；重新启用不会恢复任何旧 Key。

需要知道的 runtime 规则

• 先呼叫 GET /v1/capabilities。即使 Key 包含 write scopes，effective write access 仍可能暂不可用。
• Form 与 Workflow 编辑使用 ETag 防止 stale write；create、publish、test 与 retry 等操作会在契约要求处使用 idempotency key。
• List operations 使用有上限的 cursor pagination 与 rate-limit headers；收到 429 后应依 Retry-After 重试。
• Workflow dry run 不会投递真实消息，但执行 AI Steps 时仍会 reserve 并结算 Compute Points。

安全边界

• API Key 验证的是你的伺服器,绝非浏览器或 mobile app。只在 server-to-server 执行环境中透过 HTTPS 使用。
• Key 带有明确的 scope,并可只授权特定 Forms。未授权的资源对 Key 而言不可见。
• Response 不包含 secret、Form token、整合设置或 raw submission payload。
• 破坏性操作除了 scope 之外,还需要应用程式层级的明确确认。

开始方式

1. 在 Dashboard Settings 阅读安全风险并启用 Public API，再创建 least-privilege API Key。plaintext Key 只显示一次 — 请立即存入 server-side secret manager。
2. 呼叫 GET /v1/capabilities 确认 API version、可用 scope、writes 状态与你的 Key 适用的 rate limits。
3. 建置前先阅读本页完整 API guide 与已发布的 OpenAPI 规格。

完整 contract 与 OpenAPI

本页是公开 guide。完整的 machine-readable contract 请使用产生的 API reference 与 OpenAPI artifact。