> ## 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. # Update workflow execution status > Manually update the status of a workflow execution. This is useful for programmatically controlling workflow lifecycle from external systems. **Allowed status transitions:** - `ended` - End the execution immediately - `handoff` - Transfer execution to human agent - `waiting` - Pause execution until resumed **Use cases:** - End workflows based on external events - Transfer complex queries to human agents - Implement custom timeout logic - Coordinate workflows with external systems Invalid transitions (e.g., transitioning from a terminal state) will return a 422 error with details about why the transition is not allowed. **Response**: Returns full execution data including the updated status. Use GET /workflow_executions/{id} to retrieve execution context and event history. ## OpenAPI ````yaml /api/platform/v1/openapi-workflows.yaml patch /workflow_executions/{execution_id} 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: /workflow_executions/{execution_id}: parameters: - name: execution_id in: path required: true schema: type: string format: uuid description: Execution identifier patch: tags: - Workflows summary: Update workflow execution status description: > Manually update the status of a workflow execution. This is useful for programmatically controlling workflow lifecycle from external systems. **Allowed status transitions:** - `ended` - End the execution immediately - `handoff` - Transfer execution to human agent - `waiting` - Pause execution until resumed **Use cases:** - End workflows based on external events - Transfer complex queries to human agents - Implement custom timeout logic - Coordinate workflows with external systems Invalid transitions (e.g., transitioning from a terminal state) will return a 422 error with details about why the transition is not allowed. **Response**: Returns full execution data including the updated status. Use GET /workflow_executions/{id} to retrieve execution context and event history. operationId: updateWorkflowExecution requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowExecutionUpdateRequest' responses: '200': description: Execution status updated successfully content: application/json: schema: $ref: '#/components/schemas/WorkflowExecutionMinimalResponse' '400': description: Missing or invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '422': description: Invalid status transition content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Invalid transition from ended to waiting components: schemas: WorkflowExecutionUpdateRequest: type: object required: - workflow_execution properties: workflow_execution: type: object required: - status properties: status: type: string enum: - ended - handoff - waiting description: > The new status for the workflow execution. Only specific transitions are allowed based on the current state. example: ended description: > Request to update a workflow execution status. Only certain status transitions are allowed (ended, handoff, waiting). The execution will transition to the new status if the transition is valid according to the workflow state machine. WorkflowExecutionMinimalResponse: type: object required: - data properties: data: $ref: '#/components/schemas/WorkflowExecution' description: >- Minimal workflow execution response (without execution_context and events) ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message WorkflowExecution: allOf: - $ref: '#/components/schemas/WorkflowExecutionSummary' - type: object properties: error_details: type: - object - 'null' description: >- Error information when status is 'failed' (error message, stack trace, step identifier) additionalProperties: true description: Base workflow execution schema WorkflowExecutionSummary: type: object required: - id - status - started_at - last_event_at properties: id: type: string format: uuid description: Unique execution identifier status: type: string enum: - running - waiting - ended - failed - handoff description: | Execution status: - `running`: Currently executing workflow steps - `waiting`: Paused, awaiting user input or timeout - `ended`: Successfully completed - `failed`: Terminated due to error - `handoff`: Transferred to human agent started_at: type: string format: date-time description: Execution start timestamp ended_at: type: - string - 'null' format: date-time description: Execution completion timestamp, null if still active last_event_at: type: string format: date-time description: Timestamp of most recent workflow event or activity tracking_id: type: - string - 'null' format: uuid description: >- Optional external tracking identifier for correlating with external systems whatsapp_conversation_id: type: - string - 'null' format: uuid description: >- Associated WhatsApp conversation identifier, links execution to its conversation workflow: $ref: '#/components/schemas/WorkflowMinimal' current_step: $ref: '#/components/schemas/WorkflowStepReference' description: Minimal execution representation for list endpoints WorkflowMinimal: type: object required: - id - name - status properties: id: type: string format: uuid description: Workflow identifier name: type: string description: Workflow name status: type: string description: Workflow status description: Compact workflow reference used in execution objects WorkflowStepReference: type: object required: - id - identifier properties: id: type: string format: uuid description: Internal ID of the workflow step identifier: type: string description: >- Step identifier within the workflow (e.g., 'start', 'step1', 'agent_greeting') stepable_type: type: - string - 'null' description: > Ruby class name of the step type (e.g., 'FlowAgentStep', 'FlowActionStep', 'FlowWaitStep', 'FlowDecideStep') position: type: - object - 'null' description: Canvas position for visual editor properties: x: type: number 'y': type: number additionalProperties: true additionalProperties: true description: Reference to a workflow step (used in execution current_step tracking) responses: UnauthorizedError: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFoundError: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````