Create a tour · Cueston Docs

POST/toursNeedscontent.edit

Creates a draft tour. Nothing is shown to visitors until you publish it (or send isActive: true).

Authorization

secretKey

headerAuthorizationBearer <sk_…>

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

Request Body

application/json

body

name*string

Name. Default: "New Tour".

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.

cardBgColor?string

Background Color. Hex color like #4f46e5. Default: "#ffffff".

Match^#[0-9a-fA-F]{6}$

cardTextColor?string

Text Color. Hex color like #4f46e5. Default: "#1f2937".

Match^#[0-9a-fA-F]{6}$

cardBorderRadius?integer

Border Radius. Corner radius in pixels. Default: 12.

Range0 <= value <= 50

cardPadding?integer

Padding. Internal padding in pixels. Default: 20.

Range0 <= value <= 100

cardShadow?string

Shadow. One of: "none" (None), "0 2px 8px rgba(0,0,0,0.1)" (Small), "0 4px 20px rgba(0,0,0,0.15)" (Medium), "0 8px 30px rgba(0,0,0,0.2)" (Large), "0 12px 40px rgba(0,0,0,0.25)" (Extra Large). Default: "0 4px 20px rgba(0,0,0,0.15)".

Value in"none""0 2px 8px rgba(0,0,0,0.1)""0 4px 20px rgba(0,0,0,0.15)""0 8px 30px rgba(0,0,0,0.2)""0 12px 40px rgba(0,0,0,0.25)"

cardWidth?integer

Width. Tour card width in pixels. Default: 320.

Range200 <= value <= 800

textAlign?string

Text Alignment. One of: "left" (Left), "center" (Center), "right" (Right). Default: "left".

Value in"left""center""right"

cardBlurIntensity?integer

Blur Intensity. Background blur intensity. Default: 0.

Range0 <= value <= 20

cardBgOpacity?integer

Background Opacity. Background opacity percentage. Default: 100.

Range0 <= value <= 100

showBorder?boolean

Show Border. Default: false.

borderColor?string

Border Color. Hex color like #4f46e5. Default: "#e5e7eb".

Match^#[0-9a-fA-F]{6}$

borderThickness?integer

Border Thickness. Border thickness in pixels. Default: 1.

Range0 <= value <= 10

titleSize?integer

Title Size. Title font size in pixels. Default: 16.

Range10 <= value <= 32

bodySize?integer

Body Size. Body font size in pixels. Default: 14.

Range10 <= value <= 24

bodyLineHeight?number

Body Line Height. Line height multiplier. Default: 1.5.

Range1 <= value <= 3

buttonColor?string

Button Color. Hex color like #4f46e5. Default: "#2563eb".

Match^#[0-9a-fA-F]{6}$

buttonTextColor?string

Button Text Color. Hex color like #4f46e5. Default: "#ffffff".

Match^#[0-9a-fA-F]{6}$

buttonBorderRadius?integer

Button Border Radius. Button corner radius in pixels. Default: 8.

Range0 <= value <= 50

buttonSize?string

Button Size. One of: "xxs" (Extra Extra Small), "xs" (Extra Small), "s" (Small), "m" (Medium), "l" (Large), "xl" (Extra Large). Default: "m".

Value in"xxs""xs""s""m""l""xl"

zIndex?integer

Z-Index. Stacking order. Default: 10000.

Range0 <= value <= 99999

scheduleType?string

Schedule Type. One of: "immediate" (Immediate), "scheduled" (Scheduled). Default: "immediate".

Value in"immediate""scheduled"

scheduleDate?|

Schedule Date.

scheduleTime?|

Schedule Time.

timezone?string

Timezone. Default: "UTC".

Lengthlength <= 100

forceTimezone?boolean

Force Timezone. Force this timezone instead of user's local timezone. Default: false.

frequencyType?string

Frequency Type. How often to show this tour. One of: "once" (Show Once), "always" (Always Show), "every_visit" (Every Visit), "every_n_visits" (Every N Visits), "every_n_days" (Every N Days). Default: "once".

Value in"once""always""every_visit""every_n_visits""every_n_days"

frequencyCount?integer

Frequency Count. Number of visits/days between displays. Default: 1.

Range1 <= value <= 100

frequencyDays?integer

Frequency Days. Days between displays (for every_n_days). Default: 7.

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

goal?|

