Tools

Every tool checks the token's abilities before running; missing the ability returns a refusal. The tables below cover the complete workspace surface area registered on the server (116 tools).

Plan visibility

tools/list, resources/list, and prompts/list are filtered by the authenticated team's plan. On Free, survey, funnel, webhook, and AI tools (and their matching resources/prompts) are omitted entirely - clients that only read the list will not see them. On Pro and above, the full catalogue is returned.

You can still mint token abilities for paid products on any plan; without the plan feature, those tools either never appear in the list or refuse at call time with a plan error.

* * *

Product routing

• Forms - single-screen contact-style forms. Use create_form, not create_survey.
• Surveys - multi-screen questionnaires, quizzes, NPS. Use create_survey, not create_form.
• Funnels - multi-step lead-gen with screens, blocks, scoring, pixels, CAPI. Use create_funnel.
• Links - branded short links and QR codes on every plan.

Call list_templates with product (form, survey, or funnel) before create_* when the user wants a starter. Pass the returned key as template on create_form, create_survey, or create_funnel.

* * *

Build a complete form, survey, or funnel in one call

set_form_document, set_survey_document, and set_funnel_document are the full authoring path. Each one builds a complete, styled product end-to-end from a single builder document - every field/question type, content blocks, conditional branching, welcome and ending screens, and styling - the same structure the visual builder saves. Prefer them over update_* (or add_screen / add_block) when you are laying out or restyling a product rather than patching one attribute.

Each create_* returns a public_id; pass it as form_id, survey_id, or funnel_id. Pass publish: true to make the result live in the same call.

Document shape

{
  "builder": { "name": "Q4 NPS", "settings": { "display_mode": "one_per_screen", "progress": "bar" } },
  "blocks": [ /* ordered screens / questions / content - see below */ ],
  "theme_v2": { "tokens": { "color": { "primary": "#4f46e5" } } }
}

• builder - the product name plus product-level settings (e.g. survey display_mode / progress).
• blocks[] - the ordered content. Each block has an id, a kind, and a position. A question block carries one or more elements (the input fields / content). welcome, ending_screen, and ending_redirect blocks carry their copy in config. Ids and per-element config defaults are filled in when omitted.
• theme_v2 - the unified styling envelope (colors, fonts, radius, spacing, …) under tokens. This is the canonical styling surface and round-trips with the visual Styling editor. update_* accepts the same theme_v2 when you only want to restyle.

Element vocabulary

The type on each element reaches the full builder palette:

open_text, multiple_choice_single, multiple_choice_multi, picture_selection, ranking, consent, file_upload, rating, nps, csat, ces, matrix, contact_info, cal, cta, timeslots, date, barcode, range_slider

Content blocks render without collecting a submission key: heading, paragraph (a statement, not a textarea input), html, divider. (A typed email input is an open_text element with config.format: "email".)

• Forms and surveys reject an unmapped type with a clear error (so a typo never silently drops a field).
• Funnels never reject an unmapped type. Any type with no native funnel block (nps, matrix, csat, …) degrades loss-free to an inert html block that preserves the original type, so layout and styling always save. Funnel screens that stack several inputs or advance buttons are auto-split one step per screen.

Conditional branching (logic)

Attach a logic rule graph to any question block to branch on an answer. then.action is goto / skip / next, and then.target is the id of the block to jump to (rewritten internally to the right screen):

"logic": {
  "rules": [
    { "when": { "op": "and", "conditions": [ { "field": "score", "op": "lte", "value": 6 } ] },
      "then": { "action": "goto", "target": "blk_reason" } }
  ],
  "fallback": { "action": "next" }
}

Branching round-trips: re-saving a survey or funnel preserves the rules so a later edit never drops a jump.

Welcome and ending screens carry a body

Welcome and ending screens now support a multi-paragraph body alongside the headline and button_label. Author it with newline-separated paragraphs; the hosted page renders and themes each paragraph.

{ "id": "blk_welcome", "kind": "welcome", "position": 0,
  "config": { "headline": "Hi there", "body": "Two minutes, promise.\n\nNo wrong answers.", "button_label": "Start" } }

