Workflows

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/ to retrieve execution context and event history.

PATCH

workflow_executions

{execution_id}

Update workflow execution status

curl --request PATCH \
  --url https://api.kapso.ai/platform/v1/workflow_executions/{execution_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow_execution": {
    "status": "ended"
  }
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "started_at": "2023-11-07T05:31:56Z",
    "last_event_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "whatsapp_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "<string>"
    },
    "current_step": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "identifier": "<string>",
      "stepable_type": "<string>",
      "position": {
        "x": 123,
        "y": 123
      }
    },
    "error_details": {}
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

execution_id

string<uuid>

required

Execution identifier

Body

application/json

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.

workflow_execution

object

required

Show child attributes

Response

Execution status updated successfully

Minimal workflow execution response (without execution_context and events)

data

object

required

Base workflow execution schema

Show child attributes

List workflow execution eventsRetrieve events for a workflow execution in reverse chronological order (most recent first). Use `limit`, `after`, and `before` for cursor pagination. Cursors are returned in the `paging` object.

Update workflow execution status

curl --request PATCH \
  --url https://api.kapso.ai/platform/v1/workflow_executions/{execution_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workflow_execution": {
    "status": "ended"
  }
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "started_at": "2023-11-07T05:31:56Z",
    "last_event_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "tracking_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "whatsapp_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workflow": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "<string>"
    },
    "current_step": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "identifier": "<string>",
      "stepable_type": "<string>",
      "position": {
        "x": 123,
        "y": 123
      }
    },
    "error_details": {}
  }
}