Wizard Field Types

22 field types for building wizard-style input forms in agents. This guide covers the JSON schema for each field type as returned by the public API.

Overview

Agents can have wizard-style input forms defined in input_schema.steps[].questions[]. Each question is an InputField with a field_type that determines its rendering and behavior.

API endpoint: GET /public/cms/agents/{id} (returns input_schema)

Localization

The public API resolves all translatable fields to plain strings based on the Accept-Language header. All text fields (label, description, placeholder, tooltip, subtitle, on_label, off_label, inner_text, inner_subtitle, content, divider_label) are resolved the same way.

InputField (Common Fields)

Every question shares these fields:

{
  "key": "field_abc123",
  "label": "Upload Photo",
  "description": "Helper text below label",
  "placeholder": "Ghost text inside input",
  "required": true,
  "tooltip": "Tap for more info",
  "default_value": null,
  "visible_when": { "field_key": "mode", "operator": "equals", "value": "advanced" },
  "validation": { "min_length": 1, "max_length": 500, "pattern": "^[a-z]+$" },
  "field_type": { "type": "text_input" }
}

Field	Type	Required	Notes
`key`	string	yes	Unique field identifier
`label`	string	yes	Section heading
`description`	string?	no	Subtitle / helper text
`placeholder`	string?	no	Ghost text inside input
`required`	bool	yes	Shows Required/Optional badge
`tooltip`	string?	no	Info icon tooltip
`default_value`	any	no	Pre-filled value (type varies)
`visible_when`	Condition?	no	Conditional visibility rule
`validation`	object?	no	min_length, max_length, pattern
`field_type`	object	yes	Type-specific config (see below)

Condition (visible_when)

{
  "field_key": "mode",
  "operator": "equals",
  "value": "advanced"
}

Operators: equals, not_equals, contains, not_contains, is_empty, is_not_empty

SelectOption

Used by: Select, Chips, Select Cards, Tab Bar

{
  "value": "option_1",
  "label": "Option One",
  "description": "Subtitle text",
  "media": { "url": "https://cdn.example.com/icon.png", "type": "image" },
  "media_position": "left",
  "is_default": false,
  "credit_delta": 5,
  "tooltip": "Per-option tooltip"
}

Field	Type	Default	Notes
`value`	string	—	Unique key sent as user’s answer
`label`	string	—	Display text
`description`	string?	—	Subtitle below label
`media`	Media?	—	Image/icon per option
`media_position`	`left\|top\|right\|bottom`	`left`	Media placement relative to text
`is_default`	bool	false	Pre-selected on load
`credit_delta`	int?	—	Credit cost adjustment when selected
`tooltip`	string?	—	Per-option tooltip

Field Types

1. Text Input

Single-line text entry.

{
  "type": "text_input",
  "input_mask": "none",
  "character_counter": false,
  "prefix": "$",
  "suffix": "kg"
}

Field	Type	Default	Notes
`input_mask`	`none\|email\|phone\|url\|custom`	`none`	Keyboard type + validation
`custom_mask_pattern`	string?	—	Regex when mask=custom
`character_counter`	bool	false	Live char count
`prefix`	string?	—	Non-editable text before input
`suffix`	string?	—	Non-editable text after input

Default value type: string

2. Text Area

Multi-line text entry.

{
  "type": "text_area",
  "character_counter": false,
  "rows": 3,
  "max_rows": 10
}

3. Number

Numeric input with optional unit label.

{
  "type": "number",
  "min": 0,
  "max": 100,
  "step": 1,
  "unit_label": "px",
  "decimal_mode": "integer"
}

Field	Type	Default	Notes
`decimal_mode`	`auto\|integer\|decimal`	`auto`	Force integer or decimal

4. Slider

Range selection via draggable thumb.

{
  "type": "slider",
  "min": 0,
  "max": 100,
  "step": 1,
  "show_value_label": true,
  "unit_label": "%"
}

5. Image Upload

Single or multi-slot image upload.

{
  "type": "image_upload",
  "accepted_formats": ["jpg", "png", "webp"],
  "camera_gallery": "both",
  "slots": [
    {
      "slot_key": "photo",
      "inner_text": "Add Photo",
      "inner_subtitle": "Max 10MB",
      "min_count": 1,
      "max_count": 1,
      "max_file_size_mb": 10,
      "required": true,
      "face_detection_enabled": false
    }
  ]
}

Slot behavior:

