Text, email, select, number, date, file, hidden. All JSON.
Updated March 2026
Workflow presets not enough? Define your own fields. Sutrena forms are a JSON fields array. Each field gets a name, type, label, and validation rules. This guide covers every supported type, their options, conditional visibility with showIf, and how to test your form after creation.
1. Design your fields array
Each field needs a name (the JSON key in submissions), a label (what the user sees), a type, and optional validation.
// Supported field types and their options:
// text: { name, label, type: "text", required, placeholder, minLength, maxLength }
// email: { name, label, type: "email", required, placeholder }
// textarea: { name, label, type: "textarea", required, placeholder, minLength, maxLength }
// select: { name, label, type: "select", required, options: string[] }
// number: { name, label, type: "number", required, min, max }
// date: { name, label, type: "date", required }
// tel: { name, label, type: "tel", required, placeholder }
// url: { name, label, type: "url", required, placeholder }
// file: { name, label, type: "file", required, accept, maxFileSize }
// hidden: { name, label, type: "hidden", value }2. Create the form via API
POST the fields array with form metadata. As many fields as you need. The API validates definitions and returns errors for anything malformed.
curl -X POST https://sutrena.com/api/forms \
-H "Authorization: Bearer st_trial_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Event Registration",
"fields": [
{ "name": "name", "label": "Full Name", "type": "text",
"required": true, "placeholder": "Jane Doe" },
{ "name": "email", "label": "Email", "type": "email", "required": true },
{ "name": "phone", "label": "Phone", "type": "tel",
"required": false, "placeholder": "+1 (555) 000-0000" },
{ "name": "ticket_type", "label": "Ticket Type", "type": "select",
"required": true, "options": ["General", "VIP", "Student"] },
{ "name": "guests", "label": "Number of Guests", "type": "number",
"required": true, "min": 1, "max": 10 },
{ "name": "event_date", "label": "Preferred Date", "type": "date",
"required": true },
{ "name": "dietary", "label": "Dietary Restrictions", "type": "textarea",
"required": false, "placeholder": "Allergies, preferences, etc." },
{ "name": "referral_code", "label": "", "type": "hidden",
"value": "LAUNCH2026" }
],
"successMessage": "You are registered! Check your email for confirmation.",
"submitLabel": "Register"
}'3. Add conditional visibility with showIf
Use showIf to show a field only when another field has a specific value. The dependent field is hidden by default and appears when the condition is met. Server-side validation skips hidden required fields automatically.
curl -X POST https://sutrena.com/api/forms \
-H "Authorization: Bearer st_trial_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Job Application",
"fields": [
{ "name": "role", "label": "Role", "type": "select",
"required": true,
"options": ["Developer", "Designer", "PM", "Other"] },
{ "name": "role_other", "label": "Please specify your role",
"type": "text", "required": true,
"showIf": { "field": "role", "equals": "Other" } },
{ "name": "experience", "label": "Years of Experience",
"type": "number", "required": true, "min": 0, "max": 50 },
{ "name": "portfolio_url", "label": "Portfolio URL",
"type": "url", "required": true,
"showIf": { "field": "role", "equals": "Designer" } }
]
}'
# When role = "Other": role_other appears, portfolio_url stays hidden
# When role = "Designer": portfolio_url appears, role_other stays hidden
# When role = "Developer" or "PM": both conditional fields stay hidden
# Server-side validation only requires visible fields4. Test the form with a submission
Submit test data to check your field config. The API validates against your rules and returns specific errors for invalid fields.
# Valid submission:
curl -X POST https://sutrena.com/api/forms/frm_xyz789/submit \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"email": "[email protected]",
"phone": "+1 555 123 4567",
"ticket_type": "VIP",
"guests": 2,
"event_date": "2026-04-15",
"dietary": "Vegetarian"
}'
# Invalid submission (missing required field):
# 400 Bad Request
# { "error": "Validation failed",
# "details": [{ "field": "ticket_type", "message": "Required" }] }
# Invalid submission (number out of range):
# 400 Bad Request
# { "error": "Validation failed",
# "details": [{ "field": "guests", "message": "Must be between 1 and 10" }] }5. Update fields after creation
PATCH to add, remove, or modify fields. Existing submissions stay as they are. New submissions validate against the updated schema.
# Add a new field:
curl -X PATCH https://sutrena.com/api/forms/frm_xyz789 \
-H "Authorization: Bearer st_trial_abc123" \
-H "Content-Type: application/json" \
-d '{
"fields": [
{ "name": "name", "label": "Full Name", "type": "text", "required": true },
{ "name": "email", "label": "Email", "type": "email", "required": true },
{ "name": "phone", "label": "Phone", "type": "tel" },
{ "name": "ticket_type", "label": "Ticket Type", "type": "select",
"options": ["General", "VIP", "Student", "Speaker"], "required": true },
{ "name": "guests", "label": "Number of Guests", "type": "number",
"min": 1, "max": 10, "required": true },
{ "name": "event_date", "label": "Preferred Date", "type": "date", "required": true },
{ "name": "company", "label": "Company", "type": "text" },
{ "name": "dietary", "label": "Dietary Restrictions", "type": "textarea" }
]
}'No hard limit. Most forms have 3-15. The hosted form renders them all on one page.
Yes. Add hidden fields named utm_source, utm_medium, utm_campaign. Set their values dynamically in your frontend before submission.
Yes. They are JSON keys. Stick to lowercase with underscores (snake_case).
Fields render in array order. PATCH the form with the fields array in the order you want.
Yes. Workflow presets are just pre-built fields arrays. Use a workflowId, Sutrena expands it. Customize after by PATCHing the fields.
showIf supports one dependency: one field, one value. For more complex logic (field C depends on both field A and field B), build a custom frontend and handle the visibility in JavaScript. POST the final data to Sutrena.
Sutrena is the web runtime for AI agents. Forms, Pages, Analytics, Webhooks, Automations — all through 67 MCP tools and one REST API. Your agent creates web artifacts, humans interact with them, and your agent gets the data back. Use any one feature or all of them together.
Pages
Deploy HTML instantly
Forms
Collect structured data
Automations
DSL-based pipelines with 14 step types
Analytics
Privacy-first, no cookies
Webhooks
Slack, Discord, Telegram
1. Get a trial key (no auth, no signup)
curl -X POST https://sutrena.com/api/trial2. Create anything — a page, form, automation, or analytics site
# Create a form
curl -X POST https://sutrena.com/api/forms \
-H "Authorization: Bearer st_trial_xxx" \
-H "Content-Type: application/json" \
-d '{"name": "waitlist", "fields": [{"name": "email", "label": "Email", "type": "email", "required": true}]}'
# Or deploy a page
curl -X POST https://sutrena.com/api/pages \
-H "Authorization: Bearer st_trial_xxx" \
-H "Content-Type: application/json" \
-d '{"slug": "index", "title": "My Site", "html": "<h1>Live</h1>"}'Get a trial API key instantly with no signup, or create an account for the full experience.