Forms Overview

Forms capture input from submitters and route it somewhere useful — into a table, through an automation, into the built-in submission ledger, or any combination of the three. They are declared in the top-level forms array, each one reachable at its own URL, embeddable inside a page, and addressable from an automation trigger.

A form is the public-facing counterpart to a table: where a table defines what data looks like, a form defines how people contribute it. The same form can write directly to a tables[] entry, fire a notify-sales automation, or simply land in the platform's form_submissions ledger for later review.

forms:
  - id: 1
    name: contact
    title: Contact Sales
    path: /contact
    submitTo:
      table: leads
    fields:
      - { kind: table-field, column: email, required: true }
      - { kind: table-field, column: message }

Form Properties

Each entry in the forms array accepts the following properties.

Submit Targets

The submitTo object decouples a form from any single persistence model. At least one of table, automation, or storeSubmission: true (the default) must be set — otherwise the submission would be discarded silently and the schema rejects the config.

submitTo:
  table: support_tickets
  automation: page-on-call
  mapping:
    userEmail: email # form field 'userEmail' -> table column 'email'

Public Routes

Every form is reachable at the canonical route /forms/{name} regardless of configuration — a form without a path is not private, it is simply only reachable there. When path is set, the form is served at that custom path and at /forms/{name} simultaneously (no redirect; both URLs render the same form).

Access Control

The access object reuses the shared permission model used by tables, pages, buckets, automations, and agents.

forms:
  - id: 2
    name: member-survey
    title: Member Survey
    access:
      require: authenticated
      redirectTo: /login
    submitTo: { table: survey_responses }
    fields:
      - { kind: standalone, name: rating, inputType: rating, required: true }

Embedding a Form in a Page

A top-level form can be rendered inline inside a page via the form control's formRef. The form is defined once and reused anywhere — fields, validation, conditional logic, multi-step layout, file uploads, and onSuccess/onError all flow from app.forms[]. The host page's access control is intersected with the form's own rules at render time.

pages:
  - id: 1
    name: landing
    path: /
    components:
      - type: form
        formRef: contact # renders the top-level "contact" form inline
        props:
          label: Get in touch # display-only override of the submit label

See Form Controls for the page-component side of formRef.

Related Pages

• Form Fields — standalone vs table-bound fields, prefill, inline relationship create.
• Conditional Logic — visible / required / disabled rules.
• Multi-Step Forms — steps, branching, one-question layouts, display overrides.
• Submissions — the dual-write ledger, success and error handling.
• Access Control — the access block in full, and what a denied submitter gets.
• Availability — submission windows, caps, and the closed-form page.
• Anti-Spam & Attribution — antiSpam, submitter, and the analytics opt-out.
• File Uploads — attachment fields backed by buckets.
• Tables Overview — the data models forms write to.
• Form Controls — embedding a form inside a page.
• Auth — roles and authentication behind access.