> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows API

> Manage and execute durable multi-step workflows

## Workflow Definitions

Endpoints for managing workflow definitions.

| Method   | Endpoint                            | Description                           |
| -------- | ----------------------------------- | ------------------------------------- |
| `POST`   | `/api/v1/workflows`                 | Create a new workflow                 |
| `GET`    | `/api/v1/workflows`                 | List all workflows                    |
| `GET`    | `/api/v1/workflows/:id`             | Get workflow by ID                    |
| `PUT`    | `/api/v1/workflows/:id`             | Update workflow (creates new version) |
| `DELETE` | `/api/v1/workflows/:id`             | Disable workflow                      |
| `POST`   | `/api/v1/workflows/validate`        | Validate definition without saving    |
| `GET`    | `/api/v1/workflows/:id/versions`    | List all versions                     |
| `GET`    | `/api/v1/workflows/:id/versions/:v` | Get specific version                  |

### Create Workflow

**Request Body**

```json theme={null}
{
  "workflowId": "incident-rca",
  "name": "Incident Root Cause Analysis",
  "description": "Parallel investigation with synthesis",
  "definition": {
    "id": "incident-rca",
    "start": "investigate",
    "states": [...]
  }
}
```

## Workflow Runs

Endpoints for executing workflows and tracking their progress.

| Method | Endpoint                           | Description                                   |
| ------ | ---------------------------------- | --------------------------------------------- |
| `POST` | `/api/v1/workflow-runs`            | Start a new run                               |
| `GET`  | `/api/v1/workflow-runs`            | List runs (filter by `workflow_id`, `status`) |
| `GET`  | `/api/v1/workflow-runs/:id`        | Get run status and output                     |
| `GET`  | `/api/v1/workflow-runs/:id/stream` | SSE stream of run updates                     |
| `GET`  | `/api/v1/workflow-runs/:id/steps`  | List completed steps                          |
| `POST` | `/api/v1/workflow-runs/:id/pause`  | Pause execution                               |
| `POST` | `/api/v1/workflow-runs/:id/resume` | Resume paused run                             |
| `POST` | `/api/v1/workflow-runs/:id/cancel` | Cancel run                                    |

### Start Run

**Request Body**

```json theme={null}
{
  "workflowId": "incident-rca",
  "input": {
    "service_name": "payment-service",
    "namespace": "production"
  }
}
```

### Streaming Updates (SSE)

The `/api/v1/workflow-runs/:id/stream` endpoint provides a server-sent events (SSE) stream of run updates.

**Events:**

* `run_started`: Emitted when the run begins
* `step_started`: Emitted when a step begins execution
* `step_completed`: Emitted when a step finishes
* `run_completed`: Emitted when the entire workflow finishes
* `run_failed`: Emitted if an error occurs

## Human Approvals

Endpoints for managing `human_approval` steps in workflows.

| Method | Endpoint                                 | Description                   |
| ------ | ---------------------------------------- | ----------------------------- |
| `GET`  | `/api/v1/workflow-approvals`             | List pending approvals        |
| `GET`  | `/api/v1/workflow-approvals/:id`         | Get approval details          |
| `POST` | `/api/v1/workflow-approvals/:id/approve` | Approve with optional comment |
| `POST` | `/api/v1/workflow-approvals/:id/reject`  | Reject with reason            |

### Approve Request

**Request Body**

```json theme={null}
{
  "comment": "Reviewed and approved for production rollout"
}
```

<Note>
  Set `X-Approver-ID` header to identify the approver. Defaults to `api-user` if not provided.
</Note>