1 slot, max_count=1 → single image upload
1 slot, max_count=N → multi image grid
N slots → named upload boxes

6. Video

Video upload with configurable slots. Same slot fields as Image Upload, plus max_duration_secs: int? per slot.

{
  "type": "video",
  "accepted_formats": ["mp4", "mov", "webm"],
  "camera_gallery": "both",
  "slots": [{ "slot_key": "clip", "max_duration_secs": 60, "required": true }]
}

7. Audio

Audio upload or recording.

{
  "type": "audio",
  "source": "both",
  "slots": [{ "slot_key": "recording", "max_duration_secs": 120 }]
}

source: both | record | upload

8. File Upload

Generic file upload (PDF, docs, spreadsheets).

{
  "type": "file_upload",
  "accepted_types": ["pdf", "docx", "csv"],
  "slots": [{ "slot_key": "document", "max_count": 3, "max_file_size_mb": 25 }]
}

Empty accepted_types = all file types allowed.

9. Toggle

On/off switch.

{
  "type": "toggle",
  "on_label": "Yes",
  "off_label": "No"
}

Default value type: boolean. If labels set → two pill buttons. Otherwise → toggle switch.

10. Select

Pick from a list. Covers single select, multi select, dropdown, radio list, checkbox list, scroll picker.

{
  "type": "select",
  "display_mode": "dropdown",
  "selection_mode": "single",
  "options": []
}

Field	Type	Default
`display_mode`	`dropdown\|radio_list\|checkbox_list\|list\|scroll_wheel`	`dropdown`
`selection_mode`	`single\|multi`	`single`

11. Chips

Compact inline pill selector.

{
  "type": "chips",
  "selection_mode": "single",
  "layout": "wrap",
  "options": []
}

layout: wrap | scroll

12. Select Cards

Visual card selector with images.

{
  "type": "select_cards",
  "selection_mode": "single",
  "card_layout": "grid",
  "columns": 2,
  "card_shape": "rectangular",
  "options": []
}

13. Tab Bar

Fixed horizontal segmented control for mode switching. Always single-select.

{ "type": "tab_bar", "options": [] }

Pair with visible_when on other fields to show/hide based on selected tab.

14. Model Selector

AI model picker. Models come from admin pricing records.

{
  "type": "model_selector",
  "card_layout": "horizontal_scroll",
  "models": [
    {
      "model_id": "openai/gpt-4o",
      "title_override": "GPT-4o",
      "subtitle": "Fast, ~4c/s",
      "is_default": true,
      "credit_delta": 2
    }
  ]
}

15. Voice Selector

TTS voice picker.

{
  "type": "voice_selector",
  "filter": { "model_type": "text_to_speech" }
}

16. Color Picker

Color selection input.

{
  "type": "color_picker",
  "preset_colors": ["#FF0000", "#00FF00", "#0000FF"],
  "allow_custom": true
}

Default value type: string (hex color)

17. URL Input

URL entry with validation.

{
  "type": "url_input",
  "open_in": "browser"
}

open_in: browser | in_app

18. Date/Time Picker

Date, time, or combined picker.

{
  "type": "date_time_picker",
  "mode": "date_only",
  "min_date": "2024-01-01",
  "max_date": "2025-12-31",
  "time_format": "24h"
}

mode: date_only | time_only | date_and_time

19. Variations Selector

Quantity picker for output variations.

{
  "type": "variations_selector",
  "min": 1,
  "max": 4,
  "default": 1
}

20. Template Gallery

Pre-built template picker.

{
  "type": "template_gallery",
  "template_ids": ["template:abc", "template:def"]
}

21. Collapsible Group

Layout container grouping questions under an expandable section.

{
  "type": "collapsible_group",
  "children": ["field_abc", "field_def"],
  "default_open": false
}

children is an array of field keys of nested questions.

22. Content Block

Non-input content injected between questions.

{
  "type": "content_block",
  "display_mode": "text",
  "content": "Important notice...",
  "severity": "info"
}

display_mode: divider | text | component

severity: info | warning | error | success (applies to text mode)

23. Sortable List

Drag-to-rank ordered list of items. The user reorders options; the submitted value is an array of value strings in rank order (best → worst, or whichever order the user set).

Important: the authored order of options is the default ranking shown to the user. There is no default_value for this field type, and the is_default property on individual options is unused and not shown in the admin UI.

Submitted value type: string[] — the option value strings in rank order.

