curl --request PATCH \
--url https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks \
--header 'Content-Type: application/json' \
--cookie next-auth.session-token= \
--data '
{
"ops": [
{
"op": "update",
"id": "k1p9wq2m4x7c3v8b5n6t0j2r",
"block": {
"id": "k1p9wq2m4x7c3v8b5n6t0j2r",
"name": "Satisfaction",
"elements": [
{
"id": "satisfaction",
"type": "openText",
"headline": {
"en-US": "How satisfied were you?"
},
"required": true,
"inputType": "text"
}
]
}
}
],
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
'
{
"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>"
}
}
]
}
}
}
V3 Surveys
Edit survey blocks
Edits a survey’s blocks in place — update, insert or remove whole blocks without resending the ones you are not changing. Operations apply in order against a single snapshot and are applied atomically: either all of them land or none do.
Blocks are addressed by id, never by position, so a concurrent edit cannot silently redirect an operation onto a different block. An update replaces the target block entirely, the same whole-subtree rule PATCH /api/v3/surveys/{surveyId} uses, and the replacement must carry every language the survey has configured.
Pass expectedUpdatedAt (the updatedAt from your last read) to make the write conditional; see the 409 response. Session cookie or x-api-key.
PATCH
/
api
/
v3
/
surveys
/
{surveyId}
/
blocks
curl --request PATCH \
--url https://app.formbricks.com/api/v3/surveys/{surveyId}/blocks \
--header 'Content-Type: application/json' \
--cookie next-auth.session-token= \
--data '
{
"ops": [
{
"op": "update",
"id": "k1p9wq2m4x7c3v8b5n6t0j2r",
"block": {
"id": "k1p9wq2m4x7c3v8b5n6t0j2r",
"name": "Satisfaction",
"elements": [
{
"id": "satisfaction",
"type": "openText",
"headline": {
"en-US": "How satisfied were you?"
},
"required": true,
"inputType": "text"
}
]
}
}
],
"expectedUpdatedAt": "2026-04-21T10:00:00.000Z"
}
'
{
"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>"
}
}
]
}
}
}
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
Operations applied in order against a single snapshot, atomically — either all of them land or none do. Each operation resolves against the state left by the previous one, so an insert may anchor after a block an earlier operation inserted, and a remove followed by an insert of the same id is legal.
Required array length:
1 - 100 elementsA single block operation.
- Option 1
- Option 2
- Option 3
Show child attributes
Show child attributes
Optimistic-concurrency precondition: the survey's updatedAt from your last read. If the survey changed since, the write is rejected with 409 and the response carries the current value. Omit it to accept last-write-wins.
Response
Blocks updated; 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?