Public API

Built for servers, not browsers

The Public API is for automation that runs on infrastructure you control — cron jobs, backends, CI pipelines. It manages Forms and Fields and reads and processes Submissions. It is separate from the Form Submission API, which receives form data from your website visitors; if that is what you need, start with the Form Submission API docs instead.

What you can do

Every operation is authorized by the scopes on your API Key and the forms that key is granted to.

• Manage Forms — list, create, update, and delete forms, all governed by the forms:read, forms:create, forms:update, and forms:delete scopes.
• Define Fields — read and update a form's field configuration under the forms:read and forms:update scopes.
• Read Submissions — list submissions per form and mark them read under the submissions:read and submissions:mark_read scopes.
• Access Files — obtain authorized, short-lived download access for files attached to submissions.
• Operate Workflows — inspect and edit drafts, validate and publish versions, run dry tests, review runs, and retry eligible failures.

A minimal request

Every call is authenticated with a Bearer API Key in the Authorization header. Keys look like smto_live_<key_id>_<secret> — this is the format only, not a working 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"

Choose narrow access and plan for rotation

A Key is an independent server credential. Changing your password does not revoke it, so manage its scope, lifetime, and revocation deliberately.

• Start with selected forms, read scopes, and a 90-day expiry; add broader access only when the automation needs it.
• The plaintext Key is shown once. If it is lost, create a replacement rather than trying to recover it.
• If a Key may have leaked, revoke it immediately and rotate the runtime secret.
• Disabling Public API permanently revokes every active Key. Re-enabling access never restores an old Key.

Runtime rules worth knowing

• Call GET /v1/capabilities first. Effective write access can be unavailable even when a Key includes write scopes.
• Form and Workflow edits use ETags to prevent stale writes; create, publish, test, and retry operations use idempotency keys where required.
• List operations use bounded cursor pagination and rate-limit headers. Follow Retry-After after a 429 response.
• Workflow dry runs never deliver real messages, but AI steps still reserve and settle Compute Points.

Security boundaries

• API Keys authenticate your server, never a browser or mobile app. Only server-to-server runtimes over HTTPS.
• Keys carry selected scopes and may be granted to selected forms only. Ungranted resources are not visible to the key.
• Responses omit secrets, form tokens, integration configuration, and raw submission payloads.
• Destructive operations require an application-level confirmation on top of the scopes.

Getting started

1. Open Dashboard Settings, enable Public API after reviewing the security risks, then create a least-privilege API Key. The plaintext key is shown once — store it in your server-side secret manager immediately.
2. Call GET /v1/capabilities to confirm the API version, available scopes, write state, and rate limits your key can use.
3. Read the complete API guide on this page and the published OpenAPI specification before you build.

Full contract and OpenAPI

This page is the public guide. Use the generated API reference and the OpenAPI artifact for the complete machine-readable contract.