List AI automations

get/v1/ai/automations

Requires any one of these rolesAbout roles

org.permission.assistant.read

Legacyorg.user.apps.read

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

Retrieves a paginated list of AI automations (version 0 only).

Note: Automations can only be created or modified through the Kustomer application UI.

About this resource

AI automations

An AI automation is an AI agent built in Kustomer, such as one that answers customers in chat or one that helps your team with their work. The API lists them so you can find an agent's ID, mainly to test it with evaluations; building and editing agents happens in Kustomer.

AI automations are the AI agents your org builds in Kustomer. Each one has instructions, tools it can call, and triggers: the events that start it. These endpoints are read-only: you can't create, edit, turn on or delete an agent through the API. Their main use is finding the automationId you need to create and run evaluations, and listing your agents for an inventory or dashboard.

Key fields

Field	Meaning
`name`, `description`	What the agent is called and what it's for.
`type`	The kind of agent: `customer` for agents that talk to your customers, `rep` for agents that help your team, and also `conversational` or `workflow`.
`machineUserId`	The Kustomer user the agent acts as.
`version`	The agent version. The API returns version `0`, the agent's current draft, which is also the version evaluations test.
`createdAt`, `updatedAt`, `modifiedAt`	When the agent was created and last changed.

Filtering

GET /v1/ai/automations returns only one type at a time, and type defaults to customer, so ask for type=rep (or another type) explicitly to see other agents. name filters by name, and triggers takes a comma-separated list of trigger event names to find the agents that respond to them.

Which endpoint to use

To	Call
List your AI agents of one type	`GET /v1/ai/automations`
Look up one agent by ID	`GET /v1/ai/automations/{automationId}`
List the evaluations that test an agent	`GET /v1/ai/automations/{automationId}/evaluations`

Results are paginated with page and pageSize. These endpoints need the AI Agents feature on your Kustomer plan; without it, they return 403 Forbidden. Reading automations only needs read access to apps or AI agents, so a read-only API key is enough for listing and evaluation scripts.

Query parameters

typestring

Filter by automation type. Defaults to customer.

One ofcustomerrepconversationalworkflowDefault "customer"Example "customer"

namestring

Filter by automation name.

Example "Customer Support Agent"

triggersstring

Filter by comma-separated trigger event names.

Example "kustomer.conversation.create,kustomer.message.create"

pageinteger

Page number for pagination

Default 1Example 1

pageSizeinteger

Number of items per page

Default 100Example 100

Responses

object

array<Automation>

Open in the API console

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

{
  "meta": {
    "page": 1,
    "pageSize": 100
  },
  "links": {
    "self": "/v1/ai/automations?page=1&pageSize=100",
    "first": "/v1/ai/automations?page=1&pageSize=100",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "type": "automation",
      "attributes": {
        "name": "Customer Support Agent",
        "machineUserId": "507f1f77bcf86cd799439099",
        "description": "Handles customer support inquiries",
        "version": 0,
        "type": "customer",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z",
        "modifiedAt": "2024-01-15T10:30:00.000Z"
      },
      "relationships": {
        "org": {
          "links": {
            "self": "/v1/orgs/507f1f77bcf86cd799439010"
          },
          "data": {
            "type": "org",
            "id": "507f1f77bcf86cd799439010"
          }
        },
        "user": {
          "links": {
            "self": "/v1/users/507f1f77bcf86cd799439099"
          },
          "data": {
            "type": "user",
            "id": "507f1f77bcf86cd799439099"
          }
        },
        "modifiedBy": {
          "links": {
            "self": "/v1/users/507f1f77bcf86cd799439099"
          },
          "data": {
            "type": "user",
            "id": "507f1f77bcf86cd799439099"
          }
        }
      },
      "links": {
        "self": "string"
      }
    }
  ]
}