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

updateOneBlock

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"
}
'

200

Example

{
  "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

next-auth.session-token · string · cookie · required

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

surveyId · string<cuid2> · required

Survey identifier.

Body

application/json

ops · object[] · required

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 elements

A single block operation.

Option 1

Option 2

Option 3

Show child attributes

expectedUpdatedAt · string<date-time>

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

200

application/json

Blocks updated; returns the full survey resource.

data · object · required

The three fields every SurveyListItem and SurveyResource carries, merged into both via allOf. All required, always present.

Show child attributes