Chatbot entities

Lists all entities for a chatbot

get

Required Permission: chatbots.entities.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Responses

200

List of all entities.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/entities

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/entities HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "entities": [
    {
      "category": "Order",
      "compositionSettings": {
        "combineComponents": "combine",
        "requireExactOverlap": "exact",
        "returnLongestOverlap": "longest",
        "separateComponents": "separate"
      },
      "list": {
        "sublists": [
          {
            "listKey": "Order",
            "synonyms": [
              {
                "language": "EN-GB",
                "values": [
                  "Order",
                  "Shipment"
                ]
              }
            ]
          }
        ]
      },
      "prebuilts": [
        {
          "category": "Quantity.Number"
        }
      ],
      "regex": {
        "expressions": [
          {
            "regexKey": "ORDER_NUMBER_REGEX",
            "language": "DE",
            "regexPattern": "[A-Z]{2,}\\d{5,}"
          }
        ]
      },
      "requiredComponents": [
        "list",
        "prebuilts"
      ],
      "id": "59aBv7wzR9cxd1Pxyz",
      "created": "2025-10-02T08:00:00Z",
      "updated": "2025-10-02T08:05:00Z",
      "editable": true,
      "enabled": true,
      "variableId": "Kq8BxZaJd2wZR9cxd1P"
    }
  ],
  "error": "text"
}

Creates a new entity

post

Required Permission: chatbots.entities.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

application/json

Responses

201

Entity created successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

post

/v1/chatbots/{chatbotId}/entities

HTTPcURLJavaScriptPython

POST /v1/chatbots/{chatbotId}/entities HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 483

{
  "entity": {
    "category": "Order",
    "compositionSettings": {
      "combineComponents": "combine",
      "requireExactOverlap": "exact",
      "returnLongestOverlap": "longest",
      "separateComponents": "separate"
    },
    "list": {
      "sublists": [
        {
          "listKey": "Order",
          "synonyms": [
            {
              "language": "EN-GB",
              "values": [
                "Order",
                "Shipment"
              ]
            }
          ]
        }
      ]
    },
    "prebuilts": [
      {
        "category": "Quantity.Number"
      }
    ],
    "regex": {
      "expressions": [
        {
          "regexKey": "ORDER_NUMBER_REGEX",
          "language": "DE",
          "regexPattern": "[A-Z]{2,}\\d{5,}"
        }
      ]
    },
    "requiredComponents": [
      "list",
      "prebuilts"
    ]
  }
}

{
  "entity": {
    "category": "Order",
    "compositionSettings": {
      "combineComponents": "combine",
      "requireExactOverlap": "exact",
      "returnLongestOverlap": "longest",
      "separateComponents": "separate"
    },
    "list": {
      "sublists": [
        {
          "listKey": "Order",
          "synonyms": [
            {
              "language": "EN-GB",
              "values": [
                "Order",
                "Shipment"
              ]
            }
          ]
        }
      ]
    },
    "prebuilts": [
      {
        "category": "Quantity.Number"
      }
    ],
    "regex": {
      "expressions": [
        {
          "regexKey": "ORDER_NUMBER_REGEX",
          "language": "DE",
          "regexPattern": "[A-Z]{2,}\\d{5,}"
        }
      ]
    },
    "requiredComponents": [
      "list",
      "prebuilts"
    ],
    "id": "59aBv7wzR9cxd1Pxyz",
    "created": "2025-10-02T08:00:00Z",
    "updated": "2025-10-02T08:05:00Z",
    "editable": true,
    "enabled": true,
    "variableId": "Kq8BxZaJd2wZR9cxd1P"
  },
  "error": "text"
}

Retrieves a specific entity

get

Required Permission: chatbots.entities.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

entityIdstringRequired

The ID of the entity to retrieve.

Responses

200

Details of the entity.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/entities/{entityId}

HTTPcURLJavaScriptPython

GET /v1/chatbots/{chatbotId}/entities/{entityId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "entity": {
    "category": "Order",
    "compositionSettings": {
      "combineComponents": "combine",
      "requireExactOverlap": "exact",
      "returnLongestOverlap": "longest",
      "separateComponents": "separate"
    },
    "list": {
      "sublists": [
        {
          "listKey": "Order",
          "synonyms": [
            {
              "language": "EN-GB",
              "values": [
                "Order",
                "Shipment"
              ]
            }
          ]
        }
      ]
    },
    "prebuilts": [
      {
        "category": "Quantity.Number"
      }
    ],
    "regex": {
      "expressions": [
        {
          "regexKey": "ORDER_NUMBER_REGEX",
          "language": "DE",
          "regexPattern": "[A-Z]{2,}\\d{5,}"
        }
      ]
    },
    "requiredComponents": [
      "list",
      "prebuilts"
    ],
    "id": "59aBv7wzR9cxd1Pxyz",
    "created": "2025-10-02T08:00:00Z",
    "updated": "2025-10-02T08:05:00Z",
    "editable": true,
    "enabled": true,
    "variableId": "Kq8BxZaJd2wZR9cxd1P"
  },
  "error": "text"
}

