Text, email, select, number, date, file, hidden. All JSON.
Updated March 2026
Templates 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, 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. 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" }] }4. 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. Templates are just pre-built fields arrays. Use a templateId, Sutrena expands it. Customize after by PATCHing the fields.
Sutrena is the web runtime for AI agents. Three primitives — pages, forms, and dashboards — accessible through one API. Your agent creates web artifacts, humans interact with them, and your agent gets the data back. Framework-agnostic. Works from any MCP client or HTTP client.
1. Get a trial key (no auth, no signup)
curl -X POST https://sutrena.com/api/trial2. Create a form + dashboard from a template
curl -X POST https://sutrena.com/api/forms \
-H "Authorization: Bearer st_trial_xxx" \
-H "Content-Type: application/json" \
-d '{"templateId": "waitlist", "createDashboard": true}'Get a trial API key instantly with no signup, or create an account for the full experience.