Survey JSON model

A survey has a mutable draft and immutable numbered published versions. The draft contains a definition graph and an introduction page. Read the whole draft with GET /api/v1/surveys/{surveyId} before editing it.

Definition graph

definition.questions maps stable question IDs to question objects. Supported types are single choice, multiple choice, yes/no, short text, long text, number, and rating. Each question has text, required, and type-specific options or validation. Keep question and option IDs stable when changing labels so results remain comparable across versions.

definition.flow.start is the initial node. definition.flow.transitions contains id, from, to, and either default: true or a condition. Conditions compare a question answer against an option ID or value. Targets must exist; the server rejects cycles and unreachable questions. complete, screened_out, and named entries in completion.screen_outs are terminal destinations.

Page and publication

The page describes the organizer, purpose, and data use. Purpose and data-use copy are required for publication. Optional terms, privacy text, images, and sections appear on the public introduction. Images are small PNG, JPEG, or WebP data URLs stored in the versioned page JSON.

Move from draft to publication in three steps:

1. Save the draft. This validates graph structure and increments draftRevision. Missing publication copy is allowed at this stage.
2. Validate: POST .../validate checks whether the saved draft can publish. Resolve any errors before continuing.
3. Publish: POST .../publish repeats validation, stores an immutable version, and returns the public URL.

Existing respondent sessions stay on their version after another is published.

See the survey creation guide for the request sequence and the interactive API reference for field schemas.