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

# Flows API Reference

> Complete API documentation for Flows endpoints

## GET /public/workflows

List available workflows for your organization.

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(
      "https://catalogapi.rastro.ai/api/public/workflows",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"limit": 50, "offset": 0}
  )
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl "https://catalogapi.rastro.ai/api/public/workflows?limit=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

### Query Parameters

| Parameter | Type    | Default | Description                                 |
| --------- | ------- | ------- | ------------------------------------------- |
| `search`  | string  | —       | Case-insensitive search on name/description |
| `limit`   | integer | 50      | Items per page (1–100)                      |
| `offset`  | integer | 0       | Items to skip                               |

### Response

```json theme={null}
{
  "workflows": [
    {"id": "wf_123", "name": "Enrich Products", "description": "..."}
  ],
  "total": 5
}
```

***

## POST /public/workflows/{workflow_id}/execute

Start a flow execution with input data.

<CodeGroup>
  ```python Python theme={null}
  import requests

  FLOW_ID = "your-flow-id"

  response = requests.post(
      f"https://catalogapi.rastro.ai/api/public/workflows/{FLOW_ID}/execute",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "input": [
              {"sku": "A1", "title": "Product A"}
          ]
      }
  )
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl -X POST "https://catalogapi.rastro.ai/api/public/workflows/{workflow_id}/execute" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": [
        {"sku": "A1", "title": "Product A"}
      ],
      "cancel_existing": false
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`https://catalogapi.rastro.ai/api/public/workflows/${workflowId}/execute`, {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      input: [{ sku: "A1", title: "Product A" }]
    })
  });
  ```
</CodeGroup>

### Request Parameters

| Parameter         | Type    | Required | Description                                                                       |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------- |
| `input`           | array   | Yes      | Array of objects to process                                                       |
| `cancel_existing` | boolean | No       | Cancel currently running executions for this workflow before starting the new one |

### Response

```json theme={null}
{
  "workflow_run_id": "run_abc123",
  "workflow_id": "wf_123",
  "workflow_name": "Enrich Products",
  "status": "running",
  "created_at": "2026-06-29T12:00:00Z",
  "poll_url": "/api/public/workflows/runs/run_abc123",
  "workflow_url": "https://dashboard.rastro.ai/flows/wf_123/edit",
  "total_nodes": 3,
  "message": "Workflow execution started"
}
```

| Field             | Type    | Description                       |
| ----------------- | ------- | --------------------------------- |
| `workflow_run_id` | string  | Run ID for status polling         |
| `workflow_id`     | string  | Workflow that is executing        |
| `workflow_name`   | string  | Workflow display name             |
| `status`          | string  | `"running"`                       |
| `poll_url`        | string  | API URL for polling               |
| `workflow_url`    | string  | Dashboard URL for the flow editor |
| `total_nodes`     | integer | Number of nodes in the run        |
| `message`         | string  | Human-readable status             |

***

## GET /public/workflows/runs/{workflow_run_id}

Check the status of a flow run and retrieve results.

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(
      f"https://catalogapi.rastro.ai/api/public/workflows/runs/{workflow_run_id}",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  print(response.json())
  ```

  ```bash cURL theme={null}
  curl "https://catalogapi.rastro.ai/api/public/workflows/runs/{workflow_run_id}" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(`https://catalogapi.rastro.ai/api/public/workflows/runs/${workflowRunId}`, {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  });
  console.log(await response.json());
  ```
</CodeGroup>

### Query Parameters

| Parameter   | Type    | Default | Description                   |
| ----------- | ------- | ------- | ----------------------------- |
| `page`      | integer | `1`     | Page number for final results |
| `page_size` | integer | `50`    | Results per page              |

### Response (running)

```json theme={null}
{
  "workflow_run_id": "run_abc123",
  "workflow_id": "wf_123",
  "workflow_name": "Enrich Products",
  "workflow_url": "https://dashboard.rastro.ai/flows/wf_123/edit",
  "status": "running",
  "progress": 0.5,
  "current_step": "processing",
  "message": "Processing records",
  "created_at": "2026-06-29T12:00:00Z",
  "updated_at": "2026-06-29T12:01:00Z",
  "completed_at": null,
  "updates": ["Processing record 25/50"],
  "results": null,
  "node_results": null
}
```

### Response (completed)

```json theme={null}
{
  "workflow_run_id": "run_abc123",
  "workflow_id": "wf_123",
  "workflow_name": "Enrich Products",
  "workflow_url": "https://dashboard.rastro.ai/flows/wf_123/edit",
  "status": "completed",
  "progress": 1,
  "current_step": "completed",
  "message": "Workflow completed",
  "created_at": "2026-06-29T12:00:00Z",
  "updated_at": "2026-06-29T12:03:00Z",
  "completed_at": "2026-06-29T12:03:00Z",
  "results": {
    "data": [
      {"sku": "A1", "title": "Product A", "enriched_field": "..."},
      {"sku": "A2", "title": "Product B", "enriched_field": "..."}
    ],
    "total": 2,
    "page": 1,
    "page_size": 50,
    "has_more": false
  },
  "node_results": {
    "node_abc": {
      "node_type": "attribute_mapper",
      "data": [{"sku": "A1", "enriched_field": "..."}],
      "total": 2,
      "page": 1,
      "page_size": 50,
      "has_more": false
    }
  }
}
```

### Response Fields

| Field          | Type   | Description                                                                          |
| -------------- | ------ | ------------------------------------------------------------------------------------ |
| `status`       | string | Current status                                                                       |
| `progress`     | number | Progress from 0 to 1 (when running)                                                  |
| `current_step` | string | Current workflow step                                                                |
| `message`      | string | Latest status message                                                                |
| `updates`      | array  | Recent progress update messages                                                      |
| `results`      | object | Final paginated result set with `data`, `total`, `page`, `page_size`, and `has_more` |
| `node_results` | object | Per-node paginated outputs keyed by node ID                                          |

***

## Status Values

| Status      | Description                |
| ----------- | -------------------------- |
| `running`   | Flow is processing         |
| `completed` | Flow finished successfully |
| `failed`    | Flow failed                |
| `cancelled` | Flow was cancelled         |