Docs
Surveys

Update a survey

PATCH/surveys/{id}Needscontent.edit

Saves changes to the working draft. Fields you leave out keep their value; null clears a nullable field. If it's live, visitors keep seeing the published version until you publish again. PUT is accepted as an alias.

Authorization

secretKey
headerAuthorizationBearer <sk_…>

A secret API key from Settings → API keys. It acts with its creator's role.

Path Parameters

id*integer

The survey's id.

Range1 <= value

Request Body

application/json
  1. body
name?string

Name. Default: "New survey".

Lengthlength <= 255
urlPattern?string

Pages it appears on: a full URL or path with * wildcards, e.g. https://app.acme.com/billing*, */settings/*, or * for every page.

Lengthlength <= 500
isActive?boolean

true also publishes the item to production in the same request (needs content.publish; refused with approval_required when the workspace requires review). Omit it to keep a draft.

display?string

Display. How the survey appears. One of: "slideout" (Slide-out (corner, doesn't block the page)), "modal" (Modal (centered, dims the page)). Default: "slideout".

Value in"slideout""modal"
position?string

Corner. Where a slide-out survey sits. One of: "bottom-right" (Bottom right), "bottom-left" (Bottom left). Default: "bottom-right".

Value in"bottom-right""bottom-left"
questions?array<>

Questions. NPS, rating, choice and text questions, with follow-ups.

Items1 <= items <= 12
thankYou?|

Thank-you message. Default: "Thanks for your feedback!".

localizations?

Translations. Question and thank-you text per language.

styling?|

Styling. Accent, background and text colors, corner radius.

delayMs?integer

Delay (ms). Wait this long on the page before showing the survey. Default: 0.

Range0 <= value <= 60000
frequencyType?string

Frequency. How often the same person is asked. One of: "once" (Once per person), "every_n_days" (Again every N days), "always" (Every time (testing)). Default: "once".

Value in"once""every_n_days""always"
frequencyDays?integer

Days between asks. For “Again every N days”. Default: 90.

Range1 <= value <= 365
audienceRules?|

Audience Rules. Advanced audience targeting rules.

priority?integer

Priority. When several pop-ups qualify on the same page, the highest priority shows first. Default: 50.

Range0 <= value <= 100

Response Body

OK

application/json
  1. response
survey*

A survey with its working draft. What visitors see is the version in publication.

Shell
curl -X PATCH 'https://app.cueston.com/api/surveys/1' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example Response
JSON
{
  "survey": {
    "id": 42,
    "name": "Onboarding tour",
    "urlPattern": "https://app.acme.com/*",
    "isActive": true,
    "display": "slideout",
    "position": "bottom-right",
    "questions": [
      {
        "id": "string",
        "type": "nps",
        "prompt": "string",
        "required": false,
        "options": [
          "string"
        ],
        "scaleLabels": {
          "low": "string",
          "high": "string"
        },
        "placeholder": "string",
        "followUp": {
          "whenScoreBelow": -9007199254740991,
          "questionId": "string"
        }
      }
    ],
    "thankYou": "string",
    "localizations": {
      "property1": {
        "thankYou": "string",
        "questions": {
          "property1": {
            "prompt": "string",
            "options": [
              "string"
            ],
            "scaleLabels": {
              "low": "string",
              "high": "string"
            },
            "placeholder": "string"
          },
          "property2": {
            "prompt": "string",
            "options": [
              "string"
            ],
            "scaleLabels": {
              "low": "string",
              "high": "string"
            },
            "placeholder": "string"
          }
        }
      },
      "property2": {
        "thankYou": "string",
        "questions": {
          "property1": {
            "prompt": "string",
            "options": [
              "string"
            ],
            "scaleLabels": {
              "low": "string",
              "high": "string"
            },
            "placeholder": "string"
          },
          "property2": {
            "prompt": "string",
            "options": [
              "string"
            ],
            "scaleLabels": {
              "low": "string",
              "high": "string"
            },
            "placeholder": "string"
          }
        }
      }
    },
    "styling": {
      "accentColor": "string",
      "backgroundColor": "string",
      "textColor": "string",
      "borderRadius": 0
    },
    "delayMs": 0,
    "frequencyType": "once",
    "frequencyDays": 1,
    "audienceRules": {
      "enabled": false,
      "matchType": "all",
      "rules": [
        {
          "id": "string",
          "attribute": "string",
          "operator": "equals",
          "value": "string",
          "key": "string"
        }
      ]
    },
    "priority": 0,
    "createdAt": "2026-10-26T09:30:00Z",
    "updatedAt": "2026-10-26T09:30:00Z",
    "publication": {
      "production": {
        "versionId": 7,
        "version": 3,
        "publishedAt": "2026-10-26T09:30:00Z"
      },
      "staging": {
        "versionId": 7,
        "version": 3,
        "publishedAt": "2026-10-26T09:30:00Z"
      }
    },
    "hasUnpublishedChanges": true
  }
}

Get a surveyGET

The survey's working draft — every field — and what each environment serves.

Delete a surveyDELETE

Deletes the survey with its versions and translations, and stops serving it everywhere. This can't be undone.