Skip to content

Sections API

Endpoints that manage the sections (major groups) of a questionnaire.

Sections belong to the latest version's snapshot, not to the survey itself. Adding, updating, and deleting all target the latest version; earlier versions are never modified.

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

Method

HTTP Methods

Method URI Overview
POST /api/surveys/{surveyId}/sections Add a section and generate an initial draft
PATCH /api/sections/{sectionId} Update a section
DELETE /api/sections/{sectionId} Delete a section
POST /api/sections/{sectionId}/duplicate Duplicate a section
POST /api/sections/import Import a section
POST /api/sections/import-from-external Insert one section from external-origin entries

Resource Definition

Section Schema

Field Type Notes
id string UUID of the snapshot row. Changes when the version changes
title string Section title
description string Description
sortOrder number Position within the version
generatedBy string Origin. manual, ้กžไผผใ‚ปใ‚ฏใ‚ทใƒงใƒณ็”Ÿๆˆ, and so on
questionCount number Number of questions
pageCount number Number of pages (questions linked to the previous one are grouped)
questions Question[] The questions
updatedAt string ISO 8601

Authentication

User authentication via the x-user-email / x-user-name headers is required. Every operation needs edit permission on the target survey, and imports also need view permission on the source survey. Missing permission returns 404 Not Found.

Add a Section

Overview

Adds a section to the survey's latest version. Draft questions are generated automatically from the title, and their question codes are re-assigned so that they stay unique within the survey.

URI

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

Request Body

{
  "title": "ใ‚นใ‚ฏใƒชใƒผใƒ‹ใƒณใ‚ฐ",
  "description": ""
}

Validation Rules

Field Rule
title Required. String
description Optional. Defaults to "ๆ–ฐ่ฆ่ฟฝๅŠ ใ‚ปใ‚ฏใ‚ทใƒงใƒณ"

Response (201 Created)

Returns the added section schema.

Error Handling

Description Status code Status name
Malformed request body 400 Bad Request
Survey 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 /api/surveys/{surveyId}/sections
    API->>API: Check edit permission
    API->>DB: Get the latest version ID and existing sections
    API->>API: Generate draft questions from the title
    API->>API: Re-assign codes so they do not clash
    API->>DB: Insert the section at the end
    API-->>Client: 201 Created

Update a Section

Overview

Updates a section's title, description, and sort order.

Changing sortOrder swaps the section with whichever one was at that position. To avoid violating the unique constraint on (version ID, sort order), the swap goes through a temporary sort order.

URI

PATCH /api/sections/{sectionId}
Parameter Type Required Notes
sectionId string โ—ฏ UUID of the section (snapshot row)

Request Body

{
  "title": "ใ‚นใ‚ฏใƒชใƒผใƒ‹ใƒณใ‚ฐ",
  "description": "",
  "sortOrder": 2
}

Validation Rules

Field Rule
title Optional. String
description Optional. String
sortOrder Optional. Integer. The target position

Response (200 OK)

Returns the updated section schema.

Error Handling

Description Status code Status name
Malformed request body 400 Bad Request
Section does not exist, or edit permission is missing 404 Not Found

Processing Flow

  1. Resolve the owning survey from the section and check edit permission
  2. If sortOrder is given and differs from the current value:
    1. Find the section currently at the target position
    2. Move the target section to a temporary sort order
    3. Move the section that was at the target position to the original sort order
    4. Set the target section to the target sort order
  3. Update title / description

Delete a Section

Overview

Deletes a section. Its questions, choices, branch rules, and visibility rules are deleted along with it (a hard delete).

URI

DELETE /api/sections/{sectionId}

Response (200 OK)

{ "ok": true, "data": { "deleted": true } }

Error Handling

Description Status code Status name
Section does not exist, or edit permission is missing 404 Not Found

Different from deleting a survey

Surveys are soft deleted, but sections and questions are hard deleted from the latest version's snapshot. The snapshots of earlier versions remain, so a rollback can restore them.

Duplicate a Section

Overview

Duplicates a section together with its questions and appends it to the latest version. Question codes are re-assigned so that they stay unique within the survey.

URI

POST /api/sections/{sectionId}/duplicate

Response (201 Created)

Returns the duplicated section schema.

Error Handling

Description Status code Status name
Section does not exist, or edit permission is missing 404 Not Found

Processing Flow

  1. Resolve the owning survey from the section and check edit permission
  2. Load the section with its questions, choices, branch rules, and visibility rules
  3. Re-assign question codes so they do not clash with existing ones
  4. Insert as a new section at the end

Self-references are re-pointed

References such as exclusive settings that pointed at the original question are re-pointed at the copy's question code.

Import a Section

Overview

Imports a section from another survey, together with its questions, into your own survey.

URI

POST /api/sections/import

Request Body

{
  "sourceSurveyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sourceSectionId": "โ€ฆ",
  "targetSurveyId": "โ€ฆ"
}

Validation Rules

Field Rule
sourceSurveyId Required. UUID of the source survey
sourceSectionId Required. UUID of the source section
targetSurveyId Required. UUID of the destination survey

Response (201 Created)

Returns the section created in the destination survey.

Error Handling

Description Status code Status name
Malformed request body 400 Bad Request
Source or destination does not exist, or permission is missing 404 Not Found

Processing Flow

The source section is searched for in several ways, because IDs change across versions.

  1. Check edit permission on the destination and view permission on the source
  2. Look for sourceSectionId in the source survey's latest version (the normal path)
  3. If not found, look in the latest version by stable ID (stableSectionId)
  4. If still not found, read the snapshot row directly
  5. Re-assign question codes so they are unique in the destination
  6. Insert the section at the end of the destination's latest version

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: POST /api/sections/import
    API->>API: Check permissions (destination edit / source view)
    API->>DB: A. Search the latest version by sectionId
    alt Not found
        API->>DB: B. Search the latest version by stable ID
        alt Not found
            API->>DB: C. Read the snapshot row directly
        end
    end
    API->>API: Re-assign question codes
    API->>DB: Insert at the end of the destination
    API-->>Client: 201 Created

Permission bypass

Path C (reading the snapshot directly) does not go through the permission check โ€” a known issue (Infrastructure).

Insert One Section from External Entries

Overview

Selects several questions from a questionnaire imported from CS (external-origin entries in the question library) and inserts them as one new section.

Section candidates come from the section candidate preview in the Imports API.

URI

POST /api/sections/import-from-external

Request Body

{
  "targetSurveyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "libraryItemIds": ["โ€ฆ", "โ€ฆ"],
  "sectionTitle": "ใ‚นใ‚ฏใƒชใƒผใƒ‹ใƒณใ‚ฐ",
  "sectionDescription": ""
}

Validation Rules

Field Rule
targetSurveyId Required. UUID format
libraryItemIds Required. Array of UUIDs, at least one. The array order becomes the question order
sectionTitle Required. 1โ€“255 characters
sectionDescription Optional. Empty string when omitted

Response (201 Created)

Returns the created section schema.

Error Handling

Description Status code Status name
Malformed request body 400 Bad Request
Destination survey or library entries do not exist, or permission is missing 404 Not Found

Processing Flow

  1. Check edit permission on the destination survey
  2. Fetch the library entries for libraryItemIds, preserving the request order
  3. Build a question payload from each entry
    • External origin: build from the normalized payload
    • Internal origin: build from the source survey's snapshot
  4. Re-assign question codes so they are unique in the destination
  5. Create the new section and insert the questions together

Branching is not carried over

The question library does not store branch rules or visibility logic, so they must be configured again after the import.