Chatbot Versions

Lists all versions of a chatbot

get

Required Permission: chatbots.versions.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Responses

200

List of all versions.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get/v1/chatbots/{chatbotId}/versions

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

{
  "versions": [
    {
      "id": "By4hQWBaJaRrwvxg5fWz",
      "name": "Version 1.2.3",
      "created": "2025-10-04T10:00:00Z",
      "deployed": "2025-10-04T10:05:00Z",
      "modelId": "modl_Kq8BxZaJd2wZR9cxd1P",
      "versionNumber": "1.2.3",
      "stats": {
        "steps": 42,
        "events": 15,
        "intents": 28,
        "entities": 12,
        "flows": 8,
        "triggers": 5
      },
      "description": "Initial release",
      "environment": "dev",
      "deploymentId": "OI03ITtm1nSliNJGJ5HV",
      "hasActiveDeployment": true,
      "resettable": true
    }
  ],
  "error": "text"
}

Creates a new version

post

Required Permission: chatbots.versions.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

descriptionstringOptional

An optional description for the new version.

Example: Release for Q4 Campaign

namestringRequired

The name of the new version (often automatically generated).

Example: Version 1.2.4

environmentstring · enumRequired

The environment for which this version is created. None being dev, as no deployment is needed.

Example: testPossible values:

Responses

201

Version created successfully.

application/json

errorstringOptional

Optional error message.

400

Invalid input data.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/versions

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

{
  "description": "Release for Q4 Campaign",
  "name": "Version 1.2.4",
  "environment": "test"
}

{
  "version": {
    "id": "By4hQWBaJaRrwvxg5fWz",
    "name": "Version 1.2.3",
    "created": "2025-10-04T10:00:00Z",
    "deployed": "2025-10-04T10:05:00Z",
    "modelId": "modl_Kq8BxZaJd2wZR9cxd1P",
    "versionNumber": "1.2.3",
    "stats": {
      "steps": 42,
      "events": 15,
      "intents": 28,
      "entities": 12,
      "flows": 8,
      "triggers": 5
    },
    "description": "Initial release",
    "environment": "dev",
    "deploymentId": "OI03ITtm1nSliNJGJ5HV",
    "hasActiveDeployment": true,
    "resettable": true
  },
  "error": "text"
}

Deletes a version

delete

Required Permission: chatbots.versions.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

versionIdstringRequired

The Id of the version to be deleted.

Responses

200Success

application/json

deletedbooleanOptional

Indicates whether the version was successfully deleted.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

delete/v1/chatbots/{chatbotId}/versions/{versionId}

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

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

Deploys a version to an environment

post

Required Permission: chatbots.versions.deploy

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

versionIdstringRequired

The Id of the version to be deployed.

Body

environmentstring · enumRequired

The target environment for the deployment.

Example: prodPossible values:

Responses

202

Deployment process started.

application/json

startedbooleanOptional

Indicates whether the deployment was successfully started.

Example: true

errorstringOptional

Optional error message.

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/versions/{versionId}/deploy

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

{
  "environment": "prod"
}

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

Performs a rollback to a specific version

post

Required Permission: chatbots.versions.deploy

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

versionIdstringRequired

The Id of the version to roll back on.

Body

Responses

200

Result of the rollback operation.

application/json

rolledBackbooleanOptional

Indicates whether the rollback was successful.

Example: true

errorstringOptional

Optional error message.

201Success

application/json

403

Insufficient permissions.

post/v1/chatbots/{chatbotId}/versions/{versionId}/rollback

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

{
  "excludeComponents": [
    0,
    1
  ]
}

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