> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create workflow > Create a new workflow in draft status. You can provide a minimal definition (just a start node) and build out the workflow later, or provide a complete workflow definition with all nodes and edges. After creating a workflow, you can: 1. Update the definition to add more nodes/edges 2. Create triggers to specify when the workflow should execute 3. Activate the workflow by changing status to 'active' ## OpenAPI ````yaml /api/platform/v1/openapi-workflows.yaml post /workflows openapi: 3.1.0 info: title: Kapso Platform API – Advanced Resources version: 0.1.0 description: > Build WhatsApp automation workflows and serverless functions. Create multi-step conversation flows, inspect executions, and deploy custom logic. servers: - url: https://api.kapso.ai/platform/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Workflows description: Create and manage conversation workflows and executions - name: Workflow Triggers description: Configure workflow triggers to automate execution - name: Functions description: Manage serverless functions, deployments, and secrets - name: WhatsApp Conversations description: Query WhatsApp conversation data and related resources paths: /workflows: post: tags: - Workflows summary: Create workflow description: > Create a new workflow in draft status. You can provide a minimal definition (just a start node) and build out the workflow later, or provide a complete workflow definition with all nodes and edges. After creating a workflow, you can: 1. Update the definition to add more nodes/edges 2. Create triggers to specify when the workflow should execute 3. Activate the workflow by changing status to 'active' operationId: createWorkflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowCreateRequest' responses: '201': description: Workflow created successfully content: application/json: schema: $ref: '#/components/schemas/WorkflowResponse' '401': $ref: '#/components/responses/UnauthorizedError' '422': $ref: '#/components/responses/ValidationError' components: schemas: WorkflowCreateRequest: type: object required: - workflow properties: workflow: type: object required: - name properties: name: type: string description: Workflow name (must be unique within project) slug: type: string description: > Optional URL-safe identifier. Auto-generated from `name` if omitted. Lowercase alphanumeric with hyphens. Unique within the project. pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ example: inbound-support description: type: - string - 'null' description: Optional workflow description definition: $ref: '#/components/schemas/WorkflowDefinitionInput' description: > Initial workflow graph structure. Can be minimal (just a start node) or fully defined. Field names are snake_case. The definition contains: - `nodes`: Array of workflow steps with `node_type`, `config`, and position - `edges`: Array of transitions connecting steps Example minimal definition: ```json { "nodes": [{ "id": "start", "type": "flow-node", "position": {"x": 100, "y": 100}, "data": {"node_type": "start", "config": {}, "display_name": "Start"} }], "edges": [] } ``` WorkflowResponse: type: object required: - data properties: data: $ref: '#/components/schemas/Workflow' description: Single workflow response WorkflowDefinitionInput: type: object properties: nodes: type: array description: > Desired node set for the workflow. When `nodes` is present on create or update, it is treated as the complete node set: nodes omitted from the array are removed. Omit `nodes` to leave existing nodes unchanged on update. items: $ref: '#/components/schemas/WorkflowDefinitionInputNode' edges: type: array description: > Desired edge set for the workflow. When `edges` is present on create or update, it is treated as the complete edge set: edges omitted from the array are removed. Omit `edges` to leave existing edges unchanged on update. items: $ref: '#/components/schemas/WorkflowDefinitionInputEdge' additionalProperties: false description: > Workflow graph write payload. Field names are snake_case. The expanded definition response includes persisted IDs such as edge IDs and condition IDs; those IDs are optional in write payloads. Workflow: type: object required: - id - name - slug - status - created_at - updated_at properties: id: type: string format: uuid description: Unique workflow identifier name: type: string description: Workflow name (unique per project) slug: type: string description: > URL-safe workflow identifier (lowercase alphanumeric with hyphens). Stable across renames — useful as an external sync key. Auto-generated from `name` on create if not provided. Unique within the project. pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ example: inbound-support description: type: - string - 'null' description: Optional workflow description status: type: string enum: - draft - active - archived description: | Workflow lifecycle status: - `draft`: Under development, not executable - `active`: Published and executable - `archived`: Inactive, no longer in use lock_version: type: - integer - 'null' description: > Optimistic locking version. Increment on each update to prevent concurrent modification conflicts. Include this value when updating to ensure you're working with the latest version. message_debounce_seconds: type: - integer - 'null' description: > Debounce window for incoming messages in seconds (default: 1). When a user sends multiple messages rapidly, the workflow waits this duration before processing to batch messages together. Prevents workflow from reacting to every keystroke. agent_default_tools_version: type: - integer - 'null' description: >- Version used to decide which built-in agent tools are required by default for this workflow. inbound_message_read_mode: type: string enum: - disabled - read_only - read_with_typing description: > Controls how inbound WhatsApp messages are marked as read before the workflow responds (default: read_with_typing). - `disabled`: Do nothing — messages are not marked as read - `read_only`: Mark messages as read without showing a typing indicator - `read_with_typing`: Mark as read and show a typing indicator before responding created_at: type: string format: date-time description: Workflow creation timestamp updated_at: type: string format: date-time description: Last modification timestamp project_id: type: string format: uuid description: Project this workflow belongs to execution_count: type: integer minimum: 0 description: Total number of times this workflow has been executed last_executed_at: type: - string - 'null' format: date-time description: Timestamp of most recent execution, null if never executed ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message WorkflowDefinitionInputNode: type: object required: - id - position - data properties: id: type: string description: >- Stable step identifier used by edges. Use a readable identifier such as `send_intro`. pattern: ^[A-Za-z][A-Za-z0-9_-]*$ example: send_intro type: type: string description: Canvas renderer type. Use `flow-node`. example: flow-node position: $ref: '#/components/schemas/WorkflowDefinitionNodePosition' data: $ref: '#/components/schemas/WorkflowDefinitionInputNodeData' additionalProperties: false description: Node write payload. WorkflowDefinitionInputEdge: type: object required: - source - target properties: id: type: string format: uuid description: Optional existing edge ID. Usually omitted for new edges. source: type: string description: Source node identifier. example: start target: type: string description: Target node identifier. example: send_intro label: type: string description: >- Transition label. Use `next` for non-decision nodes. For decide nodes, this must match a condition label. default: next example: next type: type: string description: Optional canvas edge renderer type. The API returns `default`. example: default flow_condition_id: type: - string - 'null' format: uuid description: >- Optional persisted condition ID for decide-step edges. If omitted, the API resolves decide edges by `label`. additionalProperties: false description: Edge write payload. WorkflowDefinitionNodePosition: type: object required: - x - 'y' properties: x: type: number description: Horizontal canvas position. example: 360 'y': type: number description: Vertical canvas position. example: 120 additionalProperties: false description: Canvas position of the node. WorkflowDefinitionInputNodeData: type: object required: - node_type - config properties: node_type: type: string enum: - start - send_text - send_template - send_interactive - wait_for_response - decide - function - webhook - agent - call - handoff - set_variable description: Canonical backend node type. config: anyOf: - $ref: '#/components/schemas/WorkflowNodeStartConfig' - $ref: '#/components/schemas/WorkflowNodeSendTextConfig' - $ref: '#/components/schemas/WorkflowNodeSendTemplateConfig' - $ref: '#/components/schemas/WorkflowNodeSendInteractiveConfig' - $ref: '#/components/schemas/WorkflowNodeWaitForResponseConfig' - $ref: '#/components/schemas/WorkflowNodeDecideConfig' - $ref: '#/components/schemas/WorkflowNodeFunctionConfig' - $ref: '#/components/schemas/WorkflowNodeWebhookConfig' - $ref: '#/components/schemas/WorkflowNodeAgentConfig' - $ref: '#/components/schemas/WorkflowNodeCallConfig' - $ref: '#/components/schemas/WorkflowNodeHandoffConfig' - $ref: '#/components/schemas/WorkflowNodeSetVariableConfig' description: Node configuration. Shape depends on `node_type`. display_name: type: string description: Optional human-friendly label shown in the visual editor. additionalProperties: false description: Node data write payload. WorkflowNodeStartConfig: type: object additionalProperties: false description: Empty config for the `start` node. WorkflowNodeSendTextConfig: type: object required: - message properties: message: oneOf: - type: string - type: object additionalProperties: true description: >- Text message body. Supports workflow variable interpolation such as `{{vars.customer_name}}`. example: Hi {{vars.customer_name}}, how can we help? phone_number_id: type: - string - 'null' description: >- Preferred WhatsApp Business phone number ID to send from. If omitted, Kapso uses the conversation's phone number. whatsapp_config_id: type: - string - 'null' format: uuid description: >- Legacy internal WhatsApp config ID. Prefer `phone_number_id` for new integrations. to_phone_number: type: - string - 'null' description: >- Override destination phone number. Mainly used by observer-mode workflows that are not attached to an inbound conversation. delay_seconds: type: - integer - 'null' minimum: 0 description: Delay before sending the message. provider_model_id: type: - string - 'null' format: uuid description: AI model ID used when resolving AI fields. provider_model_name: type: - string - 'null' description: AI model name used when resolving AI fields. ai_field_config: type: object additionalProperties: true description: AI field-resolution settings. additionalProperties: false description: Config for `send_text` nodes. WorkflowNodeSendTemplateConfig: type: object required: - template_id properties: template_id: type: string format: uuid description: WhatsApp template ID. template_name: type: - string - 'null' description: Template name returned by definition responses. parameters: description: >- Template parameters. Supports Meta components format, `template_params`, arrays, and objects. phone_number_id: type: - string - 'null' description: >- Preferred WhatsApp Business phone number ID to send from. If omitted, Kapso uses the conversation's phone number. whatsapp_config_id: type: - string - 'null' format: uuid description: >- Legacy internal WhatsApp config ID. Prefer `phone_number_id` for new integrations. to_phone_number: type: - string - 'null' description: Override destination phone number. provider_model_id: type: - string - 'null' format: uuid provider_model_name: type: - string - 'null' ai_field_config: type: object additionalProperties: true additionalProperties: false description: Config for `send_template` nodes. WorkflowNodeSendInteractiveConfig: type: object required: - interactive_type - body_text properties: interactive_type: type: string enum: - button - list - cta_url - flow - product - product_list - catalog_message - location_request_message description: WhatsApp interactive message type. body_text: oneOf: - type: string maxLength: 1024 - type: object additionalProperties: true description: Main message body. footer_text: type: - string - 'null' header_type: type: - string - 'null' enum: - none - text - image - video - document - null header_text: type: - string - 'null' header_media_url: type: - string - 'null' buttons: type: array maxItems: 3 items: $ref: '#/components/schemas/WorkflowNodeInteractiveButton' list_button_text: type: - string - 'null' list_sections: type: array maxItems: 10 items: $ref: '#/components/schemas/WorkflowNodeInteractiveListSection' cta_display_text: type: - string - 'null' cta_url: type: - string - 'null' flow_id: type: - string - 'null' flow_cta: type: - string - 'null' flow_token: type: - string - 'null' flow_action: type: - string - 'null' enum: - navigate - data_exchange - null flow_action_payload: type: - object - 'null' additionalProperties: true header_config: type: - object - 'null' additionalProperties: true description: Legacy expanded header config returned by definition responses. action_config: type: - object - 'null' additionalProperties: true description: Legacy expanded action config returned by definition responses. phone_number_id: type: - string - 'null' description: >- Preferred WhatsApp Business phone number ID to send from. If omitted, Kapso uses the conversation's phone number. whatsapp_config_id: type: - string - 'null' format: uuid description: >- Legacy internal WhatsApp config ID. Prefer `phone_number_id` for new integrations. to_phone_number: type: - string - 'null' description: Override destination phone number. provider_model_id: type: - string - 'null' format: uuid provider_model_name: type: - string - 'null' ai_field_config: type: object additionalProperties: true additionalProperties: false description: Config for `send_interactive` nodes. WorkflowNodeWaitForResponseConfig: type: object properties: has_timeout: type: boolean description: Whether the wait step automatically times out. timeout_seconds: type: - integer - 'null' description: Timeout duration in seconds when `has_timeout` is true. save_response_to: type: - string - 'null' description: Variable name where the incoming response should be stored. additionalProperties: false description: Config returned for `wait_for_response` nodes. WorkflowNodeDecideConfig: type: object required: - decision_type - conditions - llm_configuration properties: decision_type: type: string enum: - ai - function description: Whether branching is evaluated by an AI model or a Kapso function. conditions: type: array description: Ordered branch definitions for the decide step. items: $ref: '#/components/schemas/WorkflowNodeDecideCondition' llm_configuration: type: object description: Additional LLM configuration stored on the decide step. additionalProperties: true function_id: type: - string - 'null' format: uuid description: Referenced function ID when `decision_type=function`. function_name: type: - string - 'null' description: Referenced function name when `decision_type=function`. provider_model_id: type: - string - 'null' format: uuid description: Referenced model ID when `decision_type=ai`. provider_model_name: type: - string - 'null' description: Referenced model name when `decision_type=ai`. llm_temperature: type: - number - 'null' description: Sampling temperature for AI decisions. llm_max_tokens: type: - integer - 'null' description: Max output tokens for AI decisions. additionalProperties: false description: Config returned for `decide` nodes. WorkflowNodeFunctionConfig: type: object required: - function_id properties: function_id: type: string format: uuid description: Kapso Function ID to execute. function_name: type: - string - 'null' description: Function name returned by definition responses. save_response_to: type: - string - 'null' description: Variable name where the function response should be stored. additionalProperties: false description: Config for `function` nodes. WorkflowNodeWebhookConfig: type: object required: - url properties: url: type: string format: uri description: External URL to call. method: type: string enum: - GET - POST - PUT - PATCH - DELETE default: POST headers: oneOf: - type: object additionalProperties: type: string - type: string description: >- HTTP headers. Object form is preferred; definition responses may contain JSON strings for legacy webhook actions. body_template: description: >- Request body template. Object form is preferred; definition responses may contain JSON strings for legacy webhook actions. provider_model_id: type: - string - 'null' format: uuid provider_model_name: type: - string - 'null' ai_field_config: type: object additionalProperties: true save_response_to: type: - string - 'null' description: Variable name where the webhook response should be stored. additionalProperties: false description: Config for `webhook` nodes. WorkflowNodeAgentConfig: type: object properties: system_prompt: type: - string - 'null' provider_model_id: type: - string - 'null' format: uuid provider_model_name: type: - string - 'null' temperature: type: - number - 'null' max_iterations: type: - integer - 'null' max_tokens: type: - integer - 'null' reasoning_effort: type: - string - 'null' enum: - none - minimal - low - medium - high - xhigh - null observer_prompt_mode: type: string enum: - analysis_only - interactive_chat description: Prompt orchestration mode used by the flow agent. message_delivery_mode: type: string enum: - auto_send_assistant_text - tool_only default: auto_send_assistant_text description: > Controls how assistant text becomes user-visible. - `auto_send_assistant_text`: normal assistant text responses are sent to the WhatsApp user automatically. - `tool_only`: normal assistant text is internal only; the agent must call `send_notification_to_user` to send user-visible messages. enabled_default_tools: type: array items: type: string description: Built-in agent tools enabled for this node. flow_agent_function_tools: type: array items: $ref: '#/components/schemas/WorkflowNodeAgentFunctionTool' flow_agent_webhooks: type: array items: $ref: '#/components/schemas/WorkflowNodeAgentWebhook' flow_agent_knowledge_bases: type: array items: $ref: '#/components/schemas/WorkflowNodeAgentKnowledgeBase' flow_agent_mcp_servers: type: array items: $ref: '#/components/schemas/WorkflowNodeAgentMcpServer' flow_agent_resources: type: array items: $ref: '#/components/schemas/WorkflowNodeAgentResource' additionalProperties: false description: Config returned for `agent` nodes. WorkflowNodeCallConfig: type: object properties: workflow_id: type: - string - 'null' format: uuid description: ID of the called workflow. workflow_name: type: - string - 'null' description: Name of the called workflow. save_error_to: type: - string - 'null' description: Variable name where child-workflow errors should be stored. additionalProperties: false description: Config returned for `call` nodes. WorkflowNodeHandoffConfig: type: object properties: reason: type: - string - 'null' description: Optional reason stored with the handoff event. context_data: description: >- Optional context payload made available to the human handoff process. additionalProperties: false description: Config for `handoff` nodes. WorkflowNodeSetVariableConfig: type: object required: - variable_name - variable_value properties: variable_name: type: string description: Workflow variable name to set. variable_value: description: Value to store. Strings support variable interpolation. value_type: type: string enum: - string - number - boolean - json default: string description: Value coercion mode. additionalProperties: false description: Config for `set_variable` nodes. WorkflowNodeInteractiveButton: type: object required: - id - title properties: id: type: string description: Stable button payload ID. title: type: string maxLength: 20 description: Button label shown to the user. additionalProperties: false WorkflowNodeInteractiveListSection: type: object required: - rows properties: title: type: string rows: type: array items: $ref: '#/components/schemas/WorkflowNodeInteractiveListRow' additionalProperties: false WorkflowNodeDecideCondition: type: object required: - id - label properties: id: type: string format: uuid description: Condition identifier. label: type: string description: Edge label emitted by this condition. example: qualified description: type: - string - 'null' description: Human-readable condition description. additionalProperties: false description: A branch option inside a decide step. WorkflowNodeAgentFunctionTool: type: object properties: name: type: string description: type: - string - 'null' function_id: type: - string - 'null' format: uuid function_name: type: - string - 'null' input_schema: type: object description: JSON Schema-like input contract exposed to the agent. additionalProperties: true additionalProperties: false description: Function tool attached to an agent node. WorkflowNodeAgentWebhook: type: object properties: name: type: string description: type: - string - 'null' url: type: - string - 'null' description: URL the agent can call. http_method: type: - string - 'null' description: HTTP method used for the request. headers: type: - object - 'null' additionalProperties: true body: description: Request body template. body_schema: type: - object - 'null' description: Optional schema describing the request/response payload. additionalProperties: true jmespath_query: type: - string - 'null' description: Optional JMESPath projection applied to the response. ai_field_config: type: object description: AI field-resolution settings for dynamic fields. additionalProperties: true additionalProperties: false description: Custom webhook tool attached to an agent node. WorkflowNodeAgentKnowledgeBase: type: object properties: name: type: string description: type: - string - 'null' knowledge_base_text: type: - string - 'null' description: Inline knowledge base content available to the agent. additionalProperties: false description: Inline knowledge base attached to an agent node. WorkflowNodeAgentMcpServer: type: object properties: name: type: string description: type: - string - 'null' url: type: - string - 'null' description: MCP server base URL. headers: type: - object - 'null' additionalProperties: true additionalProperties: false description: MCP server definition attached to an agent node. WorkflowNodeAgentResource: type: object properties: id: type: - string - 'null' format: uuid description: Resource ID returned by definition responses. resource_type: type: string enum: - github_repository description: Resource type. v1 supports GitHub repositories. repo_url: type: string description: GitHub repository URL. example: https://github.com/org/repo owner: type: - string - 'null' description: Repository owner returned by definition responses. repo_name: type: - string - 'null' description: Repository name returned by definition responses. branch: type: - string - 'null' description: Branch to clone. Defaults to the repository default branch. pat: type: - string - 'null' description: >- GitHub Personal Access Token. Accepted on write; never returned by the API. has_pat: type: - boolean - 'null' description: Returned when credentials are stored for the resource. imported_missing_pat: type: - boolean - 'null' description: >- Returned when an imported resource references credentials that were not present in the write payload. additionalProperties: false description: Repository resource mounted into an agent sandbox. WorkflowNodeInteractiveListRow: type: object required: - id - title properties: id: type: string title: type: string maxLength: 24 description: type: string maxLength: 72 additionalProperties: false responses: UnauthorizedError: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````