Form Viewer
The consumption surface for dynamic forms — open a form definition for display, upload file attachments, and submit answers. This is the side that powers public-facing form pages and any embedded form widgets.
The corresponding authoring endpoints live under Form Builder.
Scopes
| Scope | Reach |
|---|---|
forms:read | Listing forms, opening a form by URL or ID. |
forms:submit | Submitting payloads and uploading files. |
A typical "customer-facing" API key carries forms:read + forms:submit only; no builder scope, no admin scopes.
Endpoints
List Forms
GET /api/form/
Returns a page of forms — the viewer view, which exposes only the publishable surface (not authoring internals).
Required scope: forms:read · also accepts API key
Query parameters — standard pagination set; see Conventions › Pagination. Defaults: sort_by=created, sort_order=desc, hydrate=true.
Response 200 — FormInDbCursorPage
Get Form Filter Metadata
GET /api/form/filters
Returns filter/operator/sort options for List Forms.
Required scope: forms:read
Response 200 — open metadata object.
Open Form
GET /api/form/{url_or_id}
Opens a form for display — returns the viewer-side schema (fields, validations, layout) needed to render the form. The path segment accepts either the form's published URL slug or its raw ID.
Required scope: forms:read · also accepts API key
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
url_or_id | string | yes | The form's URL slug or raw ID. |
Response 200 — FormReadViewer
Submit Form
POST /api/form/{id}
Submits a completed form payload. The server validates against the form definition and creates a Submission record.
Required scope: forms:submit
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Form ID. |
Request body — FormSubmissionWriteCreate
Response 200 — FormSubmissionRead
Upload Files to Form
POST /api/form/{id}/upload
Uploads file attachments associated with a form submission. Most file-upload-equipped forms call this before the final Submit Form step and reference the returned file handles inside the submission body.
Required scope: forms:submit
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Form ID. |
Request body — Body_Form_Viewer-Upload_Files_to_Form (multipart/form-data).
Max upload size: 100 MB per request — see Conventions › Uploads.
Response 200 — upload result with file handles to reference in the submission body.
See also
- Forms › Workflow — end-to-end open → upload → submit → inspect example.
- Form Builder — authoring side of the same forms.
- Submissions — records produced by
POST /api/form/{id}.