{
  "type": "sortable_list",
  "display_mode": "list",
  "item_content": "text",
  "card_layout": "grid",
  "card_shape": "rectangular",
  "columns": 2,
  "show_position_number": false,
  "allow_add": true,
  "allow_remove": true,
  "min_items": 0,
  "max_items": 8,
  "visible_items": 4,
  "options": [
    { "value": "first", "label": { "locales": { "en": { "value": "First choice" } } } },
    { "value": "second", "label": { "locales": { "en": { "value": "Second choice" } } } }
  ]
}

Parameters

Parameter	Type	Default	Notes
`display_mode`	`list \| grid`	`list`	Single-column list or grid of cards
`item_content`	`text \| text_image \| image`	`text`	What media each item carries
`card_layout`	`grid \| horizontal_scroll \| vertical`	`grid`	Grid sub-layout (grid mode only)
`card_shape`	`rectangular \| square \| rounded \| circular`	`rectangular`	Card shape (grid mode only)
`columns`	`1 \| 2 \| 3`	`2`	Grid columns (grid mode + grid layout only)
`visible_items`	`number \| null`	`null` (all)	Items shown before “See All” appears
`show_position_number`	`boolean`	`false`	Show 1/2/3 label next to each item
`allow_add`	`boolean`	`true`	User may add items at run time
`allow_remove`	`boolean`	`true`	User may remove items at run time
`min_items`	`number`	`0`	Minimum items in submitted ranking
`max_items`	`number \| null`	`null` (options.len())	Maximum items allowed
`options`	`SelectOption[]`	required	The rankable items; their authored order is the default ranking

Validation (save time)

columns must be in 1..=3
visible_items ≤ max_items and ≤ options.len()
min_items ≤ max_items ≤ options.len()
options must be non-empty with unique, non-empty value strings

Validation (submit time)

Every submitted element must exist in options[].value
No duplicates in the submitted array
min_items ≤ len ≤ max_items
When both allow_add and allow_remove are false, the submitted set must equal the full option set (order free)

Legacy alias: display_mode: "compact" normalises to "list".

Template accessors

Access the ranked submission from AI node prompts via {{ trigger.<key>.<accessor> }}:

Accessor	Returns	Notes
(bare key)	String	Newline-numbered labels: `"1. Career\n2. Travel\n…"`
`.ranked`	String	Same as bare key
`.ranked_detailed`	String	Numbered labels with descriptions: `"1. Career — Build a fulfilling career\n…"`
`.csv`	String	Comma-separated labels: `"Career, Travel, Health"`
`.json`	Array	Full ranked items; each object has `rank`, `value`, `label`, `description`, `media_url`, `media_type`
`.labels`	Array	Label strings in rank order
`.values`	Array	Raw value strings in rank order
`.media_urls`	Array	Media URLs in rank order; empty array when `item_content = "text"`
`.first`	Object	The rank-1 item (same shape as one `.json` element)
`.count`	Number	Number of submitted items

.top(n) is not an accessor. Tera, the template engine, has no method-call syntax, so {{ trigger.<key>.top(3) }} is a template error and the workflow is rejected at save time with a validation error on the prompt field — you find out immediately, not from a mangled prompt at run time. Use .first for the single top item. For a top-N subset, combine .labels or .values (arrays in rank order) with Tera’s | slice filter:

{{ trigger.<key>.labels | slice(end=3) | join(sep=", ") }}

Legacy Type Aliases

Old type names are still accepted for backward compatibility:

Old Type	Maps To
`number_input`	`number`
`multi_image_upload`, `slotted_image_upload`	`image_upload`
`audio_upload`, `voice_recording`	`audio`
`video_upload`	`video`
`document_upload`	`file_upload`
`yes_no_buttons`	`toggle`
`single_select`, `multi_select`, `dropdown`, `radio_list`, `checkbox_list`, `scroll_picker`	`select`
`chips_with_icon`	`chips`
`single_select_cards`	`select_cards`
`date_picker`, `time_picker`	`date_time_picker`
`section_divider`, `info_banner`, `field_static_text`	`content_block`

Removed Types

Removed	Use Instead
`gender_selector`	Chips
`photo_source_picker`	Image Upload (`camera_gallery` config)
`platform_selector`	Chips or Select Cards
`avatar_gallery`	Select Cards (circular shape)
`style_selector`	Select Cards (circular shape)
`multi_reference_input`	Removed (no replacement)