# Chatbot flows

## Lists all flows for a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.flows.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot flows","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/flows":{"get":{"operationId":"ChatbotFlowController_listFlows[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of all flows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListFlowsResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all flows for a chatbot","tags":["Chatbot flows"],"description":"\n\n**Required Permission:** `chatbots.flows.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListFlowsResponseDto":{"type":"object","properties":{"flows":{"description":"A list of flows.","type":"array","items":{"$ref":"#/components/schemas/FlowDto"}},"error":{"type":"string","description":"Optional error message."}},"required":["flows"]},"FlowDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the flow."},"name":{"type":"string","description":"The name of the flow."},"created":{"type":"string","description":"The creation timestamp of the flow."},"updated":{"type":"string","description":"The last update timestamp of the flow."},"type":{"type":"string","description":"The type of the flow (e.g., \"default\", \"faq\")."},"parent":{"description":"Information about the parent flow, if this is a sub-flow.","allOf":[{"$ref":"#/components/schemas/FlowParentDto"}]},"isStandard":{"type":"boolean","description":"Indicates whether the flow is a standard flow or not."}},"required":["id","name","created","updated","type"]},"FlowParentDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the parent flow."},"stepId":{"type":"string","description":"The ID of the step in the parent flow that calls this sub-flow."}},"required":["flowId","stepId"]}}}}
```

## Creates a new flow

> \
> \
> \*\*Required Permission:\*\* \`chatbots.flows.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot flows","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/flows":{"post":{"operationId":"ChatbotFlowController_createFlow[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFlowRequestDto"}}}},"responses":{"201":{"description":"Flow created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Creates a new flow","tags":["Chatbot flows"],"description":"\n\n**Required Permission:** `chatbots.flows.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CreateFlowRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the new flow."},"parentFlowId":{"type":"string","description":"The ID of the parent flow, if a sub-flow is being created."},"parentStepId":{"type":"string","description":"The ID of the step in the parent flow, if a sub-flow is being created."},"isStandard":{"type":"boolean","description":"Indicates whether the flow is a standard flow or not."}},"required":["name"]},"FlowResponseDto":{"type":"object","properties":{"flow":{"description":"The flow object.","allOf":[{"$ref":"#/components/schemas/FlowDto"}]}}},"FlowDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the flow."},"name":{"type":"string","description":"The name of the flow."},"created":{"type":"string","description":"The creation timestamp of the flow."},"updated":{"type":"string","description":"The last update timestamp of the flow."},"type":{"type":"string","description":"The type of the flow (e.g., \"default\", \"faq\")."},"parent":{"description":"Information about the parent flow, if this is a sub-flow.","allOf":[{"$ref":"#/components/schemas/FlowParentDto"}]},"isStandard":{"type":"boolean","description":"Indicates whether the flow is a standard flow or not."}},"required":["id","name","created","updated","type"]},"FlowParentDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the parent flow."},"stepId":{"type":"string","description":"The ID of the step in the parent flow that calls this sub-flow."}},"required":["flowId","stepId"]}}}}
```

## Retrieves a specific flow

> \
> \
> \*\*Required Permission:\*\* \`chatbots.flows.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot flows","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/flows/{flowId}":{"get":{"operationId":"ChatbotFlowController_getFlow[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"flowId","required":true,"in":"path","description":"The ID of the flow to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"Details of the flow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFlowResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific flow","tags":["Chatbot flows"],"description":"\n\n**Required Permission:** `chatbots.flows.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"GetFlowResponseDto":{"type":"object","properties":{"flow":{"description":"The flow object.","allOf":[{"$ref":"#/components/schemas/FlowDto"}]},"error":{"type":"string","description":"Optional error message."}}},"FlowDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the flow."},"name":{"type":"string","description":"The name of the flow."},"created":{"type":"string","description":"The creation timestamp of the flow."},"updated":{"type":"string","description":"The last update timestamp of the flow."},"type":{"type":"string","description":"The type of the flow (e.g., \"default\", \"faq\")."},"parent":{"description":"Information about the parent flow, if this is a sub-flow.","allOf":[{"$ref":"#/components/schemas/FlowParentDto"}]},"isStandard":{"type":"boolean","description":"Indicates whether the flow is a standard flow or not."}},"required":["id","name","created","updated","type"]},"FlowParentDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the parent flow."},"stepId":{"type":"string","description":"The ID of the step in the parent flow that calls this sub-flow."}},"required":["flowId","stepId"]}}}}
```

## Deletes a flow

> \
> \
> \*\*Required Permission:\*\* \`chatbots.flows.delete\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot flows","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/flows/{flowId}":{"delete":{"operationId":"ChatbotFlowController_deleteFlow[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"flowId","required":true,"in":"path","description":"The ID of the flow to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"Result of the deletion process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFlowResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes a flow","tags":["Chatbot flows"],"description":"\n\n**Required Permission:** `chatbots.flows.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteFlowResponseDto":{"type":"object","properties":{"deleted":{"type":"boolean","description":"Indicates whether the deletion operation was successful."}},"required":["deleted"]}}}}
```

## Updates an existing flow

> \
> \
> \*\*Required Permission:\*\* \`chatbots.flows.edit\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Chatbot flows","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/flows/{flowId}":{"patch":{"operationId":"ChatbotFlowController_updateFlow[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"flowId","required":true,"in":"path","description":"The ID of the flow to update.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFlowRequestDto"}}}},"responses":{"200":{"description":"Flow updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowResponseDto"}}}},"400":{"description":"Invalid input data."},"403":{"description":"Insufficient permissions."}},"summary":"Updates an existing flow","tags":["Chatbot flows"],"description":"\n\n**Required Permission:** `chatbots.flows.edit`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UpdateFlowRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the flow."},"parentFlowId":{"type":"string","description":"The new ID of the parent flow, if a sub-flow is being updated."},"parentStepId":{"type":"string","description":"The new ID of the step in the parent flow, if a sub-flow is being updated."}}},"FlowResponseDto":{"type":"object","properties":{"flow":{"description":"The flow object.","allOf":[{"$ref":"#/components/schemas/FlowDto"}]}}},"FlowDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the flow."},"name":{"type":"string","description":"The name of the flow."},"created":{"type":"string","description":"The creation timestamp of the flow."},"updated":{"type":"string","description":"The last update timestamp of the flow."},"type":{"type":"string","description":"The type of the flow (e.g., \"default\", \"faq\")."},"parent":{"description":"Information about the parent flow, if this is a sub-flow.","allOf":[{"$ref":"#/components/schemas/FlowParentDto"}]},"isStandard":{"type":"boolean","description":"Indicates whether the flow is a standard flow or not."}},"required":["id","name","created","updated","type"]},"FlowParentDto":{"type":"object","properties":{"flowId":{"type":"string","description":"The ID of the parent flow."},"stepId":{"type":"string","description":"The ID of the step in the parent flow that calls this sub-flow."}},"required":["flowId","stepId"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chatcaptain.com/api/api-dokumentation/chatbot-flows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.