Chatbot flows

Lists all flows for a chatbot

get

Required Permission: chatbots.flows.list

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Responses

200

List of all flows.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/flows

HTTPcURLJavaScriptPython

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

{
  "flows": [
    {
      "id": "Kq8BxZaJd2wZR9cxd1P",
      "name": "Order Process",
      "created": "2025-10-02T14:00:00Z",
      "updated": "2025-10-02T14:05:00Z",
      "type": "default",
      "parent": {
        "flowId": "Kq8BxZaJd2wZR9cxd1P",
        "stepId": "59aBv7wzR9cxd1Pxyz"
      },
      "isStandard": "false"
    }
  ],
  "error": "text"
}

Creates a new flow

post

Required Permission: chatbots.flows.create

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

Body

application/json

namestringRequired

The name of the new flow.

Example: Return Process

parentFlowIdstringOptional

The ID of the parent flow, if a sub-flow is being created.

Example: Kq8BxZaJd2wZR9cxd1P

parentStepIdstringOptional

The ID of the step in the parent flow, if a sub-flow is being created.

Example: 59aBv7wzR9cxd1Pxyz

isStandardbooleanOptional

Indicates whether the flow is a standard flow or not.

Example: false

Responses

201

Flow created successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

post

/v1/chatbots/{chatbotId}/flows

HTTPcURLJavaScriptPython

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

{
  "name": "Return Process",
  "parentFlowId": "Kq8BxZaJd2wZR9cxd1P",
  "parentStepId": "59aBv7wzR9cxd1Pxyz",
  "isStandard": "false"
}

{
  "flow": {
    "id": "Kq8BxZaJd2wZR9cxd1P",
    "name": "Order Process",
    "created": "2025-10-02T14:00:00Z",
    "updated": "2025-10-02T14:05:00Z",
    "type": "default",
    "parent": {
      "flowId": "Kq8BxZaJd2wZR9cxd1P",
      "stepId": "59aBv7wzR9cxd1Pxyz"
    },
    "isStandard": "false"
  }
}

Retrieves a specific flow

get

Required Permission: chatbots.flows.get

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flow to retrieve.

Responses

200

Details of the flow.

application/json

errorstringOptional

Optional error message.

403

Insufficient permissions.

get

/v1/chatbots/{chatbotId}/flows/{flowId}

HTTPcURLJavaScriptPython

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

{
  "flow": {
    "id": "Kq8BxZaJd2wZR9cxd1P",
    "name": "Order Process",
    "created": "2025-10-02T14:00:00Z",
    "updated": "2025-10-02T14:05:00Z",
    "type": "default",
    "parent": {
      "flowId": "Kq8BxZaJd2wZR9cxd1P",
      "stepId": "59aBv7wzR9cxd1Pxyz"
    },
    "isStandard": "false"
  },
  "error": "text"
}

Deletes a flow

delete

Required Permission: chatbots.flows.delete

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flow to delete.

Responses

200

Result of the deletion process.

application/json

deletedbooleanRequired

Indicates whether the deletion operation was successful.

Example: true

403

Insufficient permissions.

delete

/v1/chatbots/{chatbotId}/flows/{flowId}

HTTPcURLJavaScriptPython

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

{
  "deleted": true
}

Updates an existing flow

patch

Required Permission: chatbots.flows.edit

Resource: chatbots/:chatbotId

Authorizations

x-chatcaptain-key

x-chatcaptain-keystringRequired

Path parameters

chatbotIdstringRequired

The ID of the chatbot.

flowIdstringRequired

The ID of the flow to update.

Body

application/json

namestringOptional

The new name of the flow.

Example: Returns & Exchange Process

parentFlowIdstringOptional

The new ID of the parent flow, if a sub-flow is being updated.

Example: Kq8BxZaJd2wZR9cxd1P

parentStepIdstringOptional

The new ID of the step in the parent flow, if a sub-flow is being updated.

Example: 59aBv7wzR9cxd1Pxyz

Responses

200

Flow updated successfully.

application/json

400

Invalid input data.

403

Insufficient permissions.

patch

/v1/chatbots/{chatbotId}/flows/{flowId}

HTTPcURLJavaScriptPython

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

{
  "name": "Returns & Exchange Process",
  "parentFlowId": "Kq8BxZaJd2wZR9cxd1P",
  "parentStepId": "59aBv7wzR9cxd1Pxyz"
}

{
  "flow": {
    "id": "Kq8BxZaJd2wZR9cxd1P",
    "name": "Order Process",
    "created": "2025-10-02T14:00:00Z",
    "updated": "2025-10-02T14:05:00Z",
    "type": "default",
    "parent": {
      "flowId": "Kq8BxZaJd2wZR9cxd1P",
      "stepId": "59aBv7wzR9cxd1Pxyz"
    },
    "isStandard": "false"
  }
}