Get Available Apps

get/v1/apps/available

Requires any one of these rolesAbout roles

org.permission.apps.read

Legacyorg.user.apps.readorg.admin.apps.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Fetches all apps available for installation.

About this resource

Apps

An app is a packaged integration, described in one JSON app definition, that adds custom objects, views, workflows, hooks and settings to a Kustomer org. These endpoints list the app versions your org can install and the apps it has installed, along with the state of every component each install created.

Admins find apps in Settings › Apps › App Directory, where they install, configure and update them. Behind each listing is an app definition that a developer registered as a numbered version. Installing a version creates its components in the org: Klasses, KViews, hooks, triggers, actions, workflows and so on. The org keeps running that version until an admin installs a newer one. Registering and installing are covered in Register and install; the endpoints on this page read the results.

Available apps and installed apps

The API has two views of an app:

View	What it is
Available app	One registered version of a definition. `GET /v1/apps/available` lists every version your org may install, both your own private apps and public ones.
Installed app	The record of an app in your org: which `version` is installed, its overall `status` and `statusAt`, and what happened to each component.

An available app carries the listing details (title, description, iconUrl, visibility) and the components as registered (klasses, hooks, triggers, actions, workflows, cards), plus dependencies on other apps. system is true for apps Kustomer provides itself, and you can filter on it with system=true or false. Use fields to return only the attributes you need, since full definitions can be large.

Component state

An installed app groups its components by type (actions, cards, hooks, klasses, triggers, workflows). Each one is keyed by component name and holds a status (such as success), a statusAt timestamp and the id of the object the install created in your org. Use that id to find, for example, the workflow an app installed, so you can open it with the workflows API.

App version IDs

Endpoints that take {appVersion} expect <app>-<version>, such as kustomer-0.1.0. On GET /v1/apps/{appVersion} you can also pass just <app> to get the version that is currently installed. Private apps are registered with your org ID appended to their name (acme_orders becomes acme_orders_<orgId>), so read the final name from the API rather than building it yourself.

Which endpoint to use

To	Call
Browse the app versions your org can install	`GET /v1/apps/available`
Read one registered version, including its full definition	`GET /v1/apps/available/{appVersion}`
List the apps installed in your org	`GET /v1/apps`
Check which version of an app is installed and how each component fared	`GET /v1/apps/{appVersion}`

These read endpoints accept the apps read roles, so agents' and admins' keys can both call them. Registering and installing apps needs a key with the org.admin.apps role. List endpoints are paginated with page and pageSize.

Query parameters

pageinteger

Page number to return.

Example 1

pageSizeinteger

Number of records to return per page.

Example 100

fieldsstring

Comma-separated available app fields to include.

Example "appDetails,tags,url"

systemboolean

Filter available apps by system-app status.

Example false

Responses

objectrequired

array<object>required

Open in the API console

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

{
  "meta": {
    "pageSize": 100,
    "page": 1
  },
  "data": [
    {
      "type": "available_app",
      "id": "chat-0.1.0",
      "attributes": {
        "name": "chat",
        "version": "0.1.0",
        "visibility": "public",
        "dependencies": [
          "kustomer-0.1.0"
        ],
        "default": true,
        "system": true,
        "title": "Chat",
        "iconUrl": "https://cdn.kustomerapp.com/chat/images/icon.png",
        "vendor": "Kustomer",
        "description": "Send & Receive Chat Messages",
        "screenshots": [],
        "website": "https://kustomer.com/",
        "actions": [],
        "cards": [],
        "hooks": [],
        "klasses": [],
        "triggers": [
          {
            "eventName": "kustomer.app.chat.message.receive",
            "outputTemplate": {
              "id": "/#data.id",
              "trackingId": "/#data.attributes.trackingId",
              "body": "/#data.attributes.body",
              "sentAt": "/#data.attributes.createdAt",
              "size": "/#data.attributes.body.length",
              "customer": "/#data.relationships.customer.data.id",
              "session": "/#data.relationships.session.data.id",
              "links": "/#data.links"
            },
            "outputSchema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "trackingId": {
                  "type": "string"
                },
                "body": {
                  "type": "string"
                },
                "sentAt": {
                  "type": "string"
                },
                "size": {
                  "type": "number"
                },
                "customer": {
                  "type": "string"
                },
                "conversation": {
                  "type": "string"
                },
                "links": {
                  "type": "object"
                }
              }
            }
          }
        ],
        "workflows": [
          {
            "name": "chat-message-receive",
            "description": "Create a message when a chat message is received.",
            "trigger": {
              "transitions": [
                {
                  "condition": {
                    "values": [
                      true
                    ],
                    "op": "true"
                  },
                  "target": "create-message"
                }
              ],
              "appVersion": "chat-0.1.0",
              "id": "chat-message",
              "eventName": "kustomer.app.chat.message.receive"
            },
            "steps": [
              {
                "params": {
                  "related": "/#steps.chat-message.links.self",
                  "size": "/#steps.chat-message.size",
                  "body": "/#steps.chat-message.body",
                  "sentAt": "/#steps.chat-message.sentAt",
                  "app": "chat",
                  "channel": "chat",
                  "id": "/#steps.chat-message.id",
                  "customer": "/#steps.chat-message.customer",
                  "conversation": "/#steps.chat-message.session",
                  "meta": {
                    "trackingId": "/#steps.chat-message.trackingId"
                  }
                },
                "appVersion": "kustomer-0.1.0",
                "action": "kustomer.message.create",
                "id": "create-message",
                "transitions": []
              }
            ]
          }
        ],
        "createdAt": "2016-11-14T22:32:44.079Z",
        "updatedAt": "2016-11-14T22:32:44.079Z"
      },
      "links": {
        "self": "/v1/apps/available/chat-0.1.0"
      }
    }
  ]
}