Forms

Dynamic forms — the S-Launch platform's mechanism for collecting structured user input. A form is authored in the Form Builder, served to a (potentially unauthenticated) end-user via the Form Viewer, and the resulting Submissions are stored for downstream processing (often by a Factory blueprint).

Resource	What it is	Lives at
Form Builder	Authoring surface — create, edit, delete form definitions.	/api/formbuilder/*
Form Viewer	Public/runtime surface — open a form and submit it.	/api/form/*
Submissions	Stored submission records — list, read, delete.	/api/form/history/*

Scopes

Scope	Reach
formbuilder:read	Reading form definitions and their thumbnails.
formbuilder:write	Authoring forms in the builder.
forms:read	Opening a form for display.
forms:submit	Submitting data and uploading files to a form.
form_submissions:read	Reading submission records.
form_submissions:write	Deleting submission records.

The split between formbuilder:* (authoring) and forms:* (consumption) is intentional: a role that should never edit forms (e.g., a customer-facing submission token) can carry forms:submit without formbuilder:write.

Workflow: Open, Submit, and Read a Submission

# 1. Open the form definition (by URL or ID) — returns the schema the viewer renders.
FORM=$(curl "https://<tenant>.s-launch.com/api/form/my-intake-form" \
  -H "Authorization: Bearer $TOKEN")
FORM_ID=$(echo $FORM | jq -r '.id')

# 2. (Optional) Upload any file attachments referenced by the form.
curl -X POST "https://<tenant>.s-launch.com/api/form/$FORM_ID/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./brief.pdf"

# 3. Submit the form's structured payload.
SUBMISSION=$(curl -X POST "https://<tenant>.s-launch.com/api/form/$FORM_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answers":{"name":"Alice","email":"alice@example.com"}}')

# 4. Inspect the submission record.
SUBMISSION_ID=$(echo $SUBMISSION | jq -r '.id')
curl "https://<tenant>.s-launch.com/api/form/history/$SUBMISSION_ID" \
  -H "Authorization: Bearer $TOKEN"

The exact submission body shape is governed by FormSubmissionWriteCreate; the response by FormSubmissionRead.

See also

• Conventions — pagination, filtering, and error patterns used by every forms endpoint.
• Factory › Tickets — submissions often trigger factory tickets that run a workflow over the supplied data.
• Scopes › Forms & Form Submissions — the canonical scope list.