Chatbot Intents

Lists all intents for a chatbot

get

Required Permission: chatbots.intents.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Responses

200

List of all intents.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/intents

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

{
  "intents": [
    {
      "id": "69aBv7wzR9cxd1Pxyz",
      "name": "Query order status",
      "created": "2025-10-02T15:00:00Z",
      "updated": "2025-10-02T15:05:00Z",
      "confidenceScore": 0.75,
      "state": "trained",
      "trainingRequired": false,
      "actor": {
        "type": "flow",
        "flowId": "Mq8BxZaJd2wZR9cxd1P",
        "stepId": "l9aBv7wzR9cxd1Pxyz"
      }
    }
  ],
  "error": "text"
}

Creates a new intent

post

Required Permission: chatbots.intents.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

namestringRequired

The name of the new intent.

Example: Register return

confidenceScorenumber · max: 1Required

The required minimum confidence score (0.0-1.0).

Example: 0.8

Responses

201

Intent created successfully.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/intents

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

{
  "name": "Register return",
  "confidenceScore": 0.8,
  "actor": {
    "type": "flow",
    "flowId": "Mq8BxZaJd2wZR9cxd1P",
    "stepId": "l9aBv7wzR9cxd1Pxyz"
  }
}

{
  "intent": {
    "id": "69aBv7wzR9cxd1Pxyz",
    "name": "Query order status",
    "created": "2025-10-02T15:00:00Z",
    "updated": "2025-10-02T15:05:00Z",
    "confidenceScore": 0.75,
    "state": "trained",
    "trainingRequired": false,
    "actor": {
      "type": "flow",
      "flowId": "Mq8BxZaJd2wZR9cxd1P",
      "stepId": "l9aBv7wzR9cxd1Pxyz"
    }
  },
  "error": "text"
}

Retrieves a specific intent

get

Required Permission: chatbots.intents.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

intentIdstringRequired

The ID of the intent to retrieve.

Responses

200

Details of the intent.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/intents/{intentId}

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

{
  "intent": {
    "id": "69aBv7wzR9cxd1Pxyz",
    "name": "Query order status",
    "created": "2025-10-02T15:00:00Z",
    "updated": "2025-10-02T15:05:00Z",
    "confidenceScore": 0.75,
    "state": "trained",
    "trainingRequired": false,
    "actor": {
      "type": "flow",
      "flowId": "Mq8BxZaJd2wZR9cxd1P",
      "stepId": "l9aBv7wzR9cxd1Pxyz"
    }
  },
  "error": "text"
}

Deletes an intent

delete

Required Permission: chatbots.intents.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

intentIdstringRequired

The ID of the intent 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}/intents/{intentId}

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

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

Updates an existing intent

patch

Required Permission: chatbots.intents.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

intentIdstringRequired

The ID of the intent to update.

Body

namestringOptional

The new name for the intent.

Example: Returns and exchanges

confidenceScorenumber · max: 1Optional

The new confidence score for the intent.

Example: 0.85

trainingRequiredbooleanOptional

Whether the intent requires training.

Example: true

Responses

200

Intent updated successfully.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

patch/v1/chatbots/{chatbotId}/intents/{intentId}

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

{
  "name": "Returns and exchanges",
  "confidenceScore": 0.85,
  "trainingRequired": true,
  "actor": {
    "type": "flow",
    "flowId": "Mq8BxZaJd2wZR9cxd1P",
    "stepId": "l9aBv7wzR9cxd1Pxyz"
  }
}

{
  "intent": {
    "id": "69aBv7wzR9cxd1Pxyz",
    "name": "Query order status",
    "created": "2025-10-02T15:00:00Z",
    "updated": "2025-10-02T15:05:00Z",
    "confidenceScore": 0.75,
    "state": "trained",
    "trainingRequired": false,
    "actor": {
      "type": "flow",
      "flowId": "Mq8BxZaJd2wZR9cxd1P",
      "stepId": "l9aBv7wzR9cxd1Pxyz"
    }
  },
  "error": "text"
}