Is AI recommending you? Ask Contentstack Canoe for free
Is AI recommending your brand? Find out with Contentstack Canoe for free
Contentstack.comAcademyLogin
CS-log-dark.svgCS-log-dark.svg
  • Changelog
  • APIs
  • SDKs

Platform

  • Solution Center
  • Marketplace
  • Changelog
  • Developers & IT
  • Business users
  • Digital leaders
  • Developer Fast Track
  • Plans & Pricing

Solutions

  • Retail
  • Travel and tourism
  • Financial services
  • Technology
  • Manufacturing
  • E-commerce
  • Localization
  • Personalization
  • Portals and knowledge bases

Resources

  • Academy
  • Docs
  • Contentstack for Developers
  • Product updates
  • Contentstack on Contentstack
  • Blog
  • Insights and analyst reports
  • The Forrester Wave™: Digital Experience Platforms, Q4 2025
  • Webinars
  • Podcasts
  • Glossary
  • Content generative library
  • Community
  • Headless CMS
  • Composable AXP
  • Personalization
  • CDP

Customers

  • Case Studies
  • Customer Care
  • Contentstack Experience Awards
  • Customer support

Partners

  • Overview
  • Find a partner
  • Login

Company

  • About us
  • News
  • Customer support portal
  • Contact

Social

  • Facebook
  • LinkedIn
  • Instagram
  • GitHub
  • YouTube
  • Discord
  • X
LegalTermsPrivacyTrust Center

Cookie settings

Copyright © 2026 Contentstack Inc. All rights reserved.
/
  1. Home
  2. APIs
  3. Lytics API
  4. Widgets

Widgets

markdownView as Markdown

Get widgets

GEThttps://api.lytics.io/v2/widget

Get all widgets for an account. Each version of each widget is returned unless latest=true.

Sample Response
Status|200 OK
1234567891011121314151617181920212223242526272829303132333435363738
{
  "_meta": {},
  "data": [
    {
      "aid": 0,
      "config": {},
      "created": "2019-08-24T14:15:22Z",
      "custom_rule_function": "string",
      "description": "string",
      "excluded_segment_ids": [
        "string"
      ],
      "id": "string",
      "issues": [
        {
          "code": "segment_not_found",
          "field": "target_segment_ids",
          "message": "string",
          "value": "string"
        }
      ],
      "label": "string",
      "modified": "2019-08-24T14:15:22Z",
      "personalization_key": "string",
      "published_at": "2019-08-24T14:15:22Z",
      "slug": "string",
      "state": "draft",
      "state_modified_at": "2019-08-24T14:15:22Z",
      "target_segment_ids": [
        "string"
      ],
      "version": 0,
      "widget_type": "message"
    }
  ],
  "request_id": "string",
  "status": 0
}

Create widget

POSThttps://api.lytics.io/v2/widget

Create a widget. The server assigns its id and it starts as version 1 in draft; the request must not name an id or version, or a state other than draft.

Sample Request
12345678910111213141516171819202122232425262728293031
{
  "aid": 0,
  "config": {},
  "created": "2019-08-24T14:15:22Z",
  "custom_rule_function": "string",
  "description": "string",
  "excluded_segment_ids": [
    "string"
  ],
  "id": "string",
  "issues": [
    {
      "code": "segment_not_found",
      "field": "target_segment_ids",
      "message": "string",
      "value": "string"
    }
  ],
  "label": "string",
  "modified": "2019-08-24T14:15:22Z",
  "personalization_key": "string",
  "published_at": "2019-08-24T14:15:22Z",
  "slug": "string",
  "state": "draft",
  "state_modified_at": "2019-08-24T14:15:22Z",
  "target_segment_ids": [
    "string"
  ],
  "version": 0,
  "widget_type": "message"
}
Sample Response
Status|201 Created
123456789101112131415161718192021222324252627282930313233343536
{
  "_meta": {},
  "data": {
    "aid": 0,
    "config": {},
    "created": "2019-08-24T14:15:22Z",
    "custom_rule_function": "string",
    "description": "string",
    "excluded_segment_ids": [
      "string"
    ],
    "id": "string",
    "issues": [
      {
        "code": "segment_not_found",
        "field": "target_segment_ids",
        "message": "string",
        "value": "string"
      }
    ],
    "label": "string",
    "modified": "2019-08-24T14:15:22Z",
    "personalization_key": "string",
    "published_at": "2019-08-24T14:15:22Z",
    "slug": "string",
    "state": "draft",
    "state_modified_at": "2019-08-24T14:15:22Z",
    "target_segment_ids": [
      "string"
    ],
    "version": 0,
    "widget_type": "message"
  },
  "request_id": "string",
  "status": 0
}

Get widget

GEThttps://api.lytics.io/v2/widget/{id}

Get every version of a widget, or only the latest with latest=true.

