---
title: "Widgets"
description: "Widgets"
url: "https://www.contentstack.com/docs/developers/apis/lytics-api/widgets"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-20"
---

# Widgets

## Get widgets

### Get widgets

**GET** `/v2/widget`

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

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.
- **latest** (optional)
  Return only the latest version of each widget

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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

### Create widget

**POST** `/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.

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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

### Get widget

**GET** `/v2/widget/{id}`

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

#### URL Parameters

- **id** (required)
  The widget id

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.
- **latest** (optional)
  Return only the latest version of the widget

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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

### Update widget

**PUT** `/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.

#### URL Parameters

- **id** (required)
  The widget id

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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

### Delete widget

**DELETE** `/v2/widget/{id}`

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

#### URL Parameters

- **id** (required)
  The widget id

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {},
  "request_id": "string",
  "status": 0
}
```

## Get widget version

### Get widget version

**GET** `/v2/widget/{id}/{version}`

Get a specific version of a widget.

#### URL Parameters

- **id** (required)
  The widget id
- **version** (required)
  The widget version

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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

### Delete widget version

**DELETE** `/v2/widget/{id}/{version}`

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

#### URL Parameters

- **id** (required)
  The widget id
- **version** (required)
  The widget version

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_meta": {},
  "data": {},
  "request_id": "string",
  "status": 0
}
```

## Pause widget version

### Pause widget version

**POST** `/v2/widget/{id}/{version}/pause`

Pause a published widget version.

#### URL Parameters

- **id** (required)
  The widget id
- **version** (required)
  The widget version

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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

### Publish widget version

**POST** `/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.

#### URL Parameters

- **id** (required)
  The widget id
- **version** (required)
  The widget version

#### Query Parameters

- **account_id** (optional)
  The account ID. Defaults to the user's default account.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "_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
}
```