Skip to main content
API docs by Redocly

Produktly API (1.0.0)

Download OpenAPI specification:Download

The Produktly REST API gives you programmatic access to your product tours, checklists, smart tips, announcements, micro surveys, changelogs, roadmaps, feedback widgets, NPS widgets, tags, analytics, and identified users. It exposes the same functionality as the MCP server, over plain HTTP.

Base URL

https://api.produktly.com/api/v1

Authentication

All endpoints (except GET /openapi.json) require an API key passed as a Bearer token.

  1. Sign in to Produktly and open Settings → API keys.
  2. Generate a new key and copy it. The same key works for both REST and MCP.
  3. Send it on every request:
GET /api/v1/changelogs HTTP/1.1
Host: api.produktly.com
Authorization: Bearer <your-api-key>

Missing or invalid keys return 401 unauthorized. Treat the key like a password — anyone with it can read and write your Produktly data.

Response format

List endpoints return an envelope with a data array and pagination metadata:

{
  "data": [ { "id": 1, "name": "..." } ],
  "pagination": { "total": 42, "limit": 50, "offset": 0 }
}

Single-resource endpoints (e.g. GET /roadmaps/{id}) return the resource directly, no envelope.

Pagination

List endpoints accept limit (default 50, max 100) and offset (default 0) query parameters. Date filters (startDate, endDate) compose with pagination where supported.

Errors

Errors come back in a consistent shape:

{
  "error": {
    "code": "invalid_tag_names",
    "message": "Unknown tag names: foo. Use GET /v1/tags to see available tags.",
    "details": { "missing": ["foo"] }
  }
}

Common codes:

  • unauthorized (401) — missing or invalid API key
  • not_found (404) — resource doesn't exist or doesn't belong to your company
  • validation_error (400) — invalid request parameters
  • rate_limit_exceeded (429) — see Rate limits below
  • internal_error (500) — server-side problem; safe to retry

Rate limits

Every API key is limited to 60 requests per minute. The /users endpoints have a separate bucket of 300 requests per minute to support backend syncs. Every response includes:

  • X-RateLimit-Limit: total allowed in the window
  • X-RateLimit-Remaining: remaining quota
  • X-RateLimit-Reset: Unix seconds when the bucket refills

When you exceed the limit you'll get 429 rate_limit_exceeded with a Retry-After header. Back off and retry.

Changelogs

List changelogs

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

List posts in a changelog

Authorizations:
BearerAuth
path Parameters
changelogId
required
integer > 0
query Parameters
limit
integer ( 0 .. 100 ]
Default: 50
offset
integer or null >= 0
Default: 0
startDate
string
endDate
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a changelog post

Authorizations:
BearerAuth
path Parameters
changelogId
required
integer > 0
Request Body schema: application/json
title
required
string non-empty
description
string
date
string
active
boolean
tagNames
Array of strings

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "date": "string",
  • "active": true,
  • "tagNames": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "description": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "active": true,
  • "tags": [
    ]
}

Update a changelog post

Authorizations:
BearerAuth
path Parameters
changelogId
required
integer > 0
postId
required
integer > 0
Request Body schema: application/json
title
string
description
string
date
string
active
boolean
tagNames
Array of strings

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "date": "string",
  • "active": true,
  • "tagNames": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "description": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "active": true,
  • "tags": [
    ]
}

Feedback Widgets

List feedback widgets

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a feedback widget

Creates the widget as a draft. Pass active: true to publish immediately — the widget must have at least one option and targeting set, otherwise it stays a draft and the response note explains why. Supply options directly or use optionsPreset for a built-in set. The response includes a dashboardUrl for reviewing the widget in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty
Array of objects

The answer options users pick from

optionsPreset
integer [ 1 .. 6 ]

Use a built-in option set instead of listing options: 1 issue/idea/other, 2 three emojis, 3 five emojis, 4 four emojis, 5 feelings, 6 issue/idea/happy/angry/other

object
object or object or object
themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. Needs at least one option and targeting

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "options": [
    ],
  • "optionsPreset": 1,
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "options": [
    ],
  • "dashboardUrl": "string",
  • "note": "string"
}

List feedback responses

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0
query Parameters
limit
integer ( 0 .. 100 ]
Default: 50
offset
integer or null >= 0
Default: 0
startDate
string
endDate
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a feedback widget

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "options": [
    ],
  • "dashboardUrl": "string",
  • "note": "string"
}

Update a feedback widget

Only the fields you send are changed. settings are merged over stored settings; targeting and options (whether passed directly or via optionsPreset) replace wholesale. Live widgets can be edited, but an update that would leave one unpublishable (no options or no targeting) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0
Request Body schema: application/json
name
string non-empty
Array of objects

Replaces all options

optionsPreset
integer [ 1 .. 6 ]
object

Merged over existing settings

object or object or object
themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "options": [
    ],
  • "optionsPreset": 1,
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "options": [
    ],
  • "dashboardUrl": "string",
  • "note": "string"
}

