Forms

A form trigger executes a graph when a form is submitted. The form defines a schema that validates every submission before the graph runs. You can submit forms from the Portal, the API, or the headless SDK in your own application.

Overview

Form triggers provide a structured, validated entry point for graph execution:

• Schema validation -- Every submission is validated against the form's schema before the graph runs. Invalid payloads are rejected with validation errors.
• Multiple submission channels -- The same form can be submitted by a user in the Portal, by an external system via the API, or by a user in your app through the SDK.
• Embeddable -- Use the headless SDK to render forms in your React application. Submissions trigger the same graph execution without users leaving your product.

Configuration

To set up a form trigger:

1. Create a form in the Portal or via the API. Define the schema with field names, types, required/optional rules, and validation constraints. See Schemas.
2. Create a trigger of type form and link it to the form you created.
3. Attach the trigger to a root node of your graph. The graph must have a root node (a node with no incoming edges) before a trigger can be attached.

Once configured, the trigger can be enabled or disabled without removing it from the graph.

Schema and validation

The form schema is a JSON Schema object that defines the structure and rules for incoming data. Swirls validates every submission against this schema before starting execution. Submissions that fail validation return errors and do not trigger a graph run.

Downstream nodes in the graph receive the validated payload as input. When nodes are connected by edges, the downstream node automatically inherits the upstream node's output schema. See Schemas for details on defining schemas and TypeScript generation for generating type-safe code from your schemas.

Submitting forms

From the Portal

Users fill out and submit the form directly in the Portal UI. The graph runs from the root node and the execution appears in the execution list.

From the API

Send a POST request to /forms/:formId with a JSON body that matches the form schema. The response returns message and executionIds confirming that execution has started.

From the SDK

Use the headless SDK to render the form in your React application. Configure the form in the Portal, then embed it in your product so users submit data without leaving your app. Submissions trigger graph execution and are tracked the same way as Portal or API submissions.

Run swirls form gen to generate Zod schemas and a typed form registry for your project. This gives you full type safety and autocomplete when integrating forms with useSwirlsFormAdapter. See TypeScript generation for setup details.

Use cases

• User onboarding -- Collect structured input from users and run a processing or enrichment graph.
• Internal tools -- Build Portal-based forms for operations teams to trigger workflows manually.
• Embedded workflows -- Render forms in your product with the SDK so end users trigger graphs without knowing about Swirls.

Next steps

• Schemas -- Define and manage schemas for validation and code generation.
• TypeScript generation -- Generate type-safe form code for your application.
• Graphs -- Understand how graphs, root nodes, and execution work.