Sample Response
Status|200 OK
1234567891011121314151617181920212223242526272829303132333435363738
{
  "_meta": {},
  "data": [
    {
      "aid": 0,
      "config": {},
      "created": "2019-08-24T14:15:22Z",
      "custom_rule_function": "string",
      "description": "string",
      "excluded_segment_ids": [
        "string"
      ],
      "id": "string",
      "issues": [
        {
          "code": "segment_not_found",
          "field": "target_segment_ids",
          "message": "string",
          "value": "string"
        }
      ],
      "label": "string",
      "modified": "2019-08-24T14:15:22Z",
      "personalization_key": "string",
      "published_at": "2019-08-24T14:15:22Z",
      "slug": "string",
      "state": "draft",
      "state_modified_at": "2019-08-24T14:15:22Z",
      "target_segment_ids": [
        "string"
      ],
      "version": 0,
      "widget_type": "message"
    }
  ],
  "request_id": "string",
  "status": 0
}

Update widget

PUThttps://api.lytics.io/v2/widget/{id}

Update the version named in the body (404 if it does not exist), or create the next draft version when the body names none. State only changes through publish and pause; a body state must match the stored one. A published version's config, type and targeting cannot change until it is paused.

Sample Request
12345678910111213141516171819202122232425262728293031
{
  "aid": 0,
  "config": {},
  "created": "2019-08-24T14:15:22Z",
  "custom_rule_function": "string",
  "description": "string",
  "excluded_segment_ids": [
    "string"
  ],
  "id": "string",
  "issues": [
    {
      "code": "segment_not_found",
      "field": "target_segment_ids",
      "message": "string",
      "value": "string"
    }
  ],
  "label": "string",
  "modified": "2019-08-24T14:15:22Z",
  "personalization_key": "string",
  "published_at": "2019-08-24T14:15:22Z",
  "slug": "string",
  "state": "draft",
  "state_modified_at": "2019-08-24T14:15:22Z",
  "target_segment_ids": [
    "string"
  ],
  "version": 0,
  "widget_type": "message"
}
Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536
{
  "_meta": {},
  "data": {
    "aid": 0,
    "config": {},
    "created": "2019-08-24T14:15:22Z",
    "custom_rule_function": "string",
    "description": "string",
    "excluded_segment_ids": [
      "string"
    ],
    "id": "string",
    "issues": [
      {
        "code": "segment_not_found",
        "field": "target_segment_ids",
        "message": "string",
        "value": "string"
      }
    ],
    "label": "string",
    "modified": "2019-08-24T14:15:22Z",
    "personalization_key": "string",
    "published_at": "2019-08-24T14:15:22Z",
    "slug": "string",
    "state": "draft",
    "state_modified_at": "2019-08-24T14:15:22Z",
    "target_segment_ids": [
      "string"
    ],
    "version": 0,
    "widget_type": "message"
  },
  "request_id": "string",
  "status": 0
}

Delete widget

DELETEhttps://api.lytics.io/v2/widget/{id}

Delete every version of a widget. Refused with 409 while any version is published.

Sample Response
Status|200 OK
123456
{
  "_meta": {},
  "data": {},
  "request_id": "string",
  "status": 0
}

Get widget version

GEThttps://api.lytics.io/v2/widget/{id}/{version}

Get a specific version of a widget.

Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536
{
  "_meta": {},
  "data": {
    "aid": 0,
    "config": {},
    "created": "2019-08-24T14:15:22Z",
    "custom_rule_function": "string",
    "description": "string",
    "excluded_segment_ids": [
      "string"
    ],
    "id": "string",
    "issues": [
      {
        "code": "segment_not_found",
        "field": "target_segment_ids",
        "message": "string",
        "value": "string"
      }
    ],
    "label": "string",
    "modified": "2019-08-24T14:15:22Z",
    "personalization_key": "string",
    "published_at": "2019-08-24T14:15:22Z",
    "slug": "string",
    "state": "draft",
    "state_modified_at": "2019-08-24T14:15:22Z",
    "target_segment_ids": [
      "string"
    ],
    "version": 0,
    "widget_type": "message"
  },
  "request_id": "string",
  "status": 0
}

Delete widget version

DELETEhttps://api.lytics.io/v2/widget/{id}/{version}

Delete one version of a widget. Refused with 409 while that version is published.

Sample Response
Status|200 OK
123456
{
  "_meta": {},
  "data": {},
  "request_id": "string",
  "status": 0
}

Pause widget version

POSThttps://api.lytics.io/v2/widget/{id}/{version}/pause

Pause a published widget version.

Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536
{
  "_meta": {},
  "data": {
    "aid": 0,
    "config": {},
    "created": "2019-08-24T14:15:22Z",
    "custom_rule_function": "string",
    "description": "string",
    "excluded_segment_ids": [
      "string"
    ],
    "id": "string",
    "issues": [
      {
        "code": "segment_not_found",
        "field": "target_segment_ids",
        "message": "string",
        "value": "string"
      }
    ],
    "label": "string",
    "modified": "2019-08-24T14:15:22Z",
    "personalization_key": "string",
    "published_at": "2019-08-24T14:15:22Z",
    "slug": "string",
    "state": "draft",
    "state_modified_at": "2019-08-24T14:15:22Z",
    "target_segment_ids": [
      "string"
    ],
    "version": 0,
    "widget_type": "message"
  },
  "request_id": "string",
  "status": 0
}