Deletes an entity

delete

Required Permission: chatbots.entities.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

entityIdstringRequired

The ID of the entity to delete.

Responses

200

Result of the deletion process.

application/json

deletedbooleanRequired

Indicates whether the deletion operation was successful.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/entities/{entityId}

HTTPcURLJavaScriptPython

DELETE /v1/chatbots/{chatbotId}/entities/{entityId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Accept: */*

{
  "deleted": true,
  "error": "text"
}

Updates an existing entity

patch

Required Permission: chatbots.entities.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

entityIdstringRequired

The ID of the entity to update.

Body

application/json

Responses

200

Entity updated successfully.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

patch

/v1/chatbots/{chatbotId}/entities/{entityId}

HTTPcURLJavaScriptPython

PATCH /v1/chatbots/{chatbotId}/entities/{entityId} HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 483

{
  "entity": {
    "category": "Order",
    "compositionSettings": {
      "combineComponents": "combine",
      "requireExactOverlap": "exact",
      "returnLongestOverlap": "longest",
      "separateComponents": "separate"
    },
    "list": {
      "sublists": [
        {
          "listKey": "Order",
          "synonyms": [
            {
              "language": "EN-GB",
              "values": [
                "Order",
                "Shipment"
              ]
            }
          ]
        }
      ]
    },
    "prebuilts": [
      {
        "category": "Quantity.Number"
      }
    ],
    "regex": {
      "expressions": [
        {
          "regexKey": "ORDER_NUMBER_REGEX",
          "language": "DE",
          "regexPattern": "[A-Z]{2,}\\d{5,}"
        }
      ]
    },
    "requiredComponents": [
      "list",
      "prebuilts"
    ]
  }
}

{
  "entity": {
    "category": "Order",
    "compositionSettings": {
      "combineComponents": "combine",
      "requireExactOverlap": "exact",
      "returnLongestOverlap": "longest",
      "separateComponents": "separate"
    },
    "list": {
      "sublists": [
        {
          "listKey": "Order",
          "synonyms": [
            {
              "language": "EN-GB",
              "values": [
                "Order",
                "Shipment"
              ]
            }
          ]
        }
      ]
    },
    "prebuilts": [
      {
        "category": "Quantity.Number"
      }
    ],
    "regex": {
      "expressions": [
        {
          "regexKey": "ORDER_NUMBER_REGEX",
          "language": "DE",
          "regexPattern": "[A-Z]{2,}\\d{5,}"
        }
      ]
    },
    "requiredComponents": [
      "list",
      "prebuilts"
    ],
    "id": "59aBv7wzR9cxd1Pxyz",
    "created": "2025-10-02T08:00:00Z",
    "updated": "2025-10-02T08:05:00Z",
    "editable": true,
    "enabled": true,
    "variableId": "Kq8BxZaJd2wZR9cxd1P"
  },
  "error": "text"
}

Changes the activation status of an entity

patch

Required Permission: chatbots.entities.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

entityIdstringRequired

The ID of the entity.

Body

application/json

enabledbooleanRequired

Sets the entity to enabled (true) or disabled (false).

Example: true

Responses

200

Status changed successfully.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

patch

/v1/chatbots/{chatbotId}/entities/{entityId}/state

HTTPcURLJavaScriptPython

PATCH /v1/chatbots/{chatbotId}/entities/{entityId}/state HTTP/1.1
Host: api.chatcaptain.com
x-chatcaptain-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "enabled": true
}

{
  "entity": {
    "category": "Order",
    "compositionSettings": {
      "combineComponents": "combine",
      "requireExactOverlap": "exact",
      "returnLongestOverlap": "longest",
      "separateComponents": "separate"
    },
    "list": {
      "sublists": [
        {
          "listKey": "Order",
          "synonyms": [
            {
              "language": "EN-GB",
              "values": [
                "Order",
                "Shipment"
              ]
            }
          ]
        }
      ]
    },
    "prebuilts": [
      {
        "category": "Quantity.Number"
      }
    ],
    "regex": {
      "expressions": [
        {
          "regexKey": "ORDER_NUMBER_REGEX",
          "language": "DE",
          "regexPattern": "[A-Z]{2,}\\d{5,}"
        }
      ]
    },
    "requiredComponents": [
      "list",
      "prebuilts"
    ],
    "id": "59aBv7wzR9cxd1Pxyz",
    "created": "2025-10-02T08:00:00Z",
    "updated": "2025-10-02T08:05:00Z",
    "editable": true,
    "enabled": true,
    "variableId": "Kq8BxZaJd2wZR9cxd1P"
  },
  "error": "text"
}