Set survey block order
curl --request PUT \
--url https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order \
--header 'Content-Type: application/json' \
--cookie next-auth.session-token= \
--data '
{
"order": [
"b4h8s2d6f0g3j5k7l9z1x3c5",
"k1p9wq2m4x7c3v8b5n6t0j2r",
"n7m4q8w2e6r0t3y5u1i9o2p4"
],
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
'import requests
url = "https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order"
payload = {
"order": ["b4h8s2d6f0g3j5k7l9z1x3c5", "k1p9wq2m4x7c3v8b5n6t0j2r", "n7m4q8w2e6r0t3y5u1i9o2p4"],
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
headers = {
"cookie": "next-auth.session-token=",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {cookie: 'next-auth.session-token=', 'Content-Type': 'application/json'},
body: JSON.stringify({
order: [
'b4h8s2d6f0g3j5k7l9z1x3c5',
'k1p9wq2m4x7c3v8b5n6t0j2r',
'n7m4q8w2e6r0t3y5u1i9o2p4'
],
expectedUpdatedAt: '2026-04-21T10:00:00.000Z'
})
};
fetch('https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'order' => [
'b4h8s2d6f0g3j5k7l9z1x3c5',
'k1p9wq2m4x7c3v8b5n6t0j2r',
'n7m4q8w2e6r0t3y5u1i9o2p4'
],
'expectedUpdatedAt' => '2026-04-21T10:00:00.000Z'
]),
CURLOPT_COOKIE => "next-auth.session-token=",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order"
payload := strings.NewReader("{\n \"order\": [\n \"b4h8s2d6f0g3j5k7l9z1x3c5\",\n \"k1p9wq2m4x7c3v8b5n6t0j2r\",\n \"n7m4q8w2e6r0t3y5u1i9o2p4\"\n ],\n \"expectedUpdatedAt\": \"2026-04-21T10:00:00.000Z\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("cookie", "next-auth.session-token=")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order")
.header("cookie", "next-auth.session-token=")
.header("Content-Type", "application/json")
.body("{\n \"order\": [\n \"b4h8s2d6f0g3j5k7l9z1x3c5\",\n \"k1p9wq2m4x7c3v8b5n6t0j2r\",\n \"n7m4q8w2e6r0t3y5u1i9o2p4\"\n ],\n \"expectedUpdatedAt\": \"2026-04-21T10:00:00.000Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["cookie"] = 'next-auth.session-token='
request["Content-Type"] = 'application/json'
request.body = "{\n \"order\": [\n \"b4h8s2d6f0g3j5k7l9z1x3c5\",\n \"k1p9wq2m4x7c3v8b5n6t0j2r\",\n \"n7m4q8w2e6r0t3y5u1i9o2p4\"\n ],\n \"expectedUpdatedAt\": \"2026-04-21T10:00:00.000Z\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "<string>",
"workspaceId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"archivedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"type": "link",
"status": "draft",
"metadata": {
"title": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"description": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
}
},
"defaultLanguage": "<string>",
"languages": [
{
"code": "en-US",
"default": true,
"enabled": true,
"alias": "english"
}
],
"showLanguageSwitch": true,
"autoSelectLanguage": true,
"welcomeCard": {
"enabled": true,
"headline": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"subheader": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"buttonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"fileUrl": "<string>",
"videoUrl": "<string>",
"timeToFinish": true,
"showResponseCount": true
},
"blocks": [
{
"id": "<string>",
"name": "<string>",
"elements": [
{
"id": "<string>",
"type": "openText",
"headline": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"required": true,
"subheader": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"imageUrl": "<string>",
"imageAltText": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"videoUrl": "<string>",
"isDraft": true,
"placeholder": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"longAnswer": true,
"inputType": "text",
"insightsEnabled": false,
"charLimit": {
"enabled": false,
"min": 123,
"max": 123
},
"validation": {
"rules": [
{
"id": "<string>",
"type": "minLength",
"params": {},
"field": "addressLine1"
}
],
"logic": "and"
}
}
],
"logic": [
{
"id": "<string>",
"conditions": {
"id": "<string>",
"connector": "and",
"conditions": [
{
"id": "<string>",
"leftOperand": {
"type": "element",
"value": "<string>",
"meta": {}
},
"operator": "equals",
"rightOperand": {
"type": "static",
"value": "<string>"
}
}
]
},
"actions": [
{
"id": "<string>",
"objective": "calculate",
"variableId": "<string>",
"operator": "assign",
"value": {
"type": "static",
"value": "<string>"
}
}
]
}
],
"logicFallback": "<string>",
"buttonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"backButtonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
}
}
],
"endings": [
{
"id": "<string>",
"type": "endScreen",
"headline": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"subheader": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"buttonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"buttonLink": "<string>",
"imageUrl": "<string>",
"imageAltText": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"videoUrl": "<string>",
"hideDefaultIcon": true
}
],
"hiddenFields": {
"enabled": true,
"fieldIds": [
"<string>"
]
},
"variables": [
{
"id": "<string>",
"name": "<string>",
"type": "number",
"value": 123
}
],
"customCss": {
"light": "<string>",
"dark": "<string>"
},
"visibility": "restricted",
"owner": {
"name": "<string>"
},
"access": {
"via": "workspace",
"canManageVisibility": true
},
"distribution": {
"displayOption": "displaySome",
"displayLimit": 3,
"displayPercentage": null,
"recontactDays": 7,
"autoClose": null,
"autoComplete": null,
"delay": 0,
"triggers": [
{
"actionClassId": "clyy1234567890123456789012"
}
]
},
"targeting": {
"filters": [
{
"id": "<string>",
"connector": "and",
"resource": {
"id": "<string>",
"root": {
"type": "attribute",
"contactAttributeKey": "<string>"
},
"qualifier": {
"operator": "lessThan"
},
"value": "<string>"
}
}
]
}
}
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "Conflict",
"status": 409,
"detail": "Survey was modified since it was last read; updatedAt is now 2026-04-21T11:30:00.000Z. Re-read the survey and retry.",
"code": "conflict",
"requestId": "6f1f7f3e-3b0e-4a1a-9f0a-7c9a1d2b3c4d",
"details": {
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z",
"currentUpdatedAt": "2026-04-21T11:30:00.000Z"
}
}{
"title": "Unprocessable Content",
"status": 422,
"detail": "Block order must list every block exactly once",
"code": "unprocessable_content",
"requestId": "6f1f7f3e-3b0e-4a1a-9f0a-7c9a1d2b3c4d",
"invalid_params": [
{
"name": "order",
"reason": "Block 'n7m4q8w2e6r0t3y5u1i9o2p4' is missing from the order; list every block exactly once",
"code": "missing_required_field",
"identifier": "n7m4q8w2e6r0t3y5u1i9o2p4",
"referenceType": "block",
"missingId": "n7m4q8w2e6r0t3y5u1i9o2p4"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}V3 Surveys
Set survey block order
Replaces the order of a survey’s blocks. The body lists every current block id exactly once, in the order you want; block content is untouched.
Idempotent: the same order always yields the same survey, and an order that already matches performs no write at all, so updatedAt does not move and other callers’ preconditions stay valid. A stale expectedUpdatedAt is still rejected with 409 on that path — the precondition is evaluated before the method, so a no-op outcome never reports success to a stale caller. Because the list must be a permutation, a dropped or duplicated block is rejected rather than silently applied — the failure mode that resending the whole blocks array cannot catch.
Pass expectedUpdatedAt (the updatedAt from your last read) to make the write conditional; see the 409 response. Session cookie or x-api-key.
PUT
/
api
/
v3
/
surveys
/
{surveyId}
/
blocks
/
order
Set survey block order
curl --request PUT \
--url https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order \
--header 'Content-Type: application/json' \
--cookie next-auth.session-token= \
--data '
{
"order": [
"b4h8s2d6f0g3j5k7l9z1x3c5",
"k1p9wq2m4x7c3v8b5n6t0j2r",
"n7m4q8w2e6r0t3y5u1i9o2p4"
],
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
'import requests
url = "https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order"
payload = {
"order": ["b4h8s2d6f0g3j5k7l9z1x3c5", "k1p9wq2m4x7c3v8b5n6t0j2r", "n7m4q8w2e6r0t3y5u1i9o2p4"],
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
headers = {
"cookie": "next-auth.session-token=",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {cookie: 'next-auth.session-token=', 'Content-Type': 'application/json'},
body: JSON.stringify({
order: [
'b4h8s2d6f0g3j5k7l9z1x3c5',
'k1p9wq2m4x7c3v8b5n6t0j2r',
'n7m4q8w2e6r0t3y5u1i9o2p4'
],
expectedUpdatedAt: '2026-04-21T10:00:00.000Z'
})
};
fetch('https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'order' => [
'b4h8s2d6f0g3j5k7l9z1x3c5',
'k1p9wq2m4x7c3v8b5n6t0j2r',
'n7m4q8w2e6r0t3y5u1i9o2p4'
],
'expectedUpdatedAt' => '2026-04-21T10:00:00.000Z'
]),
CURLOPT_COOKIE => "next-auth.session-token=",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order"
payload := strings.NewReader("{\n \"order\": [\n \"b4h8s2d6f0g3j5k7l9z1x3c5\",\n \"k1p9wq2m4x7c3v8b5n6t0j2r\",\n \"n7m4q8w2e6r0t3y5u1i9o2p4\"\n ],\n \"expectedUpdatedAt\": \"2026-04-21T10:00:00.000Z\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("cookie", "next-auth.session-token=")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order")
.header("cookie", "next-auth.session-token=")
.header("Content-Type", "application/json")
.body("{\n \"order\": [\n \"b4h8s2d6f0g3j5k7l9z1x3c5\",\n \"k1p9wq2m4x7c3v8b5n6t0j2r\",\n \"n7m4q8w2e6r0t3y5u1i9o2p4\"\n ],\n \"expectedUpdatedAt\": \"2026-04-21T10:00:00.000Z\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks/order")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["cookie"] = 'next-auth.session-token='
request["Content-Type"] = 'application/json'
request.body = "{\n \"order\": [\n \"b4h8s2d6f0g3j5k7l9z1x3c5\",\n \"k1p9wq2m4x7c3v8b5n6t0j2r\",\n \"n7m4q8w2e6r0t3y5u1i9o2p4\"\n ],\n \"expectedUpdatedAt\": \"2026-04-21T10:00:00.000Z\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "<string>",
"workspaceId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"archivedAt": "2023-11-07T05:31:56Z",
"name": "<string>",
"type": "link",
"status": "draft",
"metadata": {
"title": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"description": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
}
},
"defaultLanguage": "<string>",
"languages": [
{
"code": "en-US",
"default": true,
"enabled": true,
"alias": "english"
}
],
"showLanguageSwitch": true,
"autoSelectLanguage": true,
"welcomeCard": {
"enabled": true,
"headline": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"subheader": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"buttonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"fileUrl": "<string>",
"videoUrl": "<string>",
"timeToFinish": true,
"showResponseCount": true
},
"blocks": [
{
"id": "<string>",
"name": "<string>",
"elements": [
{
"id": "<string>",
"type": "openText",
"headline": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"required": true,
"subheader": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"imageUrl": "<string>",
"imageAltText": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"videoUrl": "<string>",
"isDraft": true,
"placeholder": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"longAnswer": true,
"inputType": "text",
"insightsEnabled": false,
"charLimit": {
"enabled": false,
"min": 123,
"max": 123
},
"validation": {
"rules": [
{
"id": "<string>",
"type": "minLength",
"params": {},
"field": "addressLine1"
}
],
"logic": "and"
}
}
],
"logic": [
{
"id": "<string>",
"conditions": {
"id": "<string>",
"connector": "and",
"conditions": [
{
"id": "<string>",
"leftOperand": {
"type": "element",
"value": "<string>",
"meta": {}
},
"operator": "equals",
"rightOperand": {
"type": "static",
"value": "<string>"
}
}
]
},
"actions": [
{
"id": "<string>",
"objective": "calculate",
"variableId": "<string>",
"operator": "assign",
"value": {
"type": "static",
"value": "<string>"
}
}
]
}
],
"logicFallback": "<string>",
"buttonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"backButtonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
}
}
],
"endings": [
{
"id": "<string>",
"type": "endScreen",
"headline": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"subheader": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"buttonLabel": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"buttonLink": "<string>",
"imageUrl": "<string>",
"imageAltText": {
"en-US": "What should we improve?",
"de-DE": "Was sollten wir verbessern?"
},
"videoUrl": "<string>",
"hideDefaultIcon": true
}
],
"hiddenFields": {
"enabled": true,
"fieldIds": [
"<string>"
]
},
"variables": [
{
"id": "<string>",
"name": "<string>",
"type": "number",
"value": 123
}
],
"customCss": {
"light": "<string>",
"dark": "<string>"
},
"visibility": "restricted",
"owner": {
"name": "<string>"
},
"access": {
"via": "workspace",
"canManageVisibility": true
},
"distribution": {
"displayOption": "displaySome",
"displayLimit": 3,
"displayPercentage": null,
"recontactDays": 7,
"autoClose": null,
"autoComplete": null,
"delay": 0,
"triggers": [
{
"actionClassId": "clyy1234567890123456789012"
}
]
},
"targeting": {
"filters": [
{
"id": "<string>",
"connector": "and",
"resource": {
"id": "<string>",
"root": {
"type": "attribute",
"contactAttributeKey": "<string>"
},
"qualifier": {
"operator": "lessThan"
},
"value": "<string>"
}
}
]
}
}
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "Conflict",
"status": 409,
"detail": "Survey was modified since it was last read; updatedAt is now 2026-04-21T11:30:00.000Z. Re-read the survey and retry.",
"code": "conflict",
"requestId": "6f1f7f3e-3b0e-4a1a-9f0a-7c9a1d2b3c4d",
"details": {
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z",
"currentUpdatedAt": "2026-04-21T11:30:00.000Z"
}
}{
"title": "Unprocessable Content",
"status": 422,
"detail": "Block order must list every block exactly once",
"code": "unprocessable_content",
"requestId": "6f1f7f3e-3b0e-4a1a-9f0a-7c9a1d2b3c4d",
"invalid_params": [
{
"name": "order",
"reason": "Block 'n7m4q8w2e6r0t3y5u1i9o2p4' is missing from the order; list every block exactly once",
"code": "missing_required_field",
"identifier": "n7m4q8w2e6r0t3y5u1i9o2p4",
"referenceType": "block",
"missingId": "n7m4q8w2e6r0t3y5u1i9o2p4"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}{
"title": "<string>",
"status": 123,
"detail": "<string>",
"requestId": "<string>",
"type": "<string>",
"instance": "<string>",
"code": "ai_features_not_enabled",
"details": {},
"invalid_params": [
{
"name": "<string>",
"reason": "<string>",
"code": "dangling_reference",
"identifier": "<string>",
"referenceType": "block",
"missingId": "<string>",
"firstUsedAt": "<string>",
"conflictsWith": "<string>"
}
]
}Authorizations
sessionAuthapiKeyAuthbearerAuth
NextAuth session JWT cookie. Development: often next-auth.session-token.
Production (HTTPS): often __Secure-next-auth.session-token. Send the cookie your browser receives after sign-in.
Path Parameters
Survey identifier.
Body
application/json
Every current block id, exactly once, in the desired order. Ids are trimmed before use, so an id that is empty or whitespace-only is a 400, as is a list of more than 1000 ids. A missing, unknown or repeated id is a 422 — repeats are reported as duplicate_identifier rather than rejected by the schema, so the response names the offending entry, and a dropped block cannot pass unnoticed, which is what makes this safer than resending the blocks.
Required array length:
1 - 1000 elementsRequired string length:
1 - 128Optimistic-concurrency precondition: the survey's updatedAt from your last read. If the survey changed since, the write is rejected with 409.
Response
Order applied (or already matching); returns the full survey resource.
The three fields every SurveyListItem and SurveyResource carries, merged into both via allOf. All required, always present.
Show child attributes
Show child attributes
Was this page helpful?