# Get KViews

> GET /v1/kviews · Apps platform API

Source: https://developer.kustomer.com/api/apps-platform/get-kviews

```http
GET https://{orgname}.api.kustomerapp.com/v1/kviews
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.kview.read`; or legacy `org.user.kview.read`, `org.admin.kview.read`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Retrieves all the KViews for a resource.

Optionally, the context can be included to be more specific.

If the context is included, the KViews will be ordered according to when the KView was added or the order specified in the KView ordering endpoint.

## About KViews

A KView (Klass View) is a view template that Kustomer renders in the agent desktop for one type of record, such as a card in the insights panel or the body of a custom object in the timeline. These endpoints read the KViews in your org, edit them and set the order they appear in.

KViews control how records look to agents. Each KView belongs to one `resource` (`customer`, `company`, `conversation`, or a custom object type written as `kobject.<klass>`) and renders in one `context`. Admins build them in Kustomer's KView editor, and apps install them from the `kviews` section of an [app definition](https://developer.kustomer.com/docs/apps/kviews). Through this API you can read, edit, enable or disable, and reorder existing KViews; creating them happens in the editor or through an app.

#### Contexts

| `context` | Where it renders |
| --- | --- |
| `smartbar-card` | A card in the insights panel to the right of the timeline |
| `smartbar-details` | The details panel at the top of the insights panel |
| `expanded-timeline` | The body of a custom object when an agent expands it in the timeline |

`meta.displayName` is the card's title and `meta.icon` its header icon. `enabled` turns a KView on or off without deleting it.

#### Code and visual KViews

A KView is stored in one of two forms. When `advanced` is `true`, `template` holds JSX source that Kustomer evaluates in the browser, with access to the record, lodash, Moment.js and Kustomer's UI components; the [KViews guide](https://developer.kustomer.com/docs/apps/kviews#write-the-template) describes what's in scope. Otherwise the view was built in the visual editor and is stored as `layout`, a tree of `row`, `column` and `component` nodes, plus `components`, which maps each component ID to its `componentType` and `componentAttributes`. Editing `template` through the API is straightforward; leave `layout` and `components` to the editor.

#### Order and app-installed views

When several KViews share a resource and context, such as many cards on conversations, they appear in the order set by `PUT /v1/kviews/{resource}/{context}/order`. Send `kviews` as the full list of KView IDs in the order you want, up to 200. `GET /v1/kviews/{resource}` with a `context` returns views in that order. KViews installed by an app are hidden while the app is disabled, and the `appDisabled` filter lets you include or exclude them.

#### Which endpoint to use

