--- title: "Create a survey draft payload with AI" method: POST path: "/api/v3/surveys/generate" tags: ["V3 Surveys"] --- # Create a survey draft payload with AI `POST /api/v3/surveys/generate` Creates a strict v3 `POST /api/v3/surveys` create payload from a creator prompt and returns validation metadata. This endpoint is single-purpose: it does **not** persist the survey. Clients should validate the returned payload with `/api/v3/surveys/validate` or use the embedded validation metadata, then create the draft through `POST /api/v3/surveys`. The generated payload always sets `status: draft`. The initial contract supports only `type: link`; app and website survey creation must stay disabled until the v3 create endpoint accepts those types. Prompt privacy: prompt text is sent to the configured AI provider to create the payload, but this endpoint does not store prompts and server logs should use request ids and failure categories instead of raw prompt content. ## Request body - GenerateSurveyRequest — AI survey creation request. `prompt` is used only to create a draft payload; it is not persisted by this endpoint. The generated payload is validated and returned to the caller for a separate create request. - `workspaceId` string, cuid2, required — Workspace where the AI-created survey draft would be created. Requires read/write access. - `prompt` string, required — Natural-language survey goal and audience. Prompts with fewer than 24 characters or fewer than four whitespace-separated words return prompt feedback before any AI provider call. - `type` 'link' — Link Survey is the only AI-created type until the v3 create endpoint supports additional types. - `language` 'de-DE' | 'en-US' | 'es-ES' | 'fr-FR' | 'hu-HU' | 'ja-JP' | 'nl-NL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sv-SE' | 'tr-TR' | 'zh-Hans-CN' | 'zh-Hant-TW' — Supported app locale code that AI survey creation can return. ## Response `200` Survey create payload generated successfully. The survey has not been created yet. - object - `data` GenerateSurveyResult, required - `language` 'de-DE' | 'en-US' | 'es-ES' | 'fr-FR' | 'hu-HU' | 'ja-JP' | 'nl-NL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sv-SE' | 'tr-TR' | 'zh-Hans-CN' | 'zh-Hant-TW', required — Supported app locale code that AI survey creation can return. - `payload` CreateSurveyRequest, required — Strict v3 survey creation document. This endpoint accepts survey structure only: name, metadata, languages, welcome card, blocks/elements/logic, endings, hidden fields, and variables. It rejects legacy `questions` and out-of-scope settings such as styling, targeting, segments, follow-ups, recaptcha, single-use/email verification, slug, custom scripts, analytics fields, timestamps, and `createdBy`. Translatable fields use real locale-code maps. The map must include the canonical `defaultLanguage` key, such as `en-US`, so the server can persist the internal default translation. Locale keys must be canonical BCP 47 codes such as `de-DE`, `pt-PT`, or `zh-Hans-CN`. Non-default locale keys must be declared in `languages`; undeclared locale keys in metadata, welcome cards, blocks, or endings are rejected with `unsupported_locale`. `blocks[].id` and `variables[].id` may be omitted on create and will be generated by the server. Provide explicit cuid2 ids when other fields in the same request reference them. For normal sequential flow, omit `logicFallback`. It is only valid together with a non-empty `logic` array on the same block. - `workspaceId` string, cuid2, required — Workspace where the survey will be created. Requires read/write access. - `name` string, required - `type` 'link' | 'app' — Optional compatibility field. `link` and `app` survey types are accepted here; app/in-app survey distribution settings remain outside this structure-focused create endpoint. - `status` 'draft' | 'inProgress' | 'paused' | 'completed' - `metadata` SurveyMetadata — Arbitrary JSON survey context for customer- or operation-specific metadata. v3 preserves arbitrary metadata values as-is. If present, `title` and `description` are treated as translatable text maps and returned with real locale-code keys. - `title` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `description` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `defaultLanguage` string — Canonical locale code accepted by v3 survey APIs, for example `en-US`, `de-DE`, or `zh-Hans-CN`. - `languages` CreateSurveyLanguage[] — Optional survey language configuration. Every non-default locale used by translatable maps must be declared here; omitted languages are not inferred from map keys. - `code` string, required — Canonical locale code accepted by v3 survey APIs, for example `en-US`, `de-DE`, or `zh-Hans-CN`. - `default` boolean — Optional marker for readability; only the `defaultLanguage` entry may set this to true. - `enabled` boolean — Whether this language is enabled for respondent-facing delivery. - `welcomeCard` SurveyWelcomeCard — Optional card shown before the first survey block. - `enabled` boolean, required - `headline` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `fileUrl` string - `videoUrl` string - `timeToFinish` boolean - `showResponseCount` boolean - `blocks` CreateSurveyBlock[], required - `id` string, cuid2 — Optional stable block id. Generated when omitted. - `name` string, required - `elements` SurveyElement[], required - union — Survey element/question inside a block. Element ids are stable public identifiers used by logic, recall strings, response data, quotas, integrations, and analysis. `type` selects the allowed shape; unsupported fields are rejected instead of ignored. - SurveyOpenTextElement - … - SurveyConsentElement - … - SurveyMultipleChoiceSingleElement - … - SurveyMultipleChoiceMultiElement - … - SurveyNpsElement - … - SurveyCtaElement — If `buttonExternal` is true, `buttonUrl` and `ctaButtonLabel` are required. - … - SurveyRatingElement - … - SurveyPictureSelectionElement - … - SurveyDateElement - … - SurveyFileUploadElement - … - SurveyCalElement - … - SurveyMatrixElement - … - SurveyAddressElement - … - SurveyRankingElement - … - SurveyContactInfoElement - … - SurveyCsatElement - … - SurveyCesElement - … - `logic` SurveyBlockLogic[] - `id` string, cuid2, required - `conditions` SurveyConditionGroup, required - `id` string, cuid2, required - `connector` 'and' | 'or', required - `conditions` union[], required - … - `actions` SurveyLogicAction[], required - union — Logic action. Keep referenced ids stable: `calculate.variableId` points to a variable id, `requireAnswer.target` points to an element id, and `jumpToBlock.target` points to a block id or ending id. - … - `logicFallback` string, cuid2 — Block or ending id used when no logic condition matches. Only valid when this same block has at least one `logic` rule; omit it for normal sequential flow. - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `backButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `endings` SurveyEnding[] - union — Ending reached after the last block or a jump action. `type` selects the allowed shape; unsupported fields are rejected instead of ignored. - SurveyEndScreenEnding — Visual end screen displayed after survey completion. - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'endScreen', required - `headline` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `buttonLink` string - `imageUrl` string - `videoUrl` string - SurveyRedirectEnding — Redirects the respondent to a URL after survey completion. External redirects require the organization's external URL permission; otherwise write endpoints return `403 Forbidden`. - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'redirectToUrl', required - `url` string, uri, required — External redirect URL. Requires the organization's external URL permission. - `label` string — Optional internal label for redirect endings. - `hiddenFields` SurveyHiddenFields — Hidden fields, sometimes called embedded data in other survey products. Field ids are stable public identifiers and may be referenced by logic, recall, quotas, integrations, and response data. Use only letters, numbers, underscores, and hyphens; avoid spaces and reserved ids. - `enabled` boolean, required - `fieldIds` string[] - `variables` CreateSurveyVariable[] - union — Survey variable accepted by `POST /api/v3/surveys`. `id` may be omitted and will be generated by the server. Provide an explicit cuid2 id when logic in the same request needs to reference this variable. - CreateSurveyNumberVariable - `id` string, cuid2 — Optional stable variable id. Generated when omitted. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'number', required - `value` number, required — Default numeric value. - CreateSurveyTextVariable - `id` string, cuid2 — Optional stable variable id. Generated when omitted. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'text', required - `value` string, required — Default text value. - `validation` GeneratedSurveyValidationResult, required - `valid` boolean, required — Whether the generated create payload passed the same v3 create preparation pipeline. - `invalid_params` InvalidParam[], required — Repairable validation errors. Successful generate responses return an empty array. - `name` string, required — Dot-path to the invalid request field. - `reason` string, required — Human-readable repair guidance. - `code` 'dangling_reference' | 'duplicate_identifier' | 'duplicate_locale' | 'forbidden_identifier' | 'immutable_identifier' | 'invalid_locale' | 'invalid_reference' | 'missing_required_field' | 'missing_translation' | 'unsupported_field' | 'unsupported_locale' — Machine-readable validation category, when available. - `identifier` string — Identifier involved in the validation failure, when available. For language errors, this can be the normalized language code. - `referenceType` 'block' | 'element' | 'ending' | 'hiddenField' | 'language' | 'variable' | 'variableName' | 'recall' — Identifier namespace involved in the validation failure. - `missingId` string — Referenced id that does not exist in the submitted survey document. - `firstUsedAt` string — Dot-path where a duplicate identifier was first used. - `conflictsWith` string — Dot-path to the existing identifier that conflicts with this field. - `languages` GeneratedSurveyValidationLanguage[], required — Languages that the generated create payload would connect or create. - `code` 'de-DE' | 'en-US' | 'es-ES' | 'fr-FR' | 'hu-HU' | 'ja-JP' | 'nl-NL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sv-SE' | 'tr-TR' | 'zh-Hans-CN' | 'zh-Hant-TW', required — Supported app locale code that AI survey creation can return. - `default` boolean, required - `enabled` boolean, required ## Other responses - `400` — Malformed body or a prompt that is too short or underspecified - `401` — Not authenticated (no valid session or API key) - `403` — Forbidden — no write access, workspace does not exist, AI is not in plan, or AI smart tools are disabled - `422` — AI generated an invalid payload after schema and v3 create validation - `429` — Rate limit exceeded - `500` — Internal Server Error - `502` — The configured AI provider failed or could not produce a valid draft - `503` — AI is not configured on this Formbricks instance ## Changes - **2026-06-19** `1e4aab51b414` — 2 info - added `subschema #2, subschema #3` to the `data/payload/allOf[#/components/schemas/CreateSurveyRequest]/blocks/items/elements/items/oneOf[#/components/schemas/SurveyCtaElement]/` response property `allOf` list for the response status `200` - removed `subschema #2` from the `data/payload/allOf[#/components/schemas/CreateSurveyRequest]/blocks/items/elements/items/oneOf[#/components/schemas/SurveyCtaElement]/` response property `allOf` list for the response status `200` - **2026-06-10** `4b05a011f15c` — 1 warning - added the new `app` enum value to the `data/payload/allOf[#/components/schemas/CreateSurveyRequest]/type` response property for the response status `200` - **2026-06-05** `90798c12f7ae` — 1 info - endpoint added - **2026-03-20** `9fa9931e1a70` — 1 breaking - api path removed without deprecation [Change history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/surveys/generate/post.md) --- [API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) · [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/formbricks/formbricks-api-v3/revisions/1e4aab51b414/schema)