Example: a survey with NPS, a branch, and a welcome body

set_survey_document {
  "survey_id": "sv_8Qd2",
  "publish": true,
  "document": {
    "builder": { "name": "Q4 NPS", "settings": { "display_mode": "one_per_screen", "progress": "bar" } },
    "blocks": [
      { "id": "blk_welcome", "kind": "welcome", "position": 0,
        "config": { "headline": "Hi there", "body": "Two minutes, promise.\n\nNo wrong answers.", "button_label": "Start" } },
      { "id": "blk_nps", "kind": "question", "position": 1,
        "logic": { "rules": [ { "when": { "op": "and", "conditions": [ { "field": "score", "op": "lte", "value": 6 } ] }, "then": { "action": "goto", "target": "blk_reason" } } ], "fallback": { "action": "next" } },
        "elements": [ { "type": "nps", "name": "score", "config": { "label": "How likely are you to recommend us?" } } ] },
      { "id": "blk_reason", "kind": "question", "position": 2,
        "elements": [ { "type": "open_text", "name": "reason", "config": { "label": "What went wrong?", "long": true } } ] },
      { "id": "blk_email", "kind": "question", "position": 3,
        "elements": [ { "type": "open_text", "name": "email", "config": { "label": "Email", "format": "email", "save_as_contact": true } } ] },
      { "id": "blk_end", "kind": "ending_screen", "position": 4,
        "config": { "headline": "Thanks!", "body": "We appreciate it." } }
    ],
    "theme_v2": { "tokens": { "color": { "primary": "#4f46e5" } } }
  }
}

Example: a styled form in one call

set_form_document {
  "form_id": "r2EdO-orF-3S",
  "document": {
    "builder": { "name": "Contact" },
    "blocks": [
      { "id": "blk_welcome", "kind": "welcome", "position": 0, "config": { "headline": "Get in touch", "body": "We reply within a day." } },
      { "id": "blk_q", "kind": "question", "position": 1, "elements": [
        { "type": "heading", "config": { "text": "Your details", "level": "h2" } },
        { "type": "open_text", "name": "full_name", "config": { "label": "Full name", "required": true } },
        { "type": "open_text", "name": "email", "config": { "label": "Email", "format": "email", "required": true } },
        { "type": "rating", "name": "satisfaction", "config": { "label": "How was it?" } }
      ] },
      { "id": "blk_end", "kind": "ending_screen", "position": 2, "config": { "headline": "Thanks!" } }
    ],
    "theme_v2": { "tokens": { "color": { "primary": "#0ea5e9" } } }
  }
}

Example: a funnel - one block per screen

A funnel document uses one block per screen (a step); each screen's fields/content are its elements. Unmapped types degrade to html rather than failing.

set_funnel_document {
  "funnel_id": "fn_lead_quiz",
  "document": {
    "builder": { "name": "Lead quiz" },
    "blocks": [
      { "id": "blk_welcome", "kind": "welcome", "position": 0, "config": { "headline": "Find your plan", "body": "60 seconds." } },
      { "id": "blk_goal", "kind": "question", "position": 1,
        "logic": { "rules": [ { "when": { "op": "and", "conditions": [ { "field": "goal", "op": "equals", "value": "pro" } ] }, "then": { "action": "goto", "target": "blk_pro" } } ], "fallback": { "action": "next" } },
        "elements": [
          { "type": "heading", "config": { "text": "What's your goal?", "level": "h2" } },
          { "type": "multiple_choice_single", "name": "goal", "config": { "label": "Goal", "options": [ { "value": "starter", "label": "Starter" }, { "value": "pro", "label": "Pro" } ] } },
          { "type": "cta", "config": { "button_text": "Continue" } }
        ] },
      { "id": "blk_pro", "kind": "question", "position": 2,
        "elements": [ { "type": "open_text", "name": "email", "config": { "label": "Work email", "format": "email", "required": true } } ] },
      { "id": "blk_end", "kind": "ending_screen", "position": 3, "config": { "headline": "Thanks!" } }
    ],
    "theme_v2": { "tokens": { "color": { "primary": "#7c3aed" } } }
  }
}