Publish widget version

POSThttps://api.lytics.io/v2/widget/{id}/{version}/publish

Publish a widget version. Refused with 409 while another version is published; that version must be paused first. Refused with 400 while the version has issues; the response's data.issues lists them.

Sample Response
Status|200 OK
123456789101112131415161718192021222324252627282930313233343536
{
  "_meta": {},
  "data": {
    "aid": 0,
    "config": {},
    "created": "2019-08-24T14:15:22Z",
    "custom_rule_function": "string",
    "description": "string",
    "excluded_segment_ids": [
      "string"
    ],
    "id": "string",
    "issues": [
      {
        "code": "segment_not_found",
        "field": "target_segment_ids",
        "message": "string",
        "value": "string"
      }
    ],
    "label": "string",
    "modified": "2019-08-24T14:15:22Z",
    "personalization_key": "string",
    "published_at": "2019-08-24T14:15:22Z",
    "slug": "string",
    "state": "draft",
    "state_modified_at": "2019-08-24T14:15:22Z",
    "target_segment_ids": [
      "string"
    ],
    "version": 0,
    "widget_type": "message"
  },
  "request_id": "string",
  "status": 0
}
Hide Parameters

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

latestoptionalstring

Return only the latest version of each widget

Headers

Authorizationoptionalstring

Hide Parameters

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring

Body Parameters

aidoptionalinteger
configoptionalobject

Raw Pathfora SDK config

createdoptionalstring (date-time)
custom_rule_functionoptionalstring
descriptionoptionalstring
excluded_segment_idsoptionalstring[]
idoptionalstring
issuesoptionalobject[]

Every reason this version cannot be served, computed per request; empty

when it can. Any issue refuses publish and keeps a published version off

the tag. Omitted only when it could not be checked.

issues[].codeoptionalstring

One of: segment_not_found, segment_invalid, segment_no_slug, segment_not_public, invalid_config, invalid_callback, invalid_custom_rule, invalid_widget_type

issues[].fieldoptionalstring

One of: target_segment_ids, excluded_segment_ids, config, custom_rule_function, widget_type

issues[].messageoptionalstring
issues[].valueoptionalstring

the segment id, or the config key of a bad callback

labeloptionalstring
modifiedoptionalstring (date-time)
personalization_keyoptionalstring
published_atoptionalstring (date-time)
slugoptionalstring
stateoptionalstring

One of: draft, published, paused, deleted

state_modified_atoptionalstring (date-time)
target_segment_idsoptionalstring[]
versionoptionalinteger
widget_typeoptionalstring

One of: message, form, sitegate

Hide Parameters

URL Parameters

idrequiredstring

The widget id

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

latestoptionalstring

Return only the latest version of the widget

Headers

Authorizationoptionalstring

Hide Parameters

URL Parameters

idrequiredstring

The widget id

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring

Body Parameters

aidoptionalinteger
configoptionalobject

Raw Pathfora SDK config

createdoptionalstring (date-time)
custom_rule_functionoptionalstring
descriptionoptionalstring
excluded_segment_idsoptionalstring[]
idoptionalstring
issuesoptionalobject[]

Every reason this version cannot be served, computed per request; empty

when it can. Any issue refuses publish and keeps a published version off

the tag. Omitted only when it could not be checked.

issues[].codeoptionalstring

One of: segment_not_found, segment_invalid, segment_no_slug, segment_not_public, invalid_config, invalid_callback, invalid_custom_rule, invalid_widget_type

issues[].fieldoptionalstring

One of: target_segment_ids, excluded_segment_ids, config, custom_rule_function, widget_type

issues[].messageoptionalstring
issues[].valueoptionalstring

the segment id, or the config key of a bad callback

labeloptionalstring
modifiedoptionalstring (date-time)
personalization_keyoptionalstring
published_atoptionalstring (date-time)
slugoptionalstring
stateoptionalstring

One of: draft, published, paused, deleted

state_modified_atoptionalstring (date-time)
target_segment_idsoptionalstring[]
versionoptionalinteger
widget_typeoptionalstring

One of: message, form, sitegate

Hide Parameters

URL Parameters

idrequiredstring

The widget id

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring

Hide Parameters

URL Parameters

idrequiredstring

The widget id

versionrequiredstring

The widget version

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring

Hide Parameters

URL Parameters

idrequiredstring

The widget id

versionrequiredstring

The widget version

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring

Hide Parameters

URL Parameters

idrequiredstring

The widget id

versionrequiredstring

The widget version

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring

Hide Parameters

URL Parameters

idrequiredstring

The widget id

versionrequiredstring

The widget version

Query Parameters

account_idoptionalstring

The account ID. Defaults to the user's default account.

Headers

Authorizationoptionalstring