Chatbot examples

Lists and filters training examples

get

Required Permission: chatbots.examples.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Query parameters

limitnumberOptional

The limit for how many examples should be fetched.

pageTokenstringOptional

The date after which to filter examples. Only examples after this date will be fetched.

intentIdstringOptional

The Id of the intent the examples belong to.

entityIdstringOptional

The Id of the intent the examples belong to.

languagestringOptional

The language of the examples.

Responses

200

List of training examples.

application/json

pageTokenstringRequired

The date of the latest fetched example.

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/examples

HTTPcURLJavaScriptPython

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

{
  "pageToken": "text",
  "examples": [
    {
      "id": "ex_Kq8BxZaJd2wZR9cxd1P",
      "text": "When does my order arrive?",
      "created": "2025-10-02T10:00:00Z",
      "updated": "2025-10-02T10:05:00Z",
      "language": "DE",
      "intentId": "int_59aBv7wzR9cxd1Pxyz",
      "error": false,
      "predictionScore": 0.98,
      "entityIds": [
        "ent_59aBv7wzR9cxd1Pxyz"
      ],
      "entities": [
        {
          "entityId": "ent_59aBv7wzR9cxd1Pxyz",
          "value": "Bestellnummer",
          "start": 12,
          "end": 25
        }
      ],
      "translatedExampleIds": [
        "text"
      ],
      "status": 2,
      "vector": [
        1
      ],
      "conversationId": "Kq8BxZaJd2wZR9cxd1P"
    }
  ],
  "error": "text"
}

Creates a new training example

post

Required Permission: chatbots.examples.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

application/json

intentIdstringRequired

The ID of the Intent to which this example is assigned.

Example: 59aBv7wzR9cxd1Pxyz

textstringRequired

The text of the training example.

Example: I would like to know the status of my order.

languagestringOptional

The language of the example.

Example: DE

entityIdsstring[]Required

A list of entity Id's that are marked in this example.

Default: []

translatebooleanOptional

Indicates whether the example should be translated into other languages.

conversationIdstringOptional

Optional ID of the conversation from which the example originated.

Example: Kq8BxZaJd2wZR9cxd1P

Responses

201

Example created successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

post

/v1/chatbots/{chatbotId}/examples

HTTPcURLJavaScriptPython

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

{
  "intentId": "59aBv7wzR9cxd1Pxyz",
  "text": "I would like to know the status of my order.",
  "language": "DE",
  "entityIds": [
    "text"
  ],
  "entities": [
    {
      "entityId": "ent_59aBv7wzR9cxd1Pxyz",
      "value": "Bestellnummer",
      "start": 12,
      "end": 25
    }
  ],
  "translate": true,
  "conversationId": "Kq8BxZaJd2wZR9cxd1P"
}

{
  "example": {
    "id": "ex_Kq8BxZaJd2wZR9cxd1P",
    "text": "When does my order arrive?",
    "created": "2025-10-02T10:00:00Z",
    "updated": "2025-10-02T10:05:00Z",
    "language": "DE",
    "intentId": "int_59aBv7wzR9cxd1Pxyz",
    "error": false,
    "predictionScore": 0.98,
    "entityIds": [
      "ent_59aBv7wzR9cxd1Pxyz"
    ],
    "entities": [
      {
        "entityId": "ent_59aBv7wzR9cxd1Pxyz",
        "value": "Bestellnummer",
        "start": 12,
        "end": 25
      }
    ],
    "translatedExampleIds": [
      "text"
    ],
    "status": 2,
    "vector": [
      1
    ],
    "conversationId": "Kq8BxZaJd2wZR9cxd1P"
  },
  "error": "text"
}

Deletes a training example

delete

Required Permission: chatbots.examples.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

exampleIdstringRequired

The ID of the example to delete.

Responses

200

Result of the deletion process.

application/json

deletedbooleanRequired

Indicates whether the deletion was successful.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/examples/{exampleId}

HTTPcURLJavaScriptPython

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

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

Updates an existing training example.

patch

Required Permission: chatbots.examples.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

exampleIdstringRequired

The ID of the example to update.

Body

application/json

textstringRequired

The updated text of the training example.

entityIdsstring[]RequiredDefault: []

statusnumber · enumOptional

The status of the example.

• 0: PENDING
• 1: INDEXING
• 2: INDEXED
• 3: ERROR

Possible values:

vectornumber[]Required

The manually set vector for this example.

Default: []

Responses

200

Example updated successfully.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

404

Example not found.

patch

/v1/chatbots/{chatbotId}/examples/{exampleId}

HTTPcURLJavaScriptPython

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

{
  "text": "text",
  "entityIds": [
    "text"
  ],
  "entities": [
    {
      "entityId": "ent_59aBv7wzR9cxd1Pxyz",
      "value": "Bestellnummer",
      "start": 12,
      "end": 25
    }
  ],
  "status": 0,
  "vector": [
    1
  ]
}

{
  "example": {
    "id": "ex_Kq8BxZaJd2wZR9cxd1P",
    "text": "When does my order arrive?",
    "created": "2025-10-02T10:00:00Z",
    "updated": "2025-10-02T10:05:00Z",
    "language": "DE",
    "intentId": "int_59aBv7wzR9cxd1Pxyz",
    "error": false,
    "predictionScore": 0.98,
    "entityIds": [
      "ent_59aBv7wzR9cxd1Pxyz"
    ],
    "entities": [
      {
        "entityId": "ent_59aBv7wzR9cxd1Pxyz",
        "value": "Bestellnummer",
        "start": 12,
        "end": 25
      }
    ],
    "translatedExampleIds": [
      "text"
    ],
    "status": 2,
    "vector": [
      1
    ],
    "conversationId": "Kq8BxZaJd2wZR9cxd1P"
  },
  "error": "text"
}