Roadmaps

List roadmaps

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get roadmap with sections and items

Authorizations:
BearerAuth
path Parameters
roadmapId
required
integer > 0
query Parameters
startDate
string
endDate
string
latestCount
integer ( 0 .. 100 ]
limit
integer ( 0 .. 100 ]
query
string
tagNames
Array of strings

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "publicName": "string",
  • "active": true,
  • "customDomain": "string",
  • "publicId": "string",
  • "sections": [
    ]
}

NPS Widgets

List NPS widgets

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create an NPS widget

Creates the widget as a draft. Pass active: true to publish immediately — the widget must have targeting set, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the widget in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty
object
object or object or object
themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. Needs targeting

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Get NPS score breakdown

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0
query Parameters
startDate
string
endDate
string

Responses

Response samples

Content type
application/json
{
  • "npsScore": 0,
  • "totalResponses": 0,
  • "promoters": {
    },
  • "passives": {
    },
  • "detractors": {
    }
}

List NPS responses

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0
query Parameters
limit
integer ( 0 .. 100 ]
Default: 50
offset
integer or null >= 0
Default: 0
startDate
string
endDate
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get an NPS widget

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Update an NPS widget

Only the fields you send are changed. settings are merged over stored settings; targeting replaces wholesale. Live widgets can be edited, but an update that would leave one unpublishable (no targeting) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
widgetId
required
integer > 0
Request Body schema: application/json
name
string non-empty
object

Merged over existing settings

object or object or object
themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Stats

Widget stats by entity type

Authorizations:
BearerAuth
path Parameters
entityType
required
string
Enum: "tour" "checklist" "smartTip" "announcement" "changelog" "npsWidget" "roadmap"
query Parameters
startDate
string
endDate
string
entityId
integer > 0

Responses

Response samples

Content type
application/json
{
  • "entityType": "string",
  • "period": {
    },
  • "widgets": [
    ]
}

Company-wide stats summary

Authorizations:
BearerAuth
query Parameters
startDate
string
endDate
string

Responses

Response samples

Content type
application/json
{
  • "period": {
    },
  • "previousPeriod": {
    },
  • "features": [
    ]
}

Users

Get an identified user

Returns the user's attributes and timestamps. metadata can be null for users identified client-side without attributes.

Authorizations:
BearerAuth
path Parameters
userId
required
string non-empty
Example: user_123

The user's external ID — the same value you pass to window.Produktly.identifyUser(). URL-encode it.

Responses

Response samples

Content type
application/json
{
  • "userId": "user_123",
  • "metadata": {
    },
  • "createdAt": "2026-07-01T09:00:00.000Z",
  • "updatedAt": "2026-07-15T09:00:00.000Z"
}

Create or replace an identified user

Server-side equivalent of identifyUser() with replace semantics: creates the user if it doesn't exist (201), otherwise replaces its entire metadata object (200). Prefer PATCH for scheduled syncs so you don't clobber attributes set client-side.

Authorizations:
BearerAuth
path Parameters
userId
required
string non-empty
Example: user_123

The user's external ID — the same value you pass to window.Produktly.identifyUser(). URL-encode it.

Request Body schema: application/json
required
object

User attributes as a JSON object (nested values allowed, max 32 KB serialized). Replaces the entire stored metadata object.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "userId": "user_123",
  • "metadata": {
    },
  • "createdAt": "2026-07-01T09:00:00.000Z",
  • "updatedAt": "2026-07-15T09:00:00.000Z"
}

Merge attributes into an identified user

Shallow-merges the given attributes into the user's metadata (RFC 7386 style at the top level): keys overwrite, null removes a key, omitted keys are kept. Creates the user if it doesn't exist (201).

Authorizations:
BearerAuth
path Parameters
userId
required
string non-empty
Example: user_123

The user's external ID — the same value you pass to window.Produktly.identifyUser(). URL-encode it.

Request Body schema: application/json
required
object

Attributes to merge (shallow, top level): keys overwrite, a key set to null is removed, omitted keys are kept, nested objects replace wholesale. Merged result max 32 KB serialized.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "userId": "user_123",
  • "metadata": {
    },
  • "createdAt": "2026-07-01T09:00:00.000Z",
  • "updatedAt": "2026-07-15T09:00:00.000Z"
}

Delete an identified user

Hard-deletes the identified user. Analytics events are kept (they reference the external ID as a plain string).

Authorizations:
BearerAuth
path Parameters
userId
required
string non-empty
Example: user_123

The user's external ID — the same value you pass to window.Produktly.identifyUser(). URL-encode it.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Tags

List tags

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Product Tours

List product tours

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a product tour

Creates the tour as a draft. Pass active: true to publish immediately — the tour must have at least one step and targeting set, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the tour in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty
Array of objects or objects or objects or objects or objects or objects

Tour steps in order. A tour with no steps never shows

