{ "openapi": "3.1.0", "info": { "title": "Formasty Forms API", "version": "1.0.0", "description": "Create, inspect, edit, validate, publish, and read Formasty forms with OAuth 2.0 or an account-owned API key." }, "servers": [ { "url": "https://app.formasty.com/api/v1" } ], "security": [ { "FormastyOAuth": [] }, { "FormastyApiKey": [] } ], "components": { "securitySchemes": { "FormastyOAuth": { "type": "oauth2", "description": "Formasty OAuth authorization-code flow with PKCE and refresh tokens.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.formasty.com/oauth/authorize/api/v1", "tokenUrl": "https://app.formasty.com/oauth/token", "scopes": { "forms:read": "Read forms", "forms:create": "Create forms", "forms:update": "Update forms", "forms:delete": "Delete forms", "forms:publish": "Publish forms", "forms:steps:write": "Edit steps", "forms:fields:write": "Edit fields", "forms:logic:write": "Edit logic", "forms:design:write": "Edit design", "submissions:read": "Read submissions", "submissions:create": "Create submissions", "submissions:update": "Update submissions", "submissions:delete": "Delete submissions" } } } }, "FormastyApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Formasty API key" } }, "responses": { "AgentError": { "description": "A machine-readable error with a stable code and a recovery hint. The legacy error value is retained for existing clients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": { "FormId": { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } }, "StepId": { "in": "path", "name": "step_id", "required": true, "schema": { "type": "string" } }, "FieldId": { "in": "path", "name": "field_id", "required": true, "schema": { "type": "string" } }, "DraftRevisionQuery": { "in": "query", "name": "draft_revision", "required": true, "schema": { "type": "integer" } } }, "schemas": { "FormSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "workspace_id", "title", "status", "draft_revision", "published_draft_revision", "draft_updated_at", "public_url" ], "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "draft_revision": { "type": "integer", "minimum": 0 }, "published_draft_revision": { "type": [ "integer", "null" ], "minimum": 0, "description": "Draft revision currently represented by the published snapshot, or null for an unpublished or legacy snapshot." }, "draft_updated_at": { "type": "integer" }, "public_url": { "type": [ "string", "null" ] }, "public_id": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "workspace_role": { "type": "string" }, "permissions": { "type": "object", "additionalProperties": { "type": "boolean" } }, "plan_access": { "type": "object", "additionalProperties": true }, "is_shared": { "type": "boolean" }, "shared_member_count": { "type": "integer" }, "responses_count": { "type": "integer" }, "views_count": { "type": [ "integer", "null" ] }, "starts_count": { "type": [ "integer", "null" ] }, "completions_count": { "type": [ "integer", "null" ] }, "schema_version": { "type": "integer" }, "published_version": { "type": "integer" }, "published_at": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } }, "DraftSchema": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ], "description": "Current builder schema version." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable step id. Supply one only when you need a caller-controlled id; otherwise Formasty can generate it." }, "title": { "type": "string" }, "backButtonLabel": { "type": "string" }, "nextButtonLabel": { "type": "string" }, "welcomeOverline": { "type": "string" }, "showWelcomeStepInfo": { "type": "boolean" }, "showWelcomeQuestionCount": { "type": "boolean" }, "showWelcomeTimeEstimate": { "type": "boolean" }, "welcomeIcon": { "type": "string", "enum": [ "none", "sparkles", "rocket", "gem", "heart_handshake", "briefcase_business", "building_2", "store", "landmark", "globe_2", "shield_check", "graduation_cap" ] }, "welcomeIconCustomUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "coverImageUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "coverImageAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "coverImageBrightness": { "type": "integer", "minimum": 40, "maximum": 140 }, "coverImageLayout": { "type": "string", "enum": [ "stack", "split", "wallpaper" ] }, "coverImageSplitSide": { "type": "string", "enum": [ "left", "right" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable field id. Required when adding a field only if you need a caller-supplied id; ignored by update_field patches." }, "type": { "type": "string", "enum": [ "text", "email", "number", "signature", "scheduler", "rating", "nps", "opinion_scale", "matrix", "file_upload", "video_audio", "address", "date", "textarea", "statement", "select", "radio", "picture_choice", "ranking", "checkbox" ], "description": "Builder field type. Reuse the exact type strings returned by formasty_get_form()." }, "label": { "type": "string", "description": "Primary field label shown to respondents." }, "required": { "type": "boolean", "description": "Whether the respondent must answer this field." }, "hidden": { "type": "boolean", "description": "Whether the field is hidden from respondents and mainly used for workflow/data capture." }, "helpText": { "type": "string", "description": "Helper copy shown below the label." }, "description": { "type": "string", "description": "Alias for helpText accepted by MCP field mutations. Prefer helpText for canonical draft schemas." }, "requiredMessage": { "type": "string" }, "defaultValue": { "type": "string" }, "urlParameter": { "type": "string", "description": "URL parameter name used for prefill when the field type supports it." }, "placeholder": { "type": "string" }, "textSubtype": { "type": "string", "enum": [ "phone", "website" ] }, "textareaSize": { "type": "string", "enum": [ "small", "medium", "large", "extralarge" ] }, "statementEmbedUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "statementAlign": { "type": "string", "enum": [ "left", "center" ] }, "minNumber": { "type": "number" }, "maxNumber": { "type": "number" }, "minCharacters": { "type": "integer", "minimum": 0 }, "maxCharacters": { "type": "integer", "minimum": 1 }, "addressVisibility": { "type": "object", "properties": { "line2": { "type": "boolean" }, "city": { "type": "boolean" }, "state": { "type": "boolean" }, "postalCode": { "type": "boolean" }, "country": { "type": "boolean" } }, "description": "Address subfield visibility controls.", "additionalProperties": false }, "addressConfig": { "type": "object", "properties": { "line1": { "type": "object", "properties": { "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "label", "placeholder", "required" ], "additionalProperties": false }, "line2": { "type": "object", "properties": { "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "label", "placeholder", "required" ], "additionalProperties": false }, "city": { "type": "object", "properties": { "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "label", "placeholder", "required" ], "additionalProperties": false }, "state": { "type": "object", "properties": { "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "label", "placeholder", "required" ], "additionalProperties": false }, "postalCode": { "type": "object", "properties": { "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "label", "placeholder", "required" ], "additionalProperties": false }, "country": { "type": "object", "properties": { "label": { "type": "string" }, "placeholder": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "label", "placeholder", "required" ], "additionalProperties": false } }, "description": "Per-subfield address labels, placeholders, and required flags.", "additionalProperties": false }, "maxStars": { "type": "integer", "minimum": 1 }, "allowHalfStars": { "type": "boolean" }, "minScaleValue": { "type": "integer", "enum": [ 0, 1 ] }, "maxScale": { "type": "integer", "minimum": 2 }, "leftLabel": { "type": "string" }, "rightLabel": { "type": "string" }, "singleRowOnMobile": { "type": "boolean" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable option id. Reuse existing ids when editing an existing field; supply a new id when adding a new option." }, "label": { "type": "string", "description": "Human-readable option label shown in the form." }, "value": { "type": "string", "description": "Submitted option value. Keep it stable once the form is live unless you intend to change downstream data." }, "imageUrl": { "type": "string", "description": "Optional image URL for picture choice options. Leave unset for text-only choices." }, "calcValue": { "type": "number", "description": "Optional numeric value contributed to calculated variables when this option is selected (select, radio, picture_choice, checkbox only; not ranking/matrix). Finite, |value| <= 1e9; decimals allowed." } }, "required": [ "id", "label", "value" ], "description": "Choice option payload used by select, radio, checkbox, picture_choice, ranking, and matrix fields.", "additionalProperties": false } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable option id. Reuse existing ids when editing an existing field; supply a new id when adding a new option." }, "label": { "type": "string", "description": "Human-readable option label shown in the form." }, "value": { "type": "string", "description": "Submitted option value. Keep it stable once the form is live unless you intend to change downstream data." }, "imageUrl": { "type": "string", "description": "Optional image URL for picture choice options. Leave unset for text-only choices." }, "calcValue": { "type": "number", "description": "Optional numeric value contributed to calculated variables when this option is selected (select, radio, picture_choice, checkbox only; not ranking/matrix). Finite, |value| <= 1e9; decimals allowed." } }, "required": [ "id", "label", "value" ], "description": "Choice option payload used by select, radio, checkbox, picture_choice, ranking, and matrix fields.", "additionalProperties": false } }, "allowMultipleSelection": { "type": "boolean" }, "maxFileSizeMb": { "type": "number", "minimum": 1 }, "allowMultiple": { "type": "boolean" }, "allowedFileTypes": { "type": "array", "items": { "type": "string" }, "description": "Allowed upload file type ids. Reuse values already supported by the Forms API/upload configuration." }, "schedulerProvider": { "type": "string", "enum": [ "tidycal", "calendly", "savvycal", "calcom" ] }, "schedulerUrl": { "type": "string", "description": "Public booking URL for scheduler fields. If omitted or empty, MCP returns a scheduler_url_missing notice that the agent must tell the user about." }, "calendarOpenerLabel": { "type": "string" }, "randomizeOptions": { "type": "boolean" }, "horizontalOptions": { "type": "boolean" }, "optionColumns": { "type": "integer", "enum": [ 1, 2, 3 ] }, "checkboxMode": { "type": "string", "enum": [ "multi", "single", "yes_no" ] }, "includeOtherOption": { "type": "boolean" }, "selectionLimitMode": { "type": "string", "enum": [ "none", "exact", "range" ] }, "selectionLimitExact": { "type": "integer", "minimum": 1 }, "selectionLimitMin": { "type": "integer", "minimum": 1 }, "selectionLimitMax": { "type": "integer", "minimum": 1 }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable option id. Reuse existing ids when editing an existing field; supply a new id when adding a new option." }, "label": { "type": "string", "description": "Human-readable option label shown in the form." }, "value": { "type": "string", "description": "Submitted option value. Keep it stable once the form is live unless you intend to change downstream data." }, "imageUrl": { "type": "string", "description": "Optional image URL for picture choice options. Leave unset for text-only choices." }, "calcValue": { "type": "number", "description": "Optional numeric value contributed to calculated variables when this option is selected (select, radio, picture_choice, checkbox only; not ranking/matrix). Finite, |value| <= 1e9; decimals allowed." } }, "required": [ "id", "label", "value" ], "description": "Choice option payload used by select, radio, checkbox, picture_choice, ranking, and matrix fields.", "additionalProperties": false }, "description": "Choice options. Required for select, radio, checkbox, picture_choice, and ranking fields." } }, "required": [ "type", "label", "required" ], "description": "Field payload for add_field and full draft schemas. MCP exposes every active builder field type except payment. Choice fields also require options with id, label, and value. Do not add respondent input fields to the leading welcome screen; add them to a later question step.", "additionalProperties": false }, "description": "Ordered field list for this step. Multiple respondent input fields are allowed when they belong together on the same screen, such as compact contact details or tightly related grouped follow-ups." } }, "required": [ "fields" ], "description": "Draft step payload. Use formasty_get_form() as the canonical source of current step ids and structure. The leading welcome screen must be a statement-only intro; respondent input fields belong in later steps and may be grouped when the form experience benefits from multiple fields on one screen.", "additionalProperties": false }, "description": "Ordered draft steps. MCP supports a leading welcome screen as the first statement-only step. Later question steps may contain one or multiple fields when grouping improves the respondent experience." }, "settings": { "type": "object", "properties": { "name": { "type": "string", "description": "Form title shown across builder, dashboard, and public runtime." }, "description": { "type": "string" }, "slug": { "type": "string" }, "searchEngineIndexing": { "type": "boolean", "description": "Legacy explicit discovery permission. Use discoveryMode for workspace inheritance. Live current-owner consent, publication and open access remain required. Imports/copies stay off. Responses and result-share URLs remain noindex." }, "discoveryMode": { "type": "string", "enum": [ "inherit", "on", "off" ], "description": "inherit follows the current owner's all/selected/none workspace default; on explicitly enables this form even with default none; off always disables it. Legacy schemas without this property use searchEngineIndexing as an explicit override. New ordinary forms inherit; imports/copies stay off. Google indexing/ranking is not guaranteed." }, "successMessage": { "type": "string" }, "redirectUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "submitButtonLabel": { "type": "string" }, "labels": { "type": "object", "properties": { "nextQuestionKeyboardInstruction": { "type": "string" }, "submitKeyboardInstruction": { "type": "string" }, "otherOptionLabel": { "type": "string" }, "otherOptionHint": { "type": "string" }, "uploadInstruction": { "type": "string" }, "uploadMaxFileSizeMessage": { "type": "string" }, "uploadInProgressMessage": { "type": "string" }, "uploadFinishingMessage": { "type": "string" }, "offlineErrorMessage": { "type": "string" }, "onlineRestoredMessage": { "type": "string" }, "serverErrorMessage": { "type": "string" }, "uploadErrorMessage": { "type": "string" }, "uploadFileSizeErrorMessage": { "type": "string" }, "uploadFileTypeErrorMessage": { "type": "string" }, "schedulerRequiredErrorMessage": { "type": "string" }, "duplicateSubmissionTitle": { "type": "string" }, "duplicateSubmissionDescription": { "type": "string" } }, "description": "Runtime copy labels shown across the live form and embeds.", "additionalProperties": false }, "builder": { "type": "object", "properties": { "createStepPerField": { "type": "boolean" }, "requiresProPublish": { "type": "boolean", "readOnly": true, "description": "Server-managed publish gate. Preserve a returned true value; do not set this property on new drafts." } }, "description": "Builder-only editing preferences.", "additionalProperties": false }, "hidden": { "type": "object", "properties": { "hiddenFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Hidden field key. Use only letters, numbers, and underscores." }, "defaultValue": { "type": "string", "description": "Default hidden field value." } }, "required": [ "key", "defaultValue" ], "additionalProperties": false } }, "variables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable workflow variable id. Omit when creating a new variable, or provide an existing id to update that variable." }, "name": { "type": "string", "description": "Workflow variable token name. Use only letters, numbers, and underscores." }, "type": { "type": "string", "enum": [ "number", "text" ], "description": "Variable value type used by workflow conditions and actions." }, "initialValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ], "description": "Optional initial value. Number variables require a numeric value; text variables accept a string." }, "formula": { "type": "string", "description": "Optional formula (number variables only) turning this into a calculated variable. Refs: {{var:}} and {{field:}}. Functions: IF, MIN, MAX, ROUND, FLOOR, CEIL, ABS. Operators + - * / and comparisons. Max 500 chars. Must reference existing fields/variables; no self/circular references. Calculated variables cannot be targets of workflow variable actions." }, "format": { "type": "object", "description": "Optional display format for a number/calculated variable shown on the form.", "properties": { "kind": { "type": "string", "enum": [ "number", "currency", "percent" ], "description": "Display format kind." }, "currency": { "type": "string", "description": "ISO currency code, required when kind is currency (USD, EUR, GBP, INR, CAD, AUD, JPY, AED, SGD)." }, "decimals": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Optional decimal places." } }, "required": [ "kind" ], "additionalProperties": false }, "showOnForm": { "type": "boolean", "description": "When true, show a live result pill for this calculated variable on the public form." } }, "required": [ "name", "type" ], "description": "Workflow variable definition stored in settings.hidden.variables.", "additionalProperties": false }, "description": "Workflow-tab variable definitions available to variable conditions and variable actions." } }, "description": "Hidden fields and Workflow variables. Prefer formasty_configure_workflow_variables for narrow variable-only MCP edits.", "additionalProperties": false }, "submissions": { "type": "object", "properties": { "autosaveProgress": { "type": "boolean", "description": "Stores respondent progress in their browser so reopening the same public form can continue from the last session." }, "anonymousResponses": { "type": "boolean", "description": "When true, Formasty avoids collecting respondent identity metadata that is not part of the submitted answers." }, "preventDuplicates": { "type": "boolean" }, "dedupe": { "type": "object", "properties": { "cookie": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "uniqueField": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fieldId": { "type": "string", "description": "Field id used for duplicate prevention." }, "normalize": { "type": "string", "enum": [ "lower_trim", "trim", "none" ] } }, "description": "Unique-field duplicate prevention settings.", "additionalProperties": false } }, "description": "Submission dedupe controls.", "additionalProperties": false }, "thankYou": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "message", "redirect" ] }, "redirectUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "title": { "type": "string" }, "description": { "type": "string" }, "message": { "type": "string" }, "showSocialShareIcons": { "type": "boolean" }, "socialShareLinks": { "type": "object", "properties": { "facebook": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "x": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "linkedin": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "description": "Optional social share links rendered on thank-you screens.", "additionalProperties": false }, "showButton": { "type": "boolean" }, "buttonLabel": { "type": "string" }, "buttonUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "buttonOpenInNewTab": { "type": "boolean" }, "mediaUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "mediaAlt": { "type": "string" }, "mediaAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "logoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "logoAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "titleSize": { "type": "string", "enum": [ "sm", "md", "lg" ] }, "textAlign": { "type": "string", "enum": [ "left", "center" ] }, "backgroundColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "backgroundImageUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "backgroundImageAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "backgroundImageBrightness": { "type": "integer", "minimum": 40, "maximum": 140 }, "headingColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "descriptionColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonBackgroundColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonTextColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonRadius": { "type": "string", "enum": [ "none", "sm", "lg" ], "description": "Thank-you button radius. Allowed values are only \"none\", \"sm\", and \"lg\"; \"md\" is not supported." }, "resultPage": { "type": "object", "properties": { "highlights": { "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 160 }, "description": "Optional concise result-page bullets. Empty strings are ignored." }, "cta": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80 }, "url": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "label", "url" ], "description": "Optional result-page CTA. Use a real URL only; do not invent booking links.", "additionalProperties": false } }, "description": "Optional scorecard/result-page block for useful outcome summaries, highlights, and CTAs on thank-you screens.", "additionalProperties": false } }, "required": [ "mode" ], "description": "Primary submission thank-you configuration.", "additionalProperties": false }, "thankYouScreens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable thank-you screen id." }, "title": { "type": "string" }, "description": { "type": "string" }, "message": { "type": "string" }, "showSocialShareIcons": { "type": "boolean" }, "socialShareLinks": { "type": "object", "properties": { "facebook": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "x": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "linkedin": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "description": "Optional social share links rendered on thank-you screens.", "additionalProperties": false }, "showButton": { "type": "boolean" }, "buttonLabel": { "type": "string" }, "buttonUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "buttonOpenInNewTab": { "type": "boolean" }, "mediaUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "mediaAlt": { "type": "string" }, "mediaAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "logoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "logoAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "titleSize": { "type": "string", "enum": [ "sm", "md", "lg" ] }, "textAlign": { "type": "string", "enum": [ "left", "center" ] }, "backgroundColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "backgroundImageUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "backgroundImageAttribution": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "unsplash" ] }, "photographerName": { "type": "string" }, "photographerUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "sourceName": { "type": "string", "enum": [ "Unsplash" ] }, "sourceUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "photoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "provider", "photographerName", "photographerUrl", "sourceUrl" ], "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.", "additionalProperties": false }, "backgroundImageBrightness": { "type": "integer", "minimum": 40, "maximum": 140 }, "headingColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "descriptionColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonBackgroundColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonTextColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonRadius": { "type": "string", "enum": [ "none", "sm", "lg" ], "description": "Thank-you button radius. Allowed values are only \"none\", \"sm\", and \"lg\"; \"md\" is not supported." }, "resultPage": { "type": "object", "properties": { "highlights": { "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 160 }, "description": "Optional concise result-page bullets. Empty strings are ignored." }, "cta": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80 }, "url": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." } }, "required": [ "label", "url" ], "description": "Optional result-page CTA. Use a real URL only; do not invent booking links.", "additionalProperties": false } }, "description": "Optional scorecard/result-page block for useful outcome summaries, highlights, and CTAs on thank-you screens.", "additionalProperties": false } }, "required": [ "id" ], "description": "Additional thank-you screen definition used by branching, match/personality quiz endings, and score quiz ranges.", "additionalProperties": false } } }, "description": "Submission behavior, duplicate prevention, and thank-you screen configuration.", "additionalProperties": false }, "privacy": { "type": "object", "properties": {}, "description": "Privacy settings use the same contract returned by formasty_get_form(). Preserve unknown keys unless you intentionally change them.", "additionalProperties": true } }, "description": "Top-level form settings contract used in full draft schemas.", "additionalProperties": false }, "theme": { "type": "object", "properties": { "fontFamily": { "type": "string", "enum": [ "system", "custom", "sohne", "satoshi", "plus_jakarta_sans", "inter", "manrope", "dm_sans", "poppins", "nunito", "playfair_display", "roboto_slab", "space_grotesk", "ibm_plex_mono" ] }, "customFont": { "type": "object", "properties": { "family": { "type": "string" }, "fileName": { "type": "string" }, "assetId": { "type": "string" }, "format": { "type": "string", "enum": [ "woff2", "woff", "ttf", "otf" ] }, "url": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "storageKey": { "type": "string" } }, "required": [ "family", "fileName", "assetId", "format", "url" ], "description": "Uploaded custom font metadata. Reuse the exact values returned by the font upload flow.", "additionalProperties": false }, "baseFontSize": { "type": "string", "enum": [ "sm", "md", "lg" ] }, "labelWeight": { "type": "string", "enum": [ "normal", "medium", "semibold" ] }, "backgroundColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "fontSizeScale": { "type": "string", "enum": [ "compact", "default", "spacious" ] }, "headingWeight": { "type": "integer", "enum": [ 600, 700 ] }, "background": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "solid" ] }, "value": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." } }, "required": [ "type", "value" ], "additionalProperties": false, "description": "MCP-created and MCP-edited forms use solid form backgrounds only. Use backgroundColor for the page background; keep outcome-specific colors on thank-you screens." }, "surfaceColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "textColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "accentColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "linkColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "borderColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "buttonTextColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "primaryColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "secondaryColor": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "borderIntensity": { "type": "string", "enum": [ "subtle", "medium" ] }, "radius": { "type": "string", "enum": [ "none", "sm", "md", "lg" ] }, "density": { "type": "string", "enum": [ "compact", "comfortable", "airy" ] }, "inputSpacing": { "type": "string", "enum": [ "compact", "comfortable", "airy" ] }, "width": { "type": "string", "enum": [ "narrow", "medium", "wide" ] }, "progress": { "type": "string", "enum": [ "none", "fraction", "dots" ] }, "progressStyle": { "type": "string", "enum": [ "none", "step_count", "bar" ] }, "previewMode": { "type": "string", "enum": [ "single-step", "stacked" ] }, "buttonStyle": { "type": "string", "enum": [ "filled", "outline" ] }, "alignment": { "type": "string", "enum": [ "left", "center", "right" ] }, "brandPalette": { "type": "array", "maxItems": 8, "items": { "type": "string", "description": "Color token such as #RRGGBB, rgb(...), or rgba(...). Use the same values returned by formasty_get_form." }, "description": "Optional brand palette swatches shown in the builder design system." }, "hoverLift": { "type": "boolean" }, "showBrandBadge": { "type": "boolean" }, "branding": { "type": "object", "properties": { "showPoweredBy": { "type": "boolean", "description": "Whether to show Formasty branding badges where the current plan allows it." }, "logoUrl": { "type": "string", "description": "Absolute URL string. Prefer https URLs for public assets and integrations." }, "logoScale": { "type": "number", "minimum": 0.7, "maximum": 1.3 } }, "description": "Branding controls nested under theme.branding.", "additionalProperties": false } }, "description": "Partial theme patch. Use the same keys returned by formasty_get_form().form.draftSchema.theme.", "additionalProperties": false }, "workflow": { "type": "object", "properties": { "version": { "type": "integer", "enum": [ 1 ] }, "enabled": { "type": "boolean" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable workflow rule id. Reuse existing ids when replacing or editing current rules." }, "title": { "type": "string", "description": "Optional human-readable rule label shown in the workflow UI." }, "source": { "type": "object", "properties": { "stepId": { "type": "string", "description": "Source step id for the rule." }, "fieldId": { "type": "string", "description": "Optional source field id when branching from a specific field." } }, "required": [ "stepId" ], "additionalProperties": false }, "match": { "type": "string", "enum": [ "all", "any" ] }, "combinator": { "type": "string", "enum": [ "and", "or" ] }, "conditions": { "type": "array", "description": "Workflow conditions. Use an empty array for an unconditional 'always go to' route, especially for statement-only steps.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable condition id. Reuse existing ids when editing an existing rule." }, "sourceType": { "type": "string", "enum": [ "field", "hidden_field", "variable" ], "description": "What the condition reads from." }, "sourceId": { "type": "string", "description": "Hidden field key or variable id depending on sourceType. For field conditions, prefer fieldId; sourceId is accepted as a compatibility alias." }, "fieldId": { "type": "string", "description": "Field id when the condition reads from a form field." }, "target": { "type": "object", "properties": { "subfieldKey": { "type": "string", "description": "Optional subfield key for structured values such as address parts." }, "rowKey": { "type": "string", "description": "Optional matrix row key when a workflow condition targets a matrix row value." } }, "description": "Optional workflow target selector for structured field values.", "additionalProperties": false }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "contains", "not_contains", "starts_with", "ends_with", "includes", "not_includes", "gt", "gte", "lt", "lte", "between", "is_answered", "is_not_answered" ], "description": "Comparison operator. Use only operators that are already valid for the chosen source/target." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, { "type": "object", "properties": { "min": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "max": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "min", "max" ], "additionalProperties": false }, { "type": "array", "minItems": 1, "items": { "type": "string" } } ], "description": "Condition value. For between, use [min,max] or {min,max}. For includes/not_includes on multi-choice values, use a string array." } }, "required": [ "id", "operator" ], "description": "Workflow condition. Reuse field ids, variable ids, hidden field keys, and target ids already present in the current form snapshot.", "additionalProperties": false } }, "logic": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "simple", "custom" ], "description": "Rule logic mode." }, "nodes": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "condition" ] }, "conditionId": { "type": "string" } }, "required": [ "id", "type", "conditionId" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "group" ] }, "groupId": { "type": "string" } }, "required": [ "id", "type", "groupId" ], "additionalProperties": false } ] } }, "combinators": { "type": "array", "items": { "type": "string", "enum": [ "and", "or" ] } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "combinator": { "type": "string", "enum": [ "and", "or" ] }, "conditionIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "combinator", "conditionIds" ], "additionalProperties": false } } }, "description": "Optional advanced workflow logic tree. Preserve ids when editing existing logic.", "additionalProperties": false }, "then": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "step" ] }, "stepId": { "type": "string", "description": "Destination draft step id." } }, "required": [ "type", "stepId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thank_you" ] }, "screenId": { "type": "string", "description": "Thank-you screen id from settings.submissions.thankYouScreens." } }, "required": [ "type", "screenId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "type" ], "additionalProperties": false } ], "description": "Workflow destination. Use existing step ids or thank-you screen ids from formasty_get_form." }, "thenAction": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable action id. Reuse existing ids when patching current workflow rules." }, "variableId": { "type": "string", "description": "Workflow variable id to modify." }, "operation": { "type": "string", "enum": [ "set", "add", "subtract", "multiply", "divide", "clear", "append", "prepend" ], "description": "Workflow variable operation." }, "source": { "type": "object", "properties": { "sourceType": { "type": "string", "enum": [ "literal", "field", "hidden_field", "variable" ], "description": "Where the workflow variable action should read its value from." }, "sourceId": { "type": "string", "description": "Hidden field key or variable id depending on sourceType. For field sources, prefer fieldId; sourceId is accepted as a compatibility alias." }, "fieldId": { "type": "string", "description": "Field id when reading from a form field." }, "target": { "type": "object", "properties": { "subfieldKey": { "type": "string", "description": "Optional subfield key for structured values such as address parts." }, "rowKey": { "type": "string", "description": "Optional matrix row key when a workflow condition targets a matrix row value." } }, "description": "Optional workflow target selector for structured field values.", "additionalProperties": false }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Literal fallback value used when sourceType is literal." } }, "description": "Workflow variable action source. Reuse ids and targets from the current draft snapshot.", "additionalProperties": false } }, "required": [ "id", "variableId", "operation" ], "description": "Workflow variable mutation attached to a rule or step action.", "additionalProperties": false }, "else": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "step" ] }, "stepId": { "type": "string", "description": "Destination draft step id." } }, "required": [ "type", "stepId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thank_you" ] }, "screenId": { "type": "string", "description": "Thank-you screen id from settings.submissions.thankYouScreens." } }, "required": [ "type", "screenId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "type" ], "additionalProperties": false } ], "description": "Workflow destination. Use existing step ids or thank-you screen ids from formasty_get_form." }, "priority": { "type": "integer", "description": "Lower numbers run first when multiple rules apply." }, "stopProcessing": { "type": "boolean", "description": "Stop evaluating later rules after this one matches." } }, "required": [ "source", "conditions", "then" ], "description": "Workflow rule payload. Use existing ids from formasty_get_form whenever you are editing a current rule; omit id when creating a new rule. An empty conditions array creates an unconditional always-route.", "additionalProperties": false } }, "fallback": { "type": "object", "properties": {}, "description": "Per-step fallback routing keyed by step id.", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "step" ] }, "stepId": { "type": "string", "description": "Destination draft step id." } }, "required": [ "type", "stepId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thank_you" ] }, "screenId": { "type": "string", "description": "Thank-you screen id from settings.submissions.thankYouScreens." } }, "required": [ "type", "screenId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "type" ], "additionalProperties": false } ], "description": "Workflow destination. Use existing step ids or thank-you screen ids from formasty_get_form." } }, "stepActions": { "type": "object", "properties": {}, "description": "Per-step workflow variable actions keyed by step id.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable action id. Reuse existing ids when patching current workflow rules." }, "variableId": { "type": "string", "description": "Workflow variable id to modify." }, "operation": { "type": "string", "enum": [ "set", "add", "subtract", "multiply", "divide", "clear", "append", "prepend" ], "description": "Workflow variable operation." }, "source": { "type": "object", "properties": { "sourceType": { "type": "string", "enum": [ "literal", "field", "hidden_field", "variable" ], "description": "Where the workflow variable action should read its value from." }, "sourceId": { "type": "string", "description": "Hidden field key or variable id depending on sourceType. For field sources, prefer fieldId; sourceId is accepted as a compatibility alias." }, "fieldId": { "type": "string", "description": "Field id when reading from a form field." }, "target": { "type": "object", "properties": { "subfieldKey": { "type": "string", "description": "Optional subfield key for structured values such as address parts." }, "rowKey": { "type": "string", "description": "Optional matrix row key when a workflow condition targets a matrix row value." } }, "description": "Optional workflow target selector for structured field values.", "additionalProperties": false }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Literal fallback value used when sourceType is literal." } }, "description": "Workflow variable action source. Reuse ids and targets from the current draft snapshot.", "additionalProperties": false } }, "required": [ "id", "variableId", "operation" ], "description": "Workflow variable mutation attached to a rule or step action.", "additionalProperties": false } } }, "layout": { "type": "object", "properties": { "nodes": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false } }, "viewport": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "zoom": { "type": "number" } }, "required": [ "x", "y", "zoom" ], "additionalProperties": false }, "panX": { "type": "number" }, "panY": { "type": "number" }, "zoom": { "type": "number" }, "autoArranged": { "type": "boolean" } }, "description": "Workflow canvas layout metadata. Preserve existing values when you are not intentionally changing the layout.", "additionalProperties": false } }, "required": [ "version", "enabled", "rules" ], "description": "Full workflow schema. Reuse ids from the current draft when editing existing rules, conditions, groups, variables, or outcomes.", "additionalProperties": false }, "quiz": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "match" ] }, "mode": { "type": "string", "enum": [ "match", "personality" ] }, "enabled": { "type": "boolean" }, "endings": { "type": "array", "items": { "type": "object", "properties": { "screenId": { "type": "string" } }, "required": [ "screenId" ], "additionalProperties": false } }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fieldId": { "type": "string" }, "optionId": { "type": "string" }, "optionValue": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "target": { "type": "object", "properties": { "subfieldKey": { "type": "string", "description": "Optional subfield key for structured values such as address parts." }, "rowKey": { "type": "string", "description": "Optional matrix row key when a workflow condition targets a matrix row value." } }, "description": "Optional workflow target selector for structured field values.", "additionalProperties": false }, "screenId": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "id", "fieldId", "screenId" ], "additionalProperties": false } } }, "required": [ "type", "enabled", "endings", "mappings" ], "description": "Optional recommendation/personality quiz configuration.", "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "score" ] }, "enabled": { "type": "boolean" }, "endings": { "type": "array", "items": { "type": "object", "properties": { "screenId": { "type": "string" }, "minScore": { "type": "number" }, "maxScore": { "type": "number" } }, "required": [ "screenId" ], "additionalProperties": false } }, "mappings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fieldId": { "type": "string" }, "optionId": { "type": "string" }, "optionValue": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "target": { "type": "object", "properties": { "subfieldKey": { "type": "string", "description": "Optional subfield key for structured values such as address parts." }, "rowKey": { "type": "string", "description": "Optional matrix row key when a workflow condition targets a matrix row value." } }, "description": "Optional workflow target selector for structured field values.", "additionalProperties": false }, "score": { "type": "number" } }, "required": [ "id", "fieldId", "score" ], "additionalProperties": false } }, "qualification": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tiers": { "type": "array", "minItems": 2, "maxItems": 6, "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Optional hex color in #RRGGBB format, matching the builder validation." }, "minScore": { "type": "number" } }, "required": [ "id", "label", "minScore" ], "additionalProperties": false } } }, "required": [ "enabled", "tiers" ], "description": "Optional Business-tier lead qualification tiers. Each tier classifies the computed score into a labeled lead tier when its minScore threshold is met. Requires Business or an active trial.", "additionalProperties": false } }, "required": [ "type", "enabled", "endings", "mappings" ], "description": "Optional score quiz configuration. Use ending minScore/maxScore ranges to resolve the result.", "additionalProperties": false } ], "description": "Optional quiz configuration. Use type=match for recommendation/personality quizzes or type=score for score ranges." }, "poll": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "resultsVisibility": { "type": "string", "enum": [ "after_vote", "hidden" ], "description": "Whether aggregate poll results are shown after voting or kept hidden." } }, "required": [ "enabled", "resultsVisibility" ], "description": "Optional poll configuration. Poll publishing is subject to the current workspace plan.", "additionalProperties": false } }, "required": [ "version", "steps", "settings", "theme", "workflow" ], "description": "Full draft schema contract. Use the exact structure returned by formasty_get_form().form.draftSchema when replacing the whole draft. New forms should keep a statement-only welcome screen before respondent fields.", "additionalProperties": false }, "WorkflowRule": { "type": "object", "additionalProperties": true, "description": "Builder-compatible workflow rule. Supports step routes, thank-you routes, and workflow variable actions.", "required": [ "id", "source" ], "properties": { "id": { "type": "string" }, "source": { "type": "object", "additionalProperties": true, "required": [ "stepId" ], "properties": { "stepId": { "type": "string" } } }, "conditions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "thenAction": { "type": "object", "additionalProperties": true }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" } } }, "QuizConfig": { "type": "object", "additionalProperties": true, "description": "Builder-compatible quiz config. Supports match/personality quizzes and score quizzes.", "required": [ "type", "enabled" ], "properties": { "type": { "type": "string", "enum": [ "match", "score" ] }, "mode": { "type": "string", "enum": [ "match", "personality" ] }, "enabled": { "type": "boolean" }, "endings": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "mappings": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "qualification": { "type": "object", "additionalProperties": true } } }, "PollConfig": { "type": "object", "additionalProperties": true, "description": "Builder-compatible poll config. Set enabled true and resultsVisibility to after_vote or hidden. Poll publishing is Pro-gated server-side.", "required": [ "enabled", "resultsVisibility" ], "properties": { "enabled": { "type": "boolean" }, "resultsVisibility": { "type": "string", "enum": [ "after_vote", "hidden" ] } } }, "ThankYouScreen": { "type": "object", "additionalProperties": true, "description": "Builder-compatible additional ending screen presentation payload.", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "message": { "type": "string" }, "buttonLabel": { "type": "string" }, "buttonUrl": { "type": "string" }, "mediaUrl": { "type": "string" }, "backgroundImageUrl": { "type": "string" } } }, "DraftMutationResponse": { "type": "object", "additionalProperties": false, "description": "Updated draft fragment with draft_revision and draft_updated_at.", "required": [ "draft_revision", "draft_updated_at" ], "properties": { "ok": { "type": "boolean" }, "step": { "type": "object", "additionalProperties": true }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/OrderedItem" } }, "field": { "type": "object", "additionalProperties": true }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/OrderedItem" } }, "logic": { "type": "object", "additionalProperties": true }, "rule": { "oneOf": [ { "$ref": "#/components/schemas/WorkflowRule" }, { "type": "null" } ] }, "quiz": { "oneOf": [ { "$ref": "#/components/schemas/QuizConfig" }, { "type": "null" } ] }, "screen": { "$ref": "#/components/schemas/ThankYouScreen" }, "theme": { "type": "object", "additionalProperties": true }, "asset": { "$ref": "#/components/schemas/GeneratedImageAsset" }, "attached": { "type": "boolean" }, "deleted_step_id": { "type": "string" }, "deleted_field_id": { "type": "string" }, "deleted_screen_id": { "type": "string" }, "draft_revision": { "type": "integer", "minimum": 0 }, "draft_updated_at": { "type": "integer" } } }, "OrderedItem": { "type": "object", "additionalProperties": false, "required": [ "id", "position" ], "properties": { "id": { "type": "string" }, "position": { "type": "integer", "minimum": 0 } } }, "GeneratedImageAsset": { "type": "object", "additionalProperties": true, "required": [ "id", "url" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" } } }, "DraftValidationIssue": { "type": "object", "additionalProperties": false, "required": [ "kind", "message" ], "properties": { "kind": { "type": "string", "enum": [ "schema", "workflow", "settings", "plan", "booking" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" }, "repairActions": { "type": "array", "items": { "type": "string" } } } }, "DraftValidationSummary": { "type": "object", "additionalProperties": true, "required": [ "publishReady", "summary", "validatedDraftRevision", "validatedDraftUpdatedAt", "inactiveDueToPlan", "plan", "issues" ], "properties": { "publishReady": { "type": "boolean" }, "summary": { "type": "string" }, "validatedDraftRevision": { "type": "integer" }, "validatedDraftUpdatedAt": { "type": "integer" }, "inactiveDueToPlan": { "type": "boolean" }, "plan": { "type": "string", "enum": [ "free", "pro" ] }, "lockedFeatureKeys": { "type": "array", "items": { "type": "string" } }, "inactiveFeatureKeys": { "type": "array", "items": { "type": "string" } }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/DraftValidationIssue" } } } }, "DraftValidationResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "validation" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "form_id", "draft_revision", "draft_updated_at" ], "properties": { "form_id": { "type": "string" }, "draft_revision": { "type": "integer" }, "draft_updated_at": { "type": "integer" } } }, "validation": { "$ref": "#/components/schemas/DraftValidationSummary" } } }, "DraftValidationFailureResponse": { "type": "object", "additionalProperties": false, "required": [ "error", "publishReady", "validation", "issues" ], "properties": { "error": { "type": "string" }, "publishReady": { "type": "boolean", "const": false }, "validation": { "$ref": "#/components/schemas/DraftValidationSummary" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/DraftValidationIssue" } } } }, "FormResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "draft_schema", "settings", "published_schema" ], "properties": { "data": { "$ref": "#/components/schemas/FormSummary" }, "draft_schema": { "$ref": "#/components/schemas/DraftSchema" }, "settings": { "type": "object", "additionalProperties": true, "description": "Complete operational settings for the current draft. Send this snapshot with draft_schema when changing both." }, "published_schema": { "oneOf": [ { "$ref": "#/components/schemas/DraftSchema" }, { "type": "null" } ] }, "draft_revision": { "type": "integer", "minimum": 0 }, "public_url": { "type": "string" } } }, "ApiKeyProfileResponse": { "type": "object", "additionalProperties": false, "required": [ "owner", "preferred_workspace", "credential" ], "properties": { "owner": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "username" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "username": { "type": "string" } } }, "preferred_workspace": { "type": "string" }, "credential": { "type": "object", "additionalProperties": true, "required": [ "type", "workspace_id", "workspace_name", "scopes" ], "properties": { "type": { "type": "string", "enum": [ "api_key", "oauth" ] }, "id": { "type": "string" }, "workspace_id": { "type": "string" }, "workspace_name": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": [ "integer", "null" ] }, "revoked_at": { "type": [ "integer", "null" ] }, "client_id": { "type": "string" }, "connection_id": { "type": "string" } } } } }, "CapabilitiesResponse": { "type": "object", "additionalProperties": false, "required": [ "contractVersion", "defaultWorkProfile", "supportedScopes", "authentication", "safeguards", "unsupported", "endpoints", "credential", "workspace", "workspaceAccess", "effectiveOperations", "operationAvailability" ], "properties": { "contractVersion": { "type": "string" }, "defaultWorkProfile": { "type": "object", "additionalProperties": true }, "supportedScopes": { "type": "array", "items": { "type": "string" } }, "authentication": { "type": "object", "additionalProperties": true }, "safeguards": { "type": "object", "additionalProperties": true }, "unsupported": { "type": "array", "items": { "type": "string" } }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } }, "credential": { "type": "object", "additionalProperties": false, "required": [ "type", "scopes" ], "properties": { "type": { "type": "string", "enum": [ "api_key", "oauth" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "workspace": { "type": "object", "additionalProperties": true }, "workspaceAccess": { "type": "object", "additionalProperties": true, "description": "OAuth workspace grants and the workspace selected for this evaluation. API keys expose selected mode with one bound workspace." }, "effectiveOperations": { "type": "array", "description": "Operations immediately available in the evaluated workspace without a target-form check.", "items": { "type": "string" } }, "operationAvailability": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "operation", "effective_status", "requires_resource_context", "blockers" ], "properties": { "operation": { "type": "string" }, "effective_status": { "type": "string", "enum": [ "available", "conditional", "blocked" ] }, "requires_resource_context": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "FormListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSummary" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque continuation token. Pass it as cursor on the next request; null means the collection is exhausted." } } }, "DeleteResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "id" ], "properties": { "ok": { "type": "boolean", "const": true }, "id": { "type": "string" } } }, "SubmissionRecord": { "type": "object", "additionalProperties": false, "required": [ "event", "eventId", "form", "submission", "answers", "fields", "meta", "answersByFieldId" ], "properties": { "event": { "type": "string" }, "eventId": { "type": "string" }, "form": { "type": "object", "additionalProperties": false, "required": [ "id", "publicId", "name", "workspaceId", "version" ], "properties": { "id": { "type": "string" }, "publicId": { "type": "string" }, "name": { "type": "string" }, "workspaceId": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ] }, "version": { "type": "integer" } } }, "submission": { "type": "object", "additionalProperties": false, "required": [ "id", "createdAt" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" } } }, "answers": { "type": "object", "additionalProperties": true }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "label", "value" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": {} } } }, "meta": { "type": "object", "additionalProperties": true }, "answersByFieldId": { "type": "object", "additionalProperties": true } } }, "SubmissionListResponse": { "type": "object", "additionalProperties": false, "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubmissionRecord" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque continuation token. Pass it as cursor with the same form and after filter; null means the collection is exhausted." } } }, "SubmissionDetailResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubmissionRecord" } } }, "SubmissionCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "submission", "thank_you" ], "properties": { "submission": { "$ref": "#/components/schemas/SubmissionRecord" }, "thank_you": { "type": "object", "additionalProperties": true }, "redirect_to": { "type": "string" } } }, "GeneratedImageResponse": { "type": "object", "additionalProperties": false, "required": [ "asset", "attached" ], "properties": { "asset": { "$ref": "#/components/schemas/GeneratedImageAsset" }, "attached": { "type": "boolean" }, "draft_revision": { "type": "integer", "minimum": 0 }, "draft_updated_at": { "type": "integer" } } }, "ErrorResponse": { "type": "object", "additionalProperties": true, "required": [ "error", "code", "message", "recovery", "retryable", "status" ], "properties": { "error": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ], "description": "Backward-compatible legacy error value. New integrations should branch on the top-level code and display message." }, "code": { "type": "string", "enum": [ "invalid_request", "authentication_required", "permission_denied", "resource_not_found", "conflict", "payload_too_large", "validation_failed", "rate_limited", "internal_error", "service_unavailable" ], "description": "Stable machine-readable category suitable for programmatic recovery." }, "message": { "type": "string", "description": "Human-readable explanation of what failed." }, "recovery": { "type": "string", "description": "Concrete next action an agent or API client can take." }, "retryable": { "type": "boolean", "description": "Whether retrying later or after the described recovery can succeed." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status mirrored in the JSON body." }, "docs_url": { "type": "string", "format": "uri", "description": "Canonical Formasty API error documentation." } } } } }, "paths": { "/capabilities": { "get": { "operationId": "getCapabilities", "x-formasty-required-scope": "none", "summary": "Inspect effective API capabilities", "description": "Returns credential scopes and workspace-role permissions as separate authorization layers, plus operations that are available, conditional on a target resource, or blocked in the evaluated workspace.", "parameters": [ { "in": "query", "name": "workspaceId", "schema": { "type": "string" }, "description": "OAuth workspace to evaluate. API keys remain bound to their configured workspace. workspace_id is also accepted." }, { "in": "header", "name": "X-Formasty-Workspace-Id", "schema": { "type": "string" }, "description": "Alternative workspace selector. It must match any workspaceId query value." } ], "responses": { "200": { "description": "Effective Formasty API capabilities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/me": { "get": { "operationId": "getApiKeyProfile", "x-formasty-required-scope": "none", "summary": "Validate the authenticated credential", "description": "Returns the OAuth or API-key owner, preferred workspace, credential type, and granted scopes.", "responses": { "200": { "description": "Authenticated credential profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyProfileResponse" } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms": { "get": { "operationId": "listForms", "x-formasty-required-scope": "forms:read", "summary": "List accessible forms", "description": "Lists forms in one workspace granted to the credential. OAuth connections can select any authorized workspace; API keys remain bound to one workspace.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size. Defaults to 20." }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque next_cursor value returned by the previous page." }, { "in": "query", "name": "workspaceId", "schema": { "type": "string" }, "description": "Authorized OAuth workspace to list. API keys can only use their bound workspace. workspace_id is also accepted." }, { "in": "header", "name": "X-Formasty-Workspace-Id", "schema": { "type": "string" }, "description": "Alternative workspace selector. It must match any workspaceId query value." } ], "responses": { "200": { "description": "Forms list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormListResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "post": { "operationId": "createForm", "x-formasty-required-scope": "forms:create", "summary": "Create a form draft", "description": "Creates a draft form in an authorized workspace. OAuth connections can select a granted workspace; API keys remain bound to one workspace. Provide a builder-compatible draftSchema for full control.", "x-openai-isConsequential": true, "parameters": [ { "in": "header", "name": "X-Formasty-Workspace-Id", "schema": { "type": "string" }, "description": "Alternative target workspace selector. It must match workspaceId in the request body when both are provided." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "workspaceId": { "type": "string" }, "title": { "type": "string" }, "draftSchema": { "$ref": "#/components/schemas/DraftSchema" } } } } } }, "responses": { "201": { "description": "Created form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}": { "get": { "operationId": "getForm", "x-formasty-required-scope": "forms:read", "summary": "Get one form", "description": "Returns form metadata, current draft schema, and published schema.", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Form payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "patch": { "operationId": "updateForm", "x-formasty-required-scope": "forms:update", "summary": "Update form title or draft", "description": "Replaces the full draft when draftSchema is supplied. Preserve unknown fields.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_revision" ], "additionalProperties": false, "properties": { "title": { "type": "string" }, "draftSchema": { "$ref": "#/components/schemas/DraftSchema" }, "settings": { "type": "object", "additionalProperties": true, "description": "Optional complete form settings snapshot when draftSchema is supplied." }, "draft_revision": { "type": "integer", "minimum": 0 }, "mutation_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Client-generated idempotency key for an exact retry of this update." } } } } } }, "responses": { "200": { "description": "Updated form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "delete": { "operationId": "deleteForm", "x-formasty-required-scope": "forms:delete", "summary": "Delete a form", "description": "Deletes a form the authenticated credential owner can manage.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/draft": { "put": { "operationId": "saveFormDraft", "x-formasty-required-scope": "forms:update", "summary": "Save the complete form draft", "description": "Atomically saves the builder-compatible schema and, when supplied, the complete form settings snapshot. Reuse the same mutation_id only when retrying the exact same request body.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draftSchema", "draft_revision" ], "additionalProperties": false, "properties": { "draftSchema": { "$ref": "#/components/schemas/DraftSchema" }, "settings": { "type": "object", "additionalProperties": true, "description": "Optional complete form settings snapshot. When supplied, schema and settings commit as one draft revision." }, "draft_revision": { "type": "integer", "minimum": 0 }, "mutation_id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Client-generated idempotency key for this logical save. Reuse it only for byte-for-byte equivalent retries." } } } } } }, "responses": { "200": { "description": "Saved draft, or the stored result of an exact mutation_id retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "409": { "description": "The draft revision is stale, or mutation_id was reused with a different payload." }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/steps": { "post": { "operationId": "createFormStep", "x-formasty-required-scope": "forms:steps:write", "summary": "Create a draft step", "description": "Appends a step or inserts it at the requested position.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_revision" ], "additionalProperties": true, "properties": { "title": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "position": { "type": "integer" }, "index": { "type": "integer" }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created step and updated draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/steps/reorder": { "post": { "operationId": "reorderFormSteps", "x-formasty-required-scope": "forms:steps:write", "summary": "Reorder draft steps", "description": "Replaces the step order with every current step ID in the desired order.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "step_ids", "draft_revision" ], "properties": { "step_ids": { "type": "array", "items": { "type": "string" } }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Reordered steps and updated draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/steps/{step_id}": { "patch": { "operationId": "updateFormStep", "x-formasty-required-scope": "forms:steps:write", "summary": "Update a draft step", "description": "Updates mutable step properties without replacing its fields or ID.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/StepId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_revision" ], "additionalProperties": true, "properties": { "title": { "type": "string" }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated step and draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "delete": { "operationId": "deleteFormStep", "x-formasty-required-scope": "forms:steps:write", "summary": "Delete a draft step", "description": "Deletes the step and cleans up workflow references. A form must retain at least one step.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/StepId" }, { "$ref": "#/components/parameters/DraftRevisionQuery" } ], "responses": { "200": { "description": "Deleted step and updated draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/steps/{step_id}/fields": { "post": { "operationId": "createFormField", "x-formasty-required-scope": "forms:fields:write", "summary": "Create a draft field", "description": "Adds a builder-compatible field to a draft step.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/StepId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "type", "label", "draft_revision" ], "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "placeholder": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "position": { "type": "integer" }, "index": { "type": "integer" }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created field and updated draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/fields/{field_id}": { "patch": { "operationId": "updateFormField", "x-formasty-required-scope": "forms:fields:write", "summary": "Update a draft field", "description": "Updates mutable builder-compatible field properties while preserving its ID.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/FieldId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_revision" ], "additionalProperties": true, "properties": { "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "required": { "type": "boolean" }, "placeholder": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated field and draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "delete": { "operationId": "deleteFormField", "x-formasty-required-scope": "forms:fields:write", "summary": "Delete a draft field", "description": "Deletes the field and cleans up workflow references.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/FieldId" }, { "$ref": "#/components/parameters/DraftRevisionQuery" } ], "responses": { "200": { "description": "Deleted field and updated draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/steps/{step_id}/fields/reorder": { "post": { "operationId": "reorderFormFields", "x-formasty-required-scope": "forms:fields:write", "summary": "Reorder fields in a draft step", "description": "Replaces the field order with every current field ID in the desired order.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/StepId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "field_ids", "draft_revision" ], "properties": { "field_ids": { "type": "array", "items": { "type": "string" } }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Reordered fields and updated draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/steps/{step_id}/logic": { "put": { "operationId": "updateFormStepLogic", "x-formasty-required-scope": "forms:logic:write", "summary": "Replace draft step logic", "description": "Replaces workflow rules and the fallback target for one draft step.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/StepId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "rules", "draft_revision" ], "properties": { "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "fallbackTarget": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated step logic and draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/design": { "patch": { "operationId": "updateFormDesign", "x-formasty-required-scope": "forms:design:write", "summary": "Update draft design", "description": "Merges a partial builder-compatible theme into the current draft theme.", "x-openai-isConsequential": true, "parameters": [ { "$ref": "#/components/parameters/FormId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "theme", "draft_revision" ], "properties": { "theme": { "type": "object", "additionalProperties": true }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated theme and draft revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/validate": { "post": { "operationId": "validateFormDraft", "x-formasty-required-scope": "forms:read", "summary": "Validate a form draft", "description": "Runs the same schema, workflow, settings, booking, and plan-gate preflight used by Formasty agents without changing or publishing the form.", "x-openai-isConsequential": false, "parameters": [ { "$ref": "#/components/parameters/FormId" } ], "responses": { "200": { "description": "Current draft revision and publish-readiness report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftValidationResponse" } } } }, "401": { "description": "Missing or invalid OAuth token or API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Missing forms:read scope or workspace permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Form not found in the authenticated credential's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/publish": { "post": { "operationId": "publishForm", "x-formasty-required-scope": "forms:publish", "summary": "Publish a form", "description": "Validates and publishes the exact saved draft_revision supplied by the caller.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "draft_revision" ], "properties": { "draft_revision": { "type": "integer", "minimum": 0, "description": "Revision of the exact saved draft to publish." } } } } } }, "responses": { "200": { "description": "Published form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" } } } }, "400": { "description": "Missing draft_revision, invalid request body, missing draft, or an inline draft schema was supplied instead of using the draft endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid OAuth token or API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Missing forms:publish scope or workspace publish permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Form not found in the authenticated credential's workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Stale draft revision, slug conflict, plan restriction, or publish-readiness preflight failure.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DraftValidationFailureResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/workflow/rules": { "post": { "operationId": "upsertWorkflowRule", "x-formasty-required-scope": "forms:logic:write", "summary": "Create or replace one workflow rule", "description": "Adds or replaces a single draft workflow route, including thank-you outcomes and workflow variable actions.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "rule", "draft_revision" ], "properties": { "rule": { "$ref": "#/components/schemas/WorkflowRule" }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated workflow rule and step logic.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/quiz": { "patch": { "operationId": "configureQuiz", "x-formasty-required-scope": "forms:logic:write", "summary": "Configure quiz result rules", "description": "Sets or clears the draft quiz config. Use null to clear. Score quizzes and extra ending screens are Pro-gated server-side.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quiz", "draft_revision" ], "properties": { "quiz": { "oneOf": [ { "$ref": "#/components/schemas/QuizConfig" }, { "type": "null" } ] }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated quiz config.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/thank-you-screens": { "post": { "operationId": "createThankYouScreen", "x-formasty-required-scope": "forms:update", "summary": "Create an additional ending screen", "description": "Creates one additional thank-you/ending screen in the draft. Extra ending screens are Pro-gated server-side.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_revision" ], "additionalProperties": false, "properties": { "screenId": { "type": "string" }, "screen": { "$ref": "#/components/schemas/ThankYouScreen" }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created ending screen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/thank-you-screens/{screen_id}": { "patch": { "operationId": "updateThankYouScreen", "x-formasty-required-scope": "forms:update", "summary": "Update an additional ending screen", "description": "Patches one additional draft ending screen.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "screen_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_revision" ], "additionalProperties": false, "properties": { "screen": { "$ref": "#/components/schemas/ThankYouScreen" }, "draft_revision": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated ending screen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "delete": { "operationId": "deleteThankYouScreen", "x-formasty-required-scope": "forms:update", "summary": "Delete an additional ending screen", "description": "Deletes one additional ending screen and safely remaps workflow/quiz references.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "screen_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "draft_revision", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted ending screen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftMutationResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/media-assets/generated": { "post": { "operationId": "uploadGeneratedImageAsset", "x-formasty-required-scope": "forms:update", "summary": "Ingest an AI-generated image asset", "description": "Stores an HTTPS or data URL PNG/JPG/GIF/WebP in Formasty storage and optionally attaches it to a step cover, ending media/background/logo, or choice option image.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "sourceUrl": { "type": "string", "description": "HTTPS image URL. Mutually exclusive with dataUrl." }, "dataUrl": { "type": "string", "description": "PNG/JPG/GIF/WebP data URL. Mutually exclusive with sourceUrl." }, "fileName": { "type": "string" }, "altText": { "type": "string" }, "target": { "type": "object", "additionalProperties": true, "description": "Optional target such as step_cover, ending_media, ending_background, ending_logo, or field_option." }, "draft_revision": { "type": "integer", "description": "Required when target is provided." } } } } } }, "responses": { "201": { "description": "Stored generated image asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratedImageResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/submissions": { "get": { "operationId": "listFormSubmissions", "x-formasty-required-scope": "submissions:read", "summary": "List form submissions", "description": "Lists completed submissions for one published form.", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 }, "description": "Opaque next_cursor value returned by the previous page." }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "date-time" }, "description": "Optional ISO timestamp lower bound." } ], "responses": { "200": { "description": "Submission records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionListResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } }, "post": { "operationId": "createFormSubmission", "x-formasty-required-scope": "submissions:create", "summary": "Create a submission", "description": "Creates a submission against the current published form snapshot.", "x-openai-isConsequential": true, "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "values": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Created submission and thank-you payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionCreateResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } }, "/forms/{form_id}/submissions/{submission_id}": { "get": { "operationId": "getFormSubmission", "x-formasty-required-scope": "submissions:read", "summary": "Get one submission", "description": "Returns one submission record for a form.", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "submission_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Submission record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionDetailResponse" } } } }, "default": { "$ref": "#/components/responses/AgentError" } } } } } }