| To | Call |
| --- | --- |
| List every KView in the org | [`GET /v1/kviews`](https://developer.kustomer.com/api/apps-platform/get-kviews) |
| List the KViews for one resource, optionally one context, in display order | [`GET /v1/kviews/{resource}`](https://developer.kustomer.com/api/apps-platform/get-kviews-by-resource) |
| Edit a KView's template, title or icon, or enable or disable it | [`PUT /v1/kviews/{resource}/{id}`](https://developer.kustomer.com/api/apps-platform/update-kview) |
| Reorder the KViews in one resource and context | [`PUT /v1/kviews/{resource}/{context}/order`](https://developer.kustomer.com/api/apps-platform/update-kviews-order) |

Reading KViews works with agent or admin read roles; editing and reordering need a KView write role. A change applies to every agent as soon as it's saved, so try template edits in a sandbox org first and keep a copy of the previous `template` before you overwrite it. For KViews that belong to an app, change the app definition instead: an upgrade to a version where the KView changed updates it from the definition.

Related: [KViews guide](https://developer.kustomer.com/docs/apps/kviews), [Klasses](https://developer.kustomer.com/docs/apps/klasses), [Apps](https://developer.kustomer.com/api/apps-platform#apps), [Cards](https://developer.kustomer.com/api/apps-platform#cards)

### Recipes

#### 1. Update a code KView's template with a backup

Deploy a new version of a code KView's JSX from source control, keeping the previous template so you can roll back.

**Step 1.** [`GET /v1/kviews/{resource}`](https://developer.kustomer.com/api/apps-platform/get-kviews-by-resource.md). List the KViews for the record type and context, and pick yours by `meta.displayName`. Check that `advanced` is `true`, which means it renders from `template`. Save the current `template` before you change anything.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/kviews/conversation?context=smartbar-card" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/kviews/conversation --query context=smartbar-card \
  | jq '.data[] | select(.attributes.meta.displayName == "Order details")' > kview-backup.json
KVIEW_ID=$(jq -r '.id' kview-backup.json)
```

**Step 2.** [`PUT /v1/kviews/{resource}/{id}`](https://developer.kustomer.com/api/apps-platform/update-kview.md). Send the new `template`. Build the body with jq so the JSX is escaped correctly. The change applies to every agent as soon as it's saved, so try it in a sandbox org first.

```bash title="cURL"
jq -n --rawfile t order-card.jsx '{template: $t}' > body.json
curl --request PUT "https://api.kustomerapp.com/v1/kviews/conversation/$KVIEW_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @body.json
```

```bash title="kusty"
jq -n --rawfile t order-card.jsx '{template: $t}' > body.json
kusty api PUT /v1/kviews/conversation/$KVIEW_ID --data @body.json
```

**Step 3.** [`PUT /v1/kviews/{resource}/{id}`](https://developer.kustomer.com/api/apps-platform/update-kview.md). To roll back, send the saved `template` the same way.

```bash title="cURL"
jq '{template: .attributes.template}' kview-backup.json > rollback.json
curl --request PUT "https://api.kustomerapp.com/v1/kviews/conversation/$KVIEW_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data @rollback.json
```

```bash title="kusty"
jq '{template: .attributes.template}' kview-backup.json > rollback.json
kusty api PUT /v1/kviews/conversation/$KVIEW_ID --data @rollback.json
```

> If the KView was installed by an app, change the app definition instead; see [KViews](https://developer.kustomer.com/docs/apps/kviews). The [KViews guide](https://developer.kustomer.com/docs/apps/kviews#write-the-template) lists what a template can use.

#### 2. Move a card to the top of the insights panel

Change the order of the cards agents see on a record type, for example to put your order card above the others on conversations.

**Step 1.** [`GET /v1/kviews/{resource}`](https://developer.kustomer.com/api/apps-platform/get-kviews-by-resource.md). List the cards for the record type with `context=smartbar-card`. With a `context`, the results come back in their current display order. Note each KView's `id`.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/kviews/conversation?context=smartbar-card&pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/kviews/conversation --query context=smartbar-card --query pageSize=100 \
  | jq -c --arg id "$KVIEW_ID" '[$id] + ([.data[].id] - [$id])' > order.json
```

**Step 2.** [`PUT /v1/kviews/{resource}/{context}/order`](https://developer.kustomer.com/api/apps-platform/update-kviews-order.md). Send `kviews` as the complete list of IDs in the new order, up to 200. Include every KView in that resource and context, not just the one you're moving.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/kviews/conversation/smartbar-card/order" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"kviews\": $(cat order.json)}"
```

```bash title="kusty"
kusty api PUT /v1/kviews/conversation/smartbar-card/order --field "kviews:=$(cat order.json)"
```

#### 3. Audit and switch off KViews across the org

List every KView with where it renders and whether it's on, then disable the ones you don't want agents to see.

**Step 1.** [`GET /v1/kviews`](https://developer.kustomer.com/api/apps-platform/get-kviews.md). Page through every KView in the org. `resource` and `context` say where each one renders, `meta.displayName` is its title and `enabled` whether agents see it.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/kviews?pageSize=100" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/kviews --all \
  | jq -r '.data | [.id, .attributes.resource, .attributes.context, .attributes.meta.displayName, .attributes.enabled] | @tsv'
```

**Step 2.** [`PUT /v1/kviews/{resource}/{id}`](https://developer.kustomer.com/api/apps-platform/update-kview.md). Set `enabled` to `false` on the ones to hide. The KView is kept, so you can turn it back on with `enabled: true`.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/kviews/$RESOURCE/$KVIEW_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"enabled": false}'
```

```bash title="kusty"
kusty api PUT /v1/kviews/$RESOURCE/$KVIEW_ID --field enabled:=false
```

### Example object

A real record from [`GET /v1/kviews/{resource}`](https://developer.kustomer.com/api/apps-platform/get-kviews-by-resource.md):

```json
{
  "id": "5e3b04994c62c800ae798cb7",
  "type": "kview",
  "attributes": {
    "resource": "conversation",
    "template": "<p>1</p>",
    "context": "smartbar-card",
    "enabled": true,
    "advanced": false,
    "layout": [],
    "components": {},
    "meta": {
      "icon": "access-point-network",
      "displayName": "conversation card 1"
    },
    "createdAt": "2020-02-05T18:08:25.150Z",
    "modifiedAt": "2020-02-05T18:08:32.299Z",
    "updatedAt": "2020-02-05T18:08:32.299Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/5e383b851046e4001a31200c"
      },
      "data": {
        "type": "org",
        "id": "5e383b851046e4001a31200c"
      }
    },
    "createdBy": {
      "links": {
        "self": "/v1/users/5e383b9e1046e4001a312012"
      },
      "data": {
        "type": "user",
        "id": "5e383b9e1046e4001a312012"
      }
    },
    "modifiedBy": {
      "links": {
        "self": "/v1/users/5e383b9e1046e4001a312012"
      },
      "data": {
        "type": "user",
        "id": "5e383b9e1046e4001a312012"
      }
    }
  }
}
```

Fields:

- `id` (string): The KView ID. Edit it with `PUT /v1/kviews/{resource}/{id}` and list it in `PUT /v1/kviews/{resource}/{context}/order`.
- `attributes.resource` (string): The type of record the KView renders: `customer`, `company`, `conversation`, or `kobject.<klass>` for a custom object. It's also the `{resource}` in the KView paths.
- `attributes.template` (string): For code KViews (`advanced` is `true`), the JSX source Kustomer evaluates in the agent's browser. Save a copy before you overwrite it with `PUT`.
- `attributes.context` (string): Where the KView renders: `smartbar-card` (a card in the insights panel), `smartbar-details` (the details panel) or `expanded-timeline` (the body of an expanded custom object).
- `attributes.enabled` (boolean): Turns the KView on or off for every agent without deleting it.
- `attributes.advanced` (boolean): `true` for a code KView that renders `template`; `false` for one built in the visual editor and stored as `layout` and `components`.
- `attributes.layout` (array): For visual KViews, a tree of `row`, `column` and `component` nodes. Leave it to the KView editor rather than writing it through the API.
- `attributes.components` (object): For visual KViews, maps each component ID used in `layout` to its `componentType` and `componentAttributes`.
- `attributes.meta.icon` (string): The icon in the card's header, a Material Design Icons name.
- `attributes.meta.displayName` (string): The title agents see on the card.
- `attributes.modifiedAt` (string): When a user last changed the KView. `relationships.modifiedBy` says who.

### Permissions

Fewest roles for a read-only integration: `org.permission.kview.read`. For every endpoint: `org.permission.kview.read`, `org.permission.kview.update`.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | no | Page number to return. |
| `pageSize` | integer | no | Number of records to return per page. |
| `appDisabled` | boolean | no | Filter app-installed resources by app-disabled status. |

## Responses

### 200

OK

- `meta` (object, required)
  - `pageSize` (integer, required)
  - `page` (integer, required)
- `links` (object, required)
  - `self` (string, required)
  - `first` (string, required)
  - `prev` (string, required, nullable)
  - `next` (string, required)
- `data` (array<object>, required)
  - `id` (string, required)
  - `type` (string, required)
  - `attributes` (object, required)
    - `resource` (string, required)
    - `template` (string, required)
    - `context` (string, required)
    - `meta` (object, required)
    - `enabled` (boolean, required)
    - `advanced` (boolean, required)
    - `layout` (array<any>, required)
    - `components` (object, required)
    - `createdAt` (string, required)
    - `modifiedAt` (string, required)
    - `updatedAt` (string, required)
  - `relationships` (object, required)
    - `org` (object, required)
    - `createdBy` (object, required)
    - `modifiedBy` (object, required)

```json
{
  "meta": {
    "pageSize": 100,
    "page": 1
  },
  "links": {
    "self": "/v1/kviews?pageSize=2&page=1",
    "first": "/v1/kviews?pageSize=2&page=1",
    "prev": null,
    "next": "/v1/kviews?pageSize=2&page=2"
  },
  "data": [
    {
      "id": "5e74d6eea3334c0041edc3a6",
      "type": "kview",
      "attributes": {
        "resource": "company",
        "template": "<p>template</p>",
        "context": "smartbar-card",
        "meta": {
          "displayName": "Company",
          "icon": "access-point-network-off"
        },
        "enabled": true,
        "advanced": true,
        "layout": [],
        "components": {},
        "createdAt": "2020-03-20T14:45:02.423Z",
        "modifiedAt": "2020-03-20T17:38:11.463Z",
        "updatedAt": "2020-03-20T17:38:11.463Z"
      },
      "relationships": {
        "org": {
          "links": {
            "self": "/v1/orgs/5e15fa33623f88001a8e0bb5"
          },
          "data": {
            "type": "org",
            "id": "5e15fa33623f88001a8e0bb5"
          }
        },
        "createdBy": {
          "links": {
            "self": "/v1/users/5e15fa45623f88001a8e0bbb"
          },
          "data": {
            "type": "user",
            "id": "5e15fa45623f88001a8e0bbb"
          }
        },
        "modifiedBy": {
          "links": {
            "self": "/v1/users/5e15fa45623f88001a8e0bbb"
          },
          "data": {
            "type": "user",
            "id": "5e15fa45623f88001a8e0bbb"
          }
        }
      }
    },
    {
      "id": "5e74d5195a1fa8001326bca3",
      "type": "kview",
      "attributes": {
        "resource": "company",
        "template": "<p>template</p>",
        "context": "smartbar-details",
        "meta": {
          "displayName": "Details",
          "icon": "access-point-network-off"
        },
        "enabled": true,
        "advanced": true,
        "layout": [],
        "components": {},
        "createdAt": "2020-03-20T14:37:13.185Z",
        "modifiedAt": "2020-03-20T17:38:03.108Z",
        "updatedAt": "2020-03-20T17:38:03.108Z"
      },
      "relationships": {
        "org": {
          "links": {
            "self": "/v1/orgs/5e15fa33623f88001a8e0bb5"
          },
          "data": {
            "type": "org",
            "id": "5e15fa33623f88001a8e0bb5"
          }
        },
        "createdBy": {
          "links": {
            "self": "/v1/users/5e15fa45623f88001a8e0bbb"
          },
          "data": {
            "type": "user",
            "id": "5e15fa45623f88001a8e0bbb"
          }
        },
        "modifiedBy": {
          "links": {
            "self": "/v1/users/5e15fa45623f88001a8e0bbb"
          },
          "data": {
            "type": "user",
            "id": "5e15fa45623f88001a8e0bbb"
          }
        }
      }
    }
  ]
}
```

### 400

Bad Request

### 401

Unauthorized

### 403

Forbidden

## Example request

```bash
curl --request GET \
  --url 'https://api.kustomerapp.com/v1/kviews' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```