object or object or object

Where the tour shows. Omit for an untargeted draft; without targeting the tour can never show

object
themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. The tour needs at least one step and targeting set; otherwise it is saved as a draft and the response note explains why.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "steps": [
    ],
  • "targeting": {
    },
  • "settings": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "steps": [
    ],
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Get a product tour

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "steps": [
    ],
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Update a product tour

Only the fields you send are changed. steps and targeting replace their stored values wholesale — fetch the tour first and send the full array back, preserving step ids. settings are merged. Live tours can be edited, but an update that would leave a live tour unpublishable (no steps or no targeting) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0
Request Body schema: application/json
name
string non-empty
Array of objects or objects or objects or objects or objects or objects

Replaces ALL steps. Fetch the tour first and send back the full array, preserving step ids

object or object or object

Replaces the whole targeting config

object

Merged over existing settings; only provided keys change

themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Set live or back to draft. Publishing requires the widget to be publishable (see the create schema); unpublishing always works.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "steps": [
    ],
  • "targeting": {
    },
  • "settings": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "steps": [
    ],
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Checklists

List checklists

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a checklist

Creates the checklist as a draft. Pass active: true to publish immediately — the checklist must have at least one item and targeting set, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the checklist in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty

Shown as the checklist panel header

Array of objects
object or object or object
object
themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. The checklist needs at least one item and targeting set; otherwise it is saved as a draft and the response note explains why.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "items": [
    ],
  • "targeting": {
    },
  • "settings": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "items": [
    ],
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Get a checklist

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "items": [
    ],
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Update a checklist

Only the fields you send are changed. items and targeting replace their stored values wholesale — fetch the checklist first and send the full array back, preserving item ids (completion state is keyed on them). settings are merged. Live checklists can be edited, but an update that would leave one unpublishable (no items or no targeting) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0
Request Body schema: application/json
name
string non-empty
Array of objects

Replaces ALL items. Fetch first and send back the full array, preserving item ids

object or object or object
object

Merged over existing settings

themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Set live or back to draft. Publishing requires the widget to be publishable (see the create schema); unpublishing always works.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "items": [
    ],
  • "targeting": {
    },
  • "settings": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "items": [
    ],
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Smart Tips

List smart tips

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a smart tip

Creates the tip as a draft. Pass active: true to publish immediately — the tip must have settings.cssSelector and targeting set, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the tip in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty

Internal name

title
string

Card title (plain text)

content
string

Card body as HTML

required
object
object or object or object

Where the tip shows. Without targeting it can never show

themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. Needs settings.cssSelector and targeting; otherwise saved as a draft and the response note explains why

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Get a smart tip

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Update a smart tip

Only the fields you send are changed. settings are merged over stored settings; targeting replaces wholesale. Live tips can be edited, but an update that would leave one unpublishable (no cssSelector or no targeting) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0
Request Body schema: application/json
name
string non-empty
title
string
content
string
object

Merged over existing settings

object or object or object

Replaces the whole targeting config

themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Set live or back to draft

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Announcements

List announcements

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create an announcement

Creates the announcement as a draft. Pass active: true to publish immediately — the announcement must have a title and targeting set, plus content for popup and toast types, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the announcement in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty
title
string

Headline. The only text shown on topbar types

content
string

HTML body. Rendered for popup and toast only

object
object or object or object
themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. Needs a title and targeting, plus content for popup and toast

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Get an announcement

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Update an announcement

Only the fields you send are changed. settings are merged over stored settings; targeting replaces wholesale. Live announcements can be edited, but an update that would leave one unpublishable (no title, no targeting, or missing content for popup/toast) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0
Request Body schema: application/json
name
string non-empty
title
string
content
string
object

Merged over existing settings

object or object or object
themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "title": "string",
  • "content": "string",
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Micro Surveys

List micro surveys

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a micro survey

Creates the survey as a draft. Pass active: true to publish immediately — the survey must have at least one question and targeting set, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the survey in the builder.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string non-empty
required
object
object or object or object
themeId
integer > 0
folderId
integer > 0
active
boolean

Publish immediately. Needs at least one question and targeting

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Get a micro survey

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}

Update a micro survey

Only the fields you send are changed. settings are merged over stored settings; targeting replaces wholesale. Live surveys can be edited, but an update that would leave one unpublishable (no questions or no targeting) returns 400; set active: false first to take it down.

Authorizations:
BearerAuth
path Parameters
id
required
integer > 0
Request Body schema: application/json
name
string non-empty
object

Merged over existing settings

object or object or object
themeId
integer or null > 0
folderId
integer or null > 0
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    },
  • "targeting": {
    },
  • "themeId": 0,
  • "folderId": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "active": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "folderId": 0,
  • "themeId": 0,
  • "settings": {
    },
  • "rules": [
    ],
  • "ruleLogicalOperator": "string",
  • "dashboardUrl": "string",
  • "note": "string"
}