Create a announcement · Cueston Docs

POST/announcementsNeedscontent.edit

Creates a draft announcement. 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. Only your team sees this. Default: "New announcement".

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?string

Title. Default: "What's new".

Lengthlength <= 200

body?string

Body. Bold, italic, links and lists.

Lengthlength <= 40000

imageUrl?|

Image. Optional picture at the top of the card. Absolute https URL.

imageAlt?|

Image description. What the image shows, for screen readers. Leave empty if it's decorative.

ctaLabel?string

Button label. Empty = no button.

Lengthlength <= 60

ctaAction?||

Button action. Open a link or start a tour.

Default

JSON

{
  "type": "none"
}{
  "type": "none"
}

labels?array<>

Labels. Up to 5 tags, like "New" or "Improvement".

Itemsitems <= 5

Default[]

display?string

Display. The banner or pop-up shows once per person. One of: "feed" (What's new feed only), "banner" (Feed, and a banner on publish), "modal" (Feed, and a pop-up on publish). Default: "feed".

Value in"feed""banner""modal"

scheduleType?"scheduled"

Schedule. One of: "scheduled" (On the publish date). Default: "scheduled".

Value in"scheduled"

scheduleDate?string

Publish date. Shown on the card. Nobody sees the announcement before this date.

scheduleTime?|

Publish time. In each visitor's own timezone. Empty = midnight.

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

frequencyType?"once"

Frequency. One of: "once" (Pop-up once per person). Default: "once".

Value in"once"

Response Body

Created

application/json

response

announcement*

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

Shell

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

Example ResponseSchema

JSON

{
  "announcement": {
    "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",
    "imageAlt": "string",
    "ctaLabel": "string",
    "ctaAction": {
      "type": "none"
    },
    "labels": [],
    "display": "feed",
    "scheduleType": "scheduled",
    "scheduleDate": "string",
    "scheduleTime": "string",
    "audienceRules": {
      "enabled": false,
      "matchType": "all",
      "rules": [
        {
          "id": "string",
          "attribute": "string",
          "operator": "equals",
          "value": "string",
          "key": "string"
        }
      ]
    },
    "priority": 0,
    "frequencyType": "once",
    "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
  }
}{
  "announcement": {
    "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",
    "imageAlt": "string",
    "ctaLabel": "string",
    "ctaAction": {
      "type": "none"
    },
    "labels": [],
    "display": "feed",
    "scheduleType": "scheduled",
    "scheduleDate": "string",
    "scheduleTime": "string",
    "audienceRules": {
      "enabled": false,
      "matchType": "all",
      "rules": [
        {
          "id": "string",
          "attribute": "string",
          "operator": "equals",
          "value": "string",
          "key": "string"
        }
      ]
    },
    "priority": 0,
    "frequencyType": "once",
    "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
  }
}