Skip to content

Versions API

Endpoints that deal with survey versions.

Creating a new version is done through Save and Create a New Version in the Surveys API. This page covers reading versions, rolling back, and duplicating from a version.

See API Definition for authentication, response format, and error handling.

Method

HTTP Methods

Method URI Overview
GET /api/surveys/{surveyId}/versions List versions
POST /api/surveys/{surveyId}/versions/{versionNo}/rollback Roll back from a version
POST /api/surveys/{surveyId}/versions/{versionNo}/duplicate Duplicate from a version

Resource Definition

Version Schema

Field Type Notes
id string Version UUID
versionNo number Version number, unique within the survey
createdAt string Creation timestamp (ISO 8601)
createdBy string User ID of the author
status enum Status at the time the version was created
snapshotSections Section[] The version's sections and questions
sourceVersionId string ID of the version this one was copied from
rollbackFromVersionId string ID of the version restored (rollback-created versions only)

Authentication

User authentication via the x-user-email / x-user-name headers is required.

Operation Required permission
Listing versions, duplicating from a version view
Rolling back edit

Missing permission returns 404 Not Found.

List Versions

Overview

Returns the survey's version history, including each version's snapshot.

URI

GET /api/surveys/{surveyId}/versions
Parameter Type Required Notes
surveyId string โ—ฏ Survey UUID

Response (200 OK)

{
  "ok": true,
  "data": [
    {
      "id": "โ€ฆ",
      "versionNo": 1,
      "createdAt": "2026-08-01T00:00:00.000Z",
      "createdBy": "โ€ฆ",
      "status": "ไธ‹ๆ›ธใ",
      "snapshotSections": []
    },
    {
      "id": "โ€ฆ",
      "versionNo": 2,
      "createdAt": "2026-08-05T00:00:00.000Z",
      "createdBy": "โ€ฆ",
      "status": "ไธ‹ๆ›ธใ",
      "snapshotSections": [],
      "sourceVersionId": "โ€ฆ"
    }
  ]
}

Error Handling

Description Status code Status name
Survey does not exist, or view permission is missing 404 Not Found

Processing Flow

  1. Check view permission
  2. Fetch the survey's versions ordered by version number
  3. Load each version's snapshot

Roll Back from a Version

Overview

Creates a new version restoring the content of the given version, and makes it the latest.

Earlier versions are not deleted; the rollback itself also remains in the history as a version.

URI

POST /api/surveys/{surveyId}/versions/{versionNo}/rollback
Parameter Type Required Notes
surveyId string โ—ฏ Survey UUID
versionNo string โ—ฏ Version number to restore (a numeric string)

Validation Rules

Field Rule
versionNo Required. A string of digits only (^\d+$)

Response (201 Created)

Returns the newly created version schema. rollbackFromVersionId holds the ID of the restored version.

Error Handling

Description Status code Status name
versionNo is not numeric 400 Bad Request
Survey or version does not exist, or edit permission is missing 404 Not Found

Processing Flow

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: POST .../versions/{versionNo}/rollback
    API->>API: Check edit permission
    API->>DB: Fetch the given version
    alt Not found
        API-->>Client: 404 Not Found
    else
        API->>DB: Load that version's snapshot
        API->>DB: Create a new version (record rollbackFromVersionId)
        API->>DB: Copy the snapshot (stable IDs carried over)
        API->>DB: Update the latest version number and pointer
        API-->>Client: 201 Created
    end

Duplicate from a Version

Overview

Creates a separate survey initialized with the content of the given version. The original survey is unchanged.

This is the same operation as Duplicate from a Survey or Version with sourceVersionNo given.

URI

POST /api/surveys/{surveyId}/versions/{versionNo}/duplicate
Parameter Type Required Notes
surveyId string โ—ฏ UUID of the source survey
versionNo string โ—ฏ Source version number (a numeric string)

Response (201 Created)

Returns the duplicated survey schema (not a version).

Error Handling

Description Status code Status name
versionNo is not numeric 400 Bad Request
Survey or version does not exist, or view permission is missing 404 Not Found

Processing Flow

  1. Check view permission
  2. Fetch the given version and its snapshot
  3. Create a new survey (version 1) in a transaction
  4. Carry over the source survey's permissions
  5. Insert the snapshot's sections and questions