v16

latestOpenAPI 3.1.1raw.githubusercontent.com2026-08-0124102197.4 KB

V3 Surveys

Create a survey draft payload with AI

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 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.

Supported app locale code that AI survey creation can return.

Example request

{
  "language": "en-US"
}

Response

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