FOformbricks
V3 Surveys

Create a survey draft payload with AI

Changed on

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. Both type: link and type: app are supported; for app, the payload includes a default distribution (display once, no triggers, no targeting) that you finish configuring in the editor or via the create request.

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.

post/api/v3/surveys/generate

Request

  • Base URL
    https://app.formbricks.com
  • URL
    https://app.formbricks.com/api/v3/surveys/generate
  • Auth
    • API key in cookie next-auth.session-token
    • or API key in header x-api-key
    • or HTTP bearer

Request body

workspaceIdstring cuid2 required

Workspace where the AI-created survey draft would be created. Requires read/write access.

promptstring 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' | 'app'

Survey type to generate. The AI generates the survey content (blocks/questions) for both types; for app it additionally seeds a default distribution (display once, no triggers, no targeting) that you finish configuring before publishing.

language'ar-EG' | 'bg-BG' | 'cs-CZ' | 'da-DK' | 'de-DE' | 'el-GR' | 'en-US' | 'es-ES' | 'et-EE' | 'fi-FI' | 'fr-FR' | 'hi-IN' | 'hr-HR' | 'hu-HU' | 'id-ID' | 'it-CH' | 'it-IT' | 'ja-JP' | 'km-KH' | 'ko-KR' | 'lt-LT' | 'lv-LV' | 'ms-MY' | 'nb-NO' | 'ne-NP' | 'nl-BE' | 'nl-NL' | 'no-NO' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sl-SI' | 'sv-SE' | 'tr-TR' | 'uk-UA' | 'ur-PK' | 'uz-UZ' | 'vi-VN' | 'zh-Hans-CN' | 'zh-Hant-TW'

Survey language code AI survey creation can write a draft in: every language the survey runtime ships button and validation strings for, plus the dashboard locales.

surveyLanguage'ar-EG' | 'bg-BG' | 'cs-CZ' | 'da-DK' | 'de-DE' | 'el-GR' | 'en-US' | 'es-ES' | 'et-EE' | 'fi-FI' | 'fr-FR' | 'hi-IN' | 'hr-HR' | 'hu-HU' | 'id-ID' | 'it-CH' | 'it-IT' | 'ja-JP' | 'km-KH' | 'ko-KR' | 'lt-LT' | 'lv-LV' | 'ms-MY' | 'nb-NO' | 'ne-NP' | 'nl-BE' | 'nl-NL' | 'no-NO' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sl-SI' | 'sv-SE' | 'tr-TR' | 'uk-UA' | 'ur-PK' | 'uz-UZ' | 'vi-VN' | 'zh-Hans-CN' | 'zh-Hant-TW'

Survey language code AI survey creation can write a draft in: every language the survey runtime ships button and validation strings for, plus the dashboard locales.

Example request

{
  "language": "en-US",
  "surveyLanguage": "en-US"
}

Response

Survey create payload generated successfully. The survey has not been created yet.

Changes

  • 25335c959a13Revision changes
    • warning

      added the new row enum value to the /////////////// response property for the response status

    • warning

      added the new row enum value to the /////////////// response property for the response status

  • 82c0afd2df39Revision changes
    • breaking

      added subschema #5: SurveyInteractionFilter to the ///////////////// response property oneOf list for the response status