Create a new form, including per-screen conditional logic. Requires a WRITE-scoped API key.

Args:

• title (string): form title (required)

• description (string, optional)

• theme (string, optional): one of amber|base|midnight|ocean|sunset|forest|lavender|minimal (default amber, the copper-to-amber FoxForm theme)

• questions (array, optional): array of screen objects ({ id, type, title, required, variableName?, choices?, logic?, ... }); omit to start empty

• thank_you_message (string, optional)

• format ('single_question' | 'single_page' | 'chatbot', optional): how the form is presented (see below)

• sections (array, optional): single_page page groups, [{ id }]

• chatbot_skin ('instagram' | 'whatsapp', optional): chatbot chrome

• chatbot_profile (object, optional): chatbot header profile ({ name, handle, followers_text, phone, status, verified, avatar_url })

Returns: { form } with the created form (including its id and slug). The form starts as a draft — call foxform_publish_form to make it live.

Screen fields are validated: unknown fields are REJECTED instead of being stored and ignored, and branching rules are cross-checked against the screen ids in the same payload.

Form format (DEVF-296 / DEVF-322): pass format to choose how the form is presented.

• 'single_question' (default): one screen at a time (classic).

• 'single_page': every screen on one scrollable page. Optionally group screens into pages with sections: [{ id }] in order (the 'Section N' label comes from position; no editable title).

• 'chatbot': an Instagram/WhatsApp DM-style conversation. Set chatbot_skin ('instagram' | 'whatsapp', default instagram) and chatbot_profile (all fields optional, each with a fallback). The question/branching engine is unchanged — only the presentation differs. These fields require the account's form-format feature to be enabled (live in production); when off the API ignores them and the form stays single_question.

CONDITIONAL LOGIC (branching), per screen — stored in questions[].logic:

logic.conditionalNavigationV2 = { enabled: true, groups: [ // groups are OR-joined; FIRST matching group wins { id: "grp-1", conditions: [ // conditions inside a group are AND-joined { id: "cond-1", left: "{{quer_testar}}", operator: "equal_to", right: "Ainda não" } ], then: { type: "specific_screen", targetScreenId: "s-motivos" } } ] }

• then.type: 'next_screen' | 'previous_screen' | 'specific_screen' (needs targetScreenId = another screen's id) | 'end_form'. Add then.url (+ optional openNewTab) to redirect to an external URL instead.

• operator: 'equal_to' | 'not_equal_to' | 'greater_than' | 'greater_or_equal_than' | 'less_than' | 'less_or_equal_than' | 'contains'.

• left/right are EXPRESSION strings: a literal ("10", "Ainda não"), a variable ("{{score}}", "{{minha_var}}" = the screen's variableName), or arithmetic ("calc({{peso}}/(({{altura}}/100)*({{altura}}/100)))").

• Comparing an ANSWER: use left: "{{<variableName of the deciding screen>}}" and right = the option's label OR its value (both match).

• {{score}} is the running sum of points on the options picked so far (choices[].points, images[].points) — that is how score-based branching works.

• A navigation group with no conditions NEVER matches. enabled: false stores the rules but disables them.

• Screen-level conditional display uses the same group shape: logic.display = { enabled: true, groups: [...], showAfterSeconds?: n } (then is ignored — THEN means "show").

• Other logic keys: logic.autoAdvance = { enabled, delaySeconds? }, logic.navigationBehavior = { onButtonClick?, onAutoAdvance?, targetScreenId? }.

• logic.conditionalNavigation (legacy, pre-DEVF-161) is still read and migrated on load — don't author new rules with it.

Unknown fields are REJECTED (they used to be stored and silently ignored): logic as an array, or rules/branching/conditions/goto/jump/nextScreen anywhere, are not read by any renderer.