Get procedures

GET

/api/v1/ai/actions

List the procedures (AI actions) configured for the workspace. A procedure is something the AI can do beyond answering, for example call an API, invoke an MCP tool or hand the conversation to a human.

Notes

• Scoped to the workspace in x-website-id; there is no query parameter to widen or narrow it
• documentsTriggeringAction lists the training documents that reference each procedure, so you can see which knowledge triggers it
• Procedures saved before the enabled flag existed are returned as enabled and backfilled on read, so a procedure never comes back without one
• Every procedure in the workspace is validated as one batch, so a single stored procedure holding a value the schema rejects, such as a variable type of number, makes this endpoint answer 502 for the whole workspace rather than skipping that one procedure. The failure lasts as long as the procedure does; fix it with the create or update endpoint

Parameters

Header Parameters

x-api-key

required

string

Your API key from account settings.

x-user-email

required

string

The email address of your user.

x-account-id

required

string

The ID of your account. You can find this in the account settings.

x-website-id

required

string

The ID of the workspace you want to use.

Responses

200

Successful response with the workspace’s procedures.

object

actions

Array<object>

One procedure (AI action) the AI can execute during a conversation. Fields beyond the common ones below depend on command; an api procedure adds the request fields documented under the create or update operation.

object

accountId

string

websiteId

string

actionId

Unique identifier for this procedure.

string

name

Display name, also what the AI refers to when it decides to run the procedure.

string

description

What the procedure does. The AI reads this when deciding whether it applies.

string

nullable

command

What the procedure executes. api calls an HTTP endpoint, mcp invokes an MCP tool, direct-answer supplies a fixed answer, and the rest drive the component. Each command reads its input from arguments.

string

Allowed values: api mcp direct-answer rephrase-and-answer redirect-to-url start-experience start-live-chat execute-custom-javascript switch-segment send-message-to-segment send-message-to-segment-and-switch resend-message-to-segment-and-switch open-image open-video

arguments

The command’s input. What it has to contain depends on command, and a procedure whose arguments is wrong is stored happily but fails when the AI tries to run it. For api and rephrase-and-answer it must be the procedure’s own actionId. For mcp it is the MCP tool ID, for direct-answer the answer text, for redirect-to-url the URL, for start-experience the component ID, for execute-custom-javascript the code, for the segment commands the topic (and message), and for open-image and open-video the media URL. Only start-live-chat takes no input.

string

nullable

enabled

Whether the procedure is live. Procedures saved before this field existed are treated as enabled and backfilled on read.

boolean

nullable

smartAction

When true the AI fills the variables from the conversation. When false the visitor is asked for each one.

boolean

nullable

escalate

Whether running this procedure hands the conversation to a human.

boolean

guidance

Extra instructions for the AI on how to use this procedure.

string

nullable

variables

The values collected before the procedure runs, referenced as {{name}} in the request.

Array<object>

One value collected from the visitor or filled by the AI before the procedure runs.

object

name

Referenced as {{name}} in the endpoint, headers or body.

string

description

What the value is. Shown to the visitor, and what the AI matches against when filling it itself.

string

type

How the value is collected and validated. string is a single-line input, multiline a text area, email validates an address, regex validates against the regex field, and select offers the options as a dropdown. No other value is accepted: number, boolean, date and phone are reserved but not implemented, and storing one of them makes the get procedures endpoint fail for the whole workspace.

string

Allowed values: string multiline email regex select

optional

boolean

forceCollection

Ask the visitor even when the AI could infer the value.

boolean

regex

Pattern the collected value must match.

string

nullable

options

Fixed set of choices offered to the visitor.

Array<object>

nullable

object

label

string

value

string

dependsOnVariable

Only collect this variable when the named variable has dependsOnVariableValue.

string

nullable

dependsOnVariableValue

string

nullable

availability

string

nullable

Allowed values: ALWAYS DURING_OPENING_HOURS OUTSIDE_OPENING_HOURS

lifecycleStage

string

nullable

Allowed values: support newSales retention salesExpansion

enabledSegments

Restrict the procedure to these AI segments. Empty or absent means every segment.

Array<string>

nullable

enabledAudiences

Restrict the procedure to these audiences.

Array<string>

nullable

preCollectionMessage

Shown before the visitor is asked for the variables.

string

nullable

preExecuteMessage

Shown just before the procedure executes.

string

nullable

immediatelyExecute

boolean

nullable

triggerAfterResponse

boolean

triggerAfterUnanswered

Run the procedure when the AI could not answer the question.

boolean

triggerAfterTimeout

boolean

triggerAfterTimeoutTime

Seconds of inactivity before the timeout trigger fires.

number

skipTranslation

boolean

nullable

javascriptDisplayTrigger

JavaScript expression that must be truthy for the procedure to be offered.

string

nullable

documentsTriggeringAction

Training documents that reference this procedure, so you can see which knowledge triggers it. Read-only, and only returned by the list operation.

Array<object>

object

Example

{
  "actions": [
    {
      "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "actionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arguments": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Look up order status",
      "description": "Retrieves the status of an order from the shop backend.",
      "command": "api",
      "enabled": true,
      "smartAction": true,
      "escalate": false,
      "method": "GET",
      "endpoint": "https://api.example.com/orders/{{orderId}}",
      "headers": {
        "x-api-key": "{{shopApiKey}}"
      },
      "body": "{}",
      "bodyType": "json",
      "variables": [
        {
          "name": "orderId",
          "description": "The order number the visitor is asking about",
          "type": "string"
        }
      ],
      "onSuccessPostActions": [
        {
          "command": "display-message",
          "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "text": "Here is the status of your order."
        }
      ],
      "onErrorPostActions": [],
      "lifecycleStage": "support",
      "documentsTriggeringAction": []
    }
  ]
}

400

Bad request - missing websiteId.

401

Unauthorized - invalid API key.

502

A stored procedure in the workspace failed schema validation, for instance a variable with a type outside the documented enum. No procedures are returned until it is corrected.