# Bot API

## Get bot

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot`

Retrieve the bot for this integration

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "MyBot",
  "description": "This is my bot",
  "default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "created_at": "2019-12-11T18:59:39.391Z",
  "updated_at": "2019-12-13T01:27:38.653Z",
  "env": {
    "MY_VAR": "somevalue"
  },
  "flows": [
      {
      "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
      "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
      "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
      "name": "Default",
      "description": "Default custom flow",
      "commands": [
        "/default"
      ],
      "content": "start:\n\tsay \"hello!\"\n\tgoto end",
      "created_at": "2019-12-11T18:59:39.610Z",
      "updated_at": "2019-12-13T01:31:51.507Z",
    },
    ...
  ]
}
```

{% endtab %}
{% endtabs %}

## Update bot

<mark style="color:orange;">`PUT`</mark> `https://clients.csml.dev/v1/api/bot`

Update a bot's name, default\_flow and/or description. Parameters that are not set will not be changed.

#### Request Body

| Name          | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| env           | object | key/value hash of bot environment variables |
| default\_flow | string | ID of default flow to set (flow must exist) |
| description   | string |                                             |
| name          | string |                                             |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "MyBot",
  "description": "This is my bot",
  "default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "created_at": "2019-12-11T18:59:39.391Z",
  "updated_at": "2019-12-13T01:27:38.653Z",
  "flows": [
      {
      "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
      "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
      "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
      "name": "Default",
      "description": "Default custom flow",
      "commands": [
        "/default"
      ],
      "content": "start:\n\tsay \"hello!\"\n\tgoto end",
      "created_at": "2019-12-11T18:59:39.610Z",
      "updated_at": "2019-12-13T01:31:51.507Z",
    },
    ...
  ]
}
```

{% endtab %}
{% endtabs %}

## Get bot flows

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot/flows`

Retrieve all the flows in the current bot

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
    "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
    "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
    "name": "Default",
    "description": "Default custom flow",
    "commands": [
      "/default"
    ],
    "content": "start:\n\tsay \"hello!\"\n\tgoto end",
    "created_at": "2019-12-11T18:59:39.610Z",
    "updated_at": "2019-12-13T01:31:51.507Z",
  },
  ...
]
```

{% endtab %}
{% endtabs %}

## Create Flow

<mark style="color:green;">`POST`</mark> `https://clients.csml.dev/v1/api/bot/flows`

Add a new flow to the current bot

#### Request Body

| Name        | Type   | Description                                                                  |
| ----------- | ------ | ---------------------------------------------------------------------------- |
| description | string | Description of the flow to create                                            |
| commands    | array  | <p>Commands that will trigger the flow.<br>Example: \["some", "command"]</p> |
| content     | string | CSML Flow                                                                    |
| name        | string | Name of the flow                                                             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "SomeFlow",
  "bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "commands": [
    "/someflow",
    "some command"
  ],
  "content": "start:\n  say \"Hi!\"\n  goto end",
  "created_at": "2020-08-23T17:54:39.461Z",
  "updated_at": "2020-08-23T17:54:39.461Z"
} 
```

{% endtab %}
{% endtabs %}

## Get flow

<mark style="color:blue;">`GET`</mark> `https://clients/csml.dev/v1/api/bot/flows/:flow_id`

#### Path Parameters

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| flow\_id | string |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "Default",
  "description": "Default custom flow",
  "commands": [
    "/default"
  ],
  "content": "start:\n\tsay \"hello!\"\n\tgoto end",
  "created_at": "2019-12-11T18:59:39.610Z",
  "updated_at": "2019-12-13T01:31:51.507Z",
}



```

{% endtab %}
{% endtabs %}

## Update flow

<mark style="color:orange;">`PUT`</mark> `https://clients/csml.dev/v1/api/bot/flows/:flow_id`

#### Path Parameters

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| flow\_id | string |             |

#### Request Body

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| commands    | array  |             |
| content     | string |             |
| description | string |             |

{% tabs %}
{% tab title="204 " %}

```javascript
{
  "id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "SomeFlow",
  "bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "commands": [
    "/someflow",
    "some command"
  ],
  "content": "start:\n  say \"Hi!\"\n  goto end",
  "created_at": "2020-08-23T17:54:39.461Z",
  "updated_at": "2020-08-23T17:54:39.461Z"
} 
```

{% endtab %}
{% endtabs %}

## Bot usage

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot/usage`

Get usage information about a bot

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "currentmonth": {
    "messages": 0,
    "clients": 0
  },
  "last30d": {
    "messages": 0,
    "clients": 0
  },
  "lastmonth": {
    "messages": 0,
    "clients": 0
  }
}
```

{% endtab %}
{% endtabs %}

## Validate bot

<mark style="color:green;">`POST`</mark> `https://clients.csml.dev/v1/api/bot/validate`

Validate bot data against the CSML interpreter

#### Request Body

| Name | Type   | Description                                             |
| ---- | ------ | ------------------------------------------------------- |
|      | object | The bot object as retrieved from the GET /bot operation |

{% tabs %}
{% tab title="200 " %}

```javascript
// bot is valid
{
  "valid": true
}

// bot is invalid
{
  "valid": false,
  "errors": [
    {
      "flow": "someFlow",
      "step": "someStep",
      "line": 0,
      "column": 0,
      "message": "error message"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Build bot

<mark style="color:green;">`POST`</mark> `https://clients.csml.dev/v1/api/bot/build`

Build a new version of the bot

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "name": "test",
  "default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
  "created_at": "2020-08-23T17:47:21.229Z",
  "version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
  "engine_version": "1.4.0",
  "flows": [
    {
      "id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
      "name": "Default",
      "commands": [
        "/default"
      ],
      "content": "start:\n  say \"Hello\"\n  goto end",
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get bot build version

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot/build`

#### Query Parameters

| Name        | Type   | Description                                                           |
| ----------- | ------ | --------------------------------------------------------------------- |
| version\_id | string | <p>ID of version to retrieve.<br>Defaults to `latest` if not set.</p> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "name": "test",
  "default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
  "created_at": "2020-08-23T17:47:21.229Z",
  "version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
  "engine_version": "1.4.0",
  "flows": [
    {
      "id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
      "name": "Default",
      "commands": [
        "/default"
      ],
      "content": "start:\n  say \"Hello\"\n  goto end",
    }
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.csml.dev/studio/api/api-reference/bot-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.