Goal. What counts as success: an event, a page visit or completing other content, within N days.

holdoutPercent?integer

Control group. Share of eligible visitors who don't see this, to measure its effect on the goal. Default: 0.

Range0 <= value <= 50

steps?array<>

Itemsitems <= 50

Response Body

Created

application/json

response

tour*

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

Shell

curl -X POST 'https://app.cueston.com/api/tours' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Onboarding tour",
  "urlPattern": "https://app.acme.com/*"
}'curl -X POST 'https://app.cueston.com/api/tours' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Onboarding tour",
  "urlPattern": "https://app.acme.com/*"
}'

Example ResponseSchema

JSON

{
  "tour": {
    "id": 42,
    "name": "Onboarding tour",
    "urlPattern": "https://app.acme.com/*",
    "isActive": true,
    "cardBgColor": "string",
    "cardTextColor": "string",
    "cardBorderRadius": 0,
    "cardPadding": 0,
    "cardShadow": "none",
    "cardWidth": 200,
    "textAlign": "left",
    "cardBlurIntensity": 0,
    "cardBgOpacity": 0,
    "showBorder": true,
    "borderColor": "string",
    "borderThickness": 0,
    "titleSize": 10,
    "bodySize": 10,
    "bodyLineHeight": 1,
    "buttonColor": "string",
    "buttonTextColor": "string",
    "buttonBorderRadius": 0,
    "buttonSize": "xxs",
    "zIndex": 0,
    "scheduleType": "immediate",
    "scheduleDate": "string",
    "scheduleTime": "string",
    "timezone": "string",
    "forceTimezone": true,
    "frequencyType": "once",
    "frequencyCount": 1,
    "frequencyDays": 1,
    "audienceRules": {
      "enabled": false,
      "matchType": "all",
      "rules": [
        {
          "id": "string",
          "attribute": "string",
          "operator": "equals",
          "value": "string",
          "key": "string"
        }
      ]
    },
    "priority": 0,
    "goal": {
      "type": "event",
      "event": "string",
      "urlPattern": "https://app.acme.com/*",
      "contentRef": "string",
      "withinDays": 7
    },
    "holdoutPercent": 0,
    "steps": [
      {
        "id": 42,
        "stepOrder": 0,
        "selector": "#export-button",
        "title": "Welcome to Acme",
        "content": "Export any report as CSV from here.",
        "imageUrl": null,
        "buttonText": "Next",
        "placement": "auto",
        "pulseEnabled": true,
        "zIndex": 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
  }
}{
  "tour": {
    "id": 42,
    "name": "Onboarding tour",
    "urlPattern": "https://app.acme.com/*",
    "isActive": true,
    "cardBgColor": "string",
    "cardTextColor": "string",
    "cardBorderRadius": 0,
    "cardPadding": 0,
    "cardShadow": "none",
    "cardWidth": 200,
    "textAlign": "left",
    "cardBlurIntensity": 0,
    "cardBgOpacity": 0,
    "showBorder": true,
    "borderColor": "string",
    "borderThickness": 0,
    "titleSize": 10,
    "bodySize": 10,
    "bodyLineHeight": 1,
    "buttonColor": "string",
    "buttonTextColor": "string",
    "buttonBorderRadius": 0,
    "buttonSize": "xxs",
    "zIndex": 0,
    "scheduleType": "immediate",
    "scheduleDate": "string",
    "scheduleTime": "string",
    "timezone": "string",
    "forceTimezone": true,
    "frequencyType": "once",
    "frequencyCount": 1,
    "frequencyDays": 1,
    "audienceRules": {
      "enabled": false,
      "matchType": "all",
      "rules": [
        {
          "id": "string",
          "attribute": "string",
          "operator": "equals",
          "value": "string",
          "key": "string"
        }
      ]
    },
    "priority": 0,
    "goal": {
      "type": "event",
      "event": "string",
      "urlPattern": "https://app.acme.com/*",
      "contentRef": "string",
      "withinDays": 7
    },
    "holdoutPercent": 0,
    "steps": [
      {
        "id": 42,
        "stepOrder": 0,
        "selector": "#export-button",
        "title": "Welcome to Acme",
        "content": "Export any report as CSV from here.",
        "imageUrl": null,
        "buttonText": "Next",
        "placement": "auto",
        "pulseEnabled": true,
        "zIndex": 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
  }
}