Per-entity captcha, scoring, and notifications

update_form, update_survey, and update_funnel now also set the surrounding configuration the document does not own:

• Captcha is always per-entity, never global. Set hcaptcha_enabled / recaptcha_enabled plus the matching *_site_key / *_secret on the individual form, survey, or funnel. Leaving a secret empty keeps the existing key so an unrelated edit never wipes stored credentials.
• Scoring (scoring), hidden fields (hidden_fields, captured from URL params), notification emails (notification_emails), autoresponder (autoresponder), redirect (redirect_url), and the spam honeypot (honeypot_field).

* * *

Templates

* * *

Forms

* * *

Submissions

* * *

Webhooks

* * *

Surveys

Surveys are a separate product from Forms - multi-screen questionnaires, quizzes, and NPS flows with conditional logic. Never call create_form to make a survey, or create_survey to make a contact form. All survey tools require a paid plan.

Surveys capture CRM contacts from responses. A survey mints a contact whenever it has at least one typed email question. Capture is opt-in per email question via save_as_contact, which defaults on - set it false on a specific question (e.g. "your colleague's email") to opt that one out. Identity is read only from typed email / phone questions, never by scanning free-text answers. Set save_as_contact in the element config when building with set_survey_document.

* * *

Action classes

Action classes are the triggers that decide when an in-app or website survey fires - a code action fires from an SDK track(key) call, a noCode action auto-fires from a spec (page view, click, exit intent, scroll depth, dwell, with optional URL filters). A survey fires when any of its attached triggers fires. Part of the in-app / website survey suite; requires a paid plan.

* * *

Contacts

The CRM audience captured from in-app / website survey responses (and managed directly). A contact is identified by external_user_id and/or email; attributes merge last-write-wins. Requires a paid plan.

* * *

Segments

Segments are reusable survey audiences: each owns a recursive AND/OR filters tree over contact attributes, device class, and nested segment membership. A survey targets one segment. Part of the in-app / website survey suite; requires a paid plan.

* * *

SDK keys

Public environment keys the in-app / website survey SDK embeds in the browser. Each key carries an allowed_origins CORS allow-list - an empty list denies all cross-origin browser use, so add your production origins explicitly. Part of the in-app / website survey suite; requires a paid plan.

* * *

Displays (read-only)

Read-only analytics over survey displays / impressions captured by the SDK. Part of the in-app / website survey suite; requires a paid plan.

* * *

Funnels

Funnels are multi-step lead-gen / quiz funnels with screens, blocks, scoring, pixels, A/B tests, and server-side CAPI. All funnel tools require a paid plan. Funnel tools accept either public_id (preferred, mirrors forms/surveys) or the legacy slug to identify a funnel.

* * *

Links

Branded short links and QR codes. Available on every plan.

* * *

Bio pages

A Bio page is a single public link-in-bio profile (handle, avatar, headline, bio) listing many ordered blocks. It is not a form, survey, funnel, or single link - use these tools, never create_form / create_survey / create_funnel / create_link. Requires a plan that includes Bio Pages.

* * *

Automations

Per-form automation rules with steps that fire on submission events. Available on every plan. Use list_automations with a form's public_id; the team-wide formspring://team/automations resource lists automations across forms, surveys, and funnels.

* * *

Billing (read-only)

* * *

AI Insights

* * *

Tokens (self-management)

* * *

Integration reference

Example call

get_framework_integration_catalog {
  "category": "ssr",
  "page": 1,
  "per_page": 25
}

* * *

Example call

list_submissions {
  form_id: "r2EdO-orF-3S",
  folder: "spam",
  limit: 25
}

returns

{
  "submissions": [
    {
      "id": "01HFXX0X9R7KZJVN9VS6TG2C5T",
      "status": "spam",
      "spam_reason": "akismet",
      "ai_moderation_score": 87,
      "payload": { "email": "spam@bad.com", "message": "..." },
      "created_at": "2026-05-07T16:09:10Z"
    }
  ]
}

* * *

What's next

• Prompt examples →
• Troubleshooting →