asksteps: read one form as an editable structure
asksteps_get_formRead-onlyIdempotent
Reads one form of the connected asksteps account as a structure of steps and fields — the same shape asksteps_update_form takes. Requires "forms:read". ALWAYS call this before asksteps_update_form: the write replaces the whole form, so you need the current state to keep what you are not changing. The answer also tells you whether writing is allowed at all (field "editable").
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| form_id | Yes | The form id, as returned by asksteps_list_forms. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The name of the form as the customer sees it in their account. | |
| note | Yes | One sentence for the user, explaining the outcome and what to do next. | |
| spec | No | The structure of the form: steps and fields, in the same shape asksteps_update_form expects. | |
| formId | No | The id of the form, to pass back to asksteps_update_form. | |
| status | Yes | Outcome. One of: "ok", "not_connected", "not_found", "not_a_form" (this is a funnel with branching, which this tool cannot describe), "error". Authorisation can also refuse before the tool runs: "plan_required" (the account's plan does not include agent access), "not_enabled" (the account owner has not switched agent access on), "owner_required" (only the account owner may do this), "mandate_required" (the owner has not granted a mandate for this). The note then says what the user has to do. | |
| editable | No | Whether asksteps_update_form may write this form back. When false, DO NOT try — the form contains things this format cannot describe, and writing would delete them. Tell the user to edit it in the asksteps studio instead, and say why. | |
| blockedBy | No | Why writing is blocked, in one sentence. Empty when editable. | |
| themeCustomized | No | True when the form uses a hand-built design instead of one of the presets. The themeId in the spec then does NOT describe what the user sees — say so instead of naming the preset. Leaving themeId empty keeps the hand-built design; setting it replaces it. | |
| screensBlockedBy | No | Why the intro/success/dismiss pages must not be sent back, in one sentence. Empty when they may be. When this is set, still change the form — just leave "screens" out of the spec, and the existing pages stay untouched. |