Content API

The Content API provides a unified interface for managing all content types: tooltips, beacons, task-lists, surveys, announcements, and self-help widgets.

NPS surveys are a sibling resource served from the dedicated /api/nps-surveys endpoints, not the content router. See the NPS Surveys section in this reference.

All endpoints require JWT authentication and are scoped to the current tenant.

Content Types

The :type path parameter accepts the following values (URL slugs):

Type	Description
tooltips	Contextual messages anchored to a DOM element
beacons	Pulsing indicators that draw attention to an element
task-lists	Multi-item checklists with completion tracking
surveys	Multi-question forms (rating, text, choice, scale, NPS, etc.)
announcements	Modal, banner, slideout, or toast messages
self-help	Knowledge base widgets embedded in the application

List Content

GET /api/content/:type

Returns a paginated list of content items for the given type.

Query Parameters

Parameter	Type	Default	Description
page	string	"1"	Page number
limit	string	"20"	Items per page
status	string	—	Filter by status (DRAFT, SCHEDULED, PUBLISHED, ARCHIVED)
search	string	—	Search by name
siteId	uuid	—	Restrict to a single site
sortBy	string	—	One of name, status, createdAt, updatedAt
sortDirection	string	—	asc or desc

Response

{
  "data": [
    {
      "id": "ct_abc123",
      "name": "Welcome Tooltip",
      "siteId": "site_xyz",
      "status": "PUBLISHED",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-20T14:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Create Content

POST /api/content/:type

Creates a new content item. The request body varies by content type. name and siteId are required for every type.

Tooltip

{
  "name": "Feature Highlight",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "targetSelector": "#new-feature-btn",
  "content": { "text": "Click here to try the new feature" },
  "position": "AUTO",
  "targetUrl": "https://app.example.com/dashboard",
  "audienceId": "aud_xyz"
}

position is one of AUTO, TOP, BOTTOM, LEFT, RIGHT. Tooltips do not accept an animation field — animation is configured on the parent flow step or on beacons.

Beacon

{
  "name": "Attention Beacon",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "targetSelector": ".sidebar-menu",
  "content": { "message": "Check out this new section" },
  "targetUrl": "https://app.example.com/settings",
  "animation": "subtle",
  "audienceId": "aud_xyz"
}

animation is one of none, subtle, full.

Task List

{
  "name": "Onboarding Checklist",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Get started with key features",
  "audienceId": "aud_xyz",
  "items": [
    {
      "title": "Complete your profile",
      "actionType": "NAVIGATE",
      "actionConfig": { "url": "/settings/profile" },
      "order": 0
    }
  ]
}

actionType is one of NAVIGATE, COMPLETE_FLOW, FILL_FORM, EXTERNAL_LINK. To launch a flow from a task, use COMPLETE_FLOW with actionConfig: { "flowId": "<flow-id>" }.

Survey

{
  "name": "Feature Feedback",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "audienceId": "aud_xyz",
  "questions": [
    {
      "type": "SINGLE_CHOICE",
      "question": "How useful was this feature?",
      "required": true,
      "options": {
        "choices": ["Very useful", "Somewhat useful", "Not useful"]
      },
      "order": 0
    }
  ]
}

type is one of RATING, TEXT, MULTIPLE_CHOICE, SINGLE_CHOICE, NPS, SCALE, BOOLEAN, DROPDOWN. triggerConfig is optional and follows the shape described in Trigger Configuration.

Announcement

{
  "name": "Maintenance Notice",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "BANNER",
  "content": {
    "title": "Scheduled Maintenance",
    "body": "Downtime expected on Saturday"
  },
  "scheduledAt": "2026-02-01T08:00:00Z",
  "expiresAt": "2026-02-02T08:00:00Z",
  "audienceId": "aud_xyz"
}

type is one of MODAL, BANNER, SLIDEOUT, TOAST. Announcements do not accept an animation field. Setting scheduledAt to a future date auto-sets status to SCHEDULED; a past or absent scheduledAt results in PUBLISHED.

Self-Help Widget

{
  "name": "Help Center",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "config": { "position": "bottom-right" },
  "items": {},
  "audienceId": "aud_xyz"
}

Response — 201 Created

{
  "data": {
    "id": "ct_new123",
    "name": "Feature Highlight",
    "siteId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "DRAFT",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
}

Trigger Configuration

Tooltips, beacons, surveys, and announcements accept an optional triggerConfig object whose type is one of:

type	Required fields
exit_intent	optional url
scroll_depth	optional url, percentage (0–100)
time_on_page	optional url, delay (ms)
side_button	optional buttonColor, buttonPosition (left/right)
url_match	required pattern; optional matchType
manual	—

Get Content

GET /api/content/:type/:id

Returns full details for a single content item.

Update Content

PATCH /api/content/:type/:id

Partial update of a content item — only provided fields are modified.

Publish / Unpublish

POST /api/content/:type/:id/publish
POST /api/content/:type/:id/unpublish

Transitions the item between DRAFT and PUBLISHED.

Archive Content

DELETE /api/content/:type/:id

Archives a content item (soft delete). Archived items are no longer served to the SDK.

Restore Content

POST /api/content/:type/:id/restore

Restores a previously archived content item back to DRAFT status.

List Survey Responses

GET /api/content/surveys/:id/responses

Returns paginated responses submitted for a specific survey.

Response

{
  "data": [
    {
      "id": "resp_abc",
      "surveyId": "survey_123",
      "endUserId": "eu_456",
      "response": { "q1": "Very useful" },
      "submittedAt": "2026-01-20T09:15:00Z",
      "tenantId": "t_789"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Content Statuses

All content types share the same lifecycle statuses (the ContentStatus enum):

Status	Description
DRAFT	Initial state, not visible to end users
SCHEDULED	Has a future scheduledAt date
PUBLISHED	Active and served to matching audiences via the SDK
ARCHIVED	Soft-deleted, can be restored