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。