Create a banner · Cueston Docs

POST/bannersNeedscontent.edit

Creates a draft banner. 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 Banner".

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.

title?|

Title.

body?|

Body.

imageUrl?|

Image URL. Absolute https URL.

buttonText?|

Button Text.

imagePosition?string

Image Position. One of: "top" (Top), "left" (Left), "right" (Right), "bottom" (Bottom). Default: "top".

Value in"top""left""right""bottom"

showCloseButton?boolean

Show Close Button. Allow users to close the banner. Default: true.

positionX?string

Horizontal Position. One of: "left" (Left), "center" (Center), "right" (Right). Default: "center".

Value in"left""center""right"

positionY?string

Vertical Position. One of: "top" (Top), "center" (Center), "bottom" (Bottom). Default: "top".

Value in"top""center""bottom"

offsetX?integer

Horizontal Offset. Horizontal offset in pixels. Default: 0.

Range-1000 <= value <= 1000

offsetY?integer

Vertical Offset. Vertical offset in pixels. Default: 0.

Range-1000 <= value <= 1000

width?integer

Width. Banner width in pixels. Default: 400.

Range200 <= value <= 1200

height?|

Height. Banner height (auto or fixed). One of: "auto" (Auto), "200" (200px), "300" (300px), "400" (400px), "500" (500px). Default: "auto".

showBackdrop?boolean

Show Backdrop. Show darkened backdrop behind banner. Default: false.

backdropOpacity?integer

Backdrop Opacity. Backdrop opacity percentage. Default: 50.

Range0 <= value <= 100

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

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 in pixels. 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"

buttonPosition?string

Button Position. One of: "left" (Left), "center" (Center), "right" (Right). Default: "left".

Value in"left""center""right"

buttonType?string

Button Type. One of: "regular" (Regular), "stretched" (Stretched (Full Width)). Default: "regular".

Value in"regular""stretched"

zIndex?integer

Z-Index. Stacking order. Default: 10000.

Range0 <= value <= 99999

delayMs?integer

Delay (ms). Delay before showing banner. Default: 0.

Range0 <= value <= 10000

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. One of: "once" (Once), "daily" (Daily), "weekly" (Weekly), "custom" (Custom). Default: "once".

Value in"once""daily""weekly""custom"

frequencyCount?integer

Frequency Count. Number of times to show. Default: 1.

Range1 <= value <= 100

frequencyDays?integer

Frequency Days. Number of days between shows. 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

Response Body

Created

application/json

response

banner*

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

Shell

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

Example ResponseSchema

JSON

{
  "banner": {
    "id": 42,
    "name": "Onboarding tour",
    "urlPattern": "https://app.acme.com/*",
    "isActive": true,
    "title": "Welcome to Acme",
    "body": "Here's a quick look at where everything is.",
    "imageUrl": "string",
    "buttonText": "Next",
    "imagePosition": "top",
    "showCloseButton": true,
    "positionX": "left",
    "positionY": "top",
    "offsetX": -1000,
    "offsetY": -1000,
    "width": 200,
    "height": "string",
    "showBackdrop": true,
    "backdropOpacity": 0,
    "cardBgColor": "string",
    "cardTextColor": "string",
    "cardBorderRadius": 0,
    "cardPadding": 0,
    "cardShadow": "none",
    "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",
    "buttonPosition": "left",
    "buttonType": "regular",
    "zIndex": 0,
    "delayMs": 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,
    "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
  }
}{
  "banner": {
    "id": 42,
    "name": "Onboarding tour",
    "urlPattern": "https://app.acme.com/*",
    "isActive": true,
    "title": "Welcome to Acme",
    "body": "Here's a quick look at where everything is.",
    "imageUrl": "string",
    "buttonText": "Next",
    "imagePosition": "top",
    "showCloseButton": true,
    "positionX": "left",
    "positionY": "top",
    "offsetX": -1000,
    "offsetY": -1000,
    "width": 200,
    "height": "string",
    "showBackdrop": true,
    "backdropOpacity": 0,
    "cardBgColor": "string",
    "cardTextColor": "string",
    "cardBorderRadius": 0,
    "cardPadding": 0,
    "cardShadow": "none",
    "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",
    "buttonPosition": "left",
    "buttonType": "regular",
    "zIndex": 0,
    "delayMs": 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,
    "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
  }
}