# Working with Flows

## Learn how to create, manage, and monitor flows using the Donobu API. Includes examples for different use cases.

### Creating Flows

Flows are the core concept in Donobu - they represent automated sequences of browser interactions to accomplish a specific objective.

#### Basic Autonomous Flow

This example creates a flow that autonomously navigates and performs actions:

```bash
curl -X POST http://localhost:31000/api/flows \
-H "Content-Type: application/json" \
-d '{
"name": "Product Search Flow",
"targetWebsite": "https://example-ecommerce.com",
"overallObjective": "Search for wireless headphones, filter by price under $100, and add the first result to cart",
"initialRunMode": "AUTONOMOUS",
"browser": {
"using": {
"type": "device",
"headless": false
}
},
"maxToolCalls": 20
}'
```

#### Deterministic Flow with Predefined Actions

For repeatable automation, you can define specific actions upfront:

```bash
curl -X POST http://localhost:31000/api/flows \
-H "Content-Type: application/json" \
-d '{
"name": "Login Sequence",
"targetWebsite": "https://app.example.com/login",
"initialRunMode": "DETERMINISTIC",
"envVars": ["USER_EMAIL", "USER_PASSWORD"],
"toolCallsOnStart": [\
{\
"name": "click",\
"parameters": {\
"selector": "#email-input"\
}\
},\
{\
"name": "type",\
"parameters": {\
"text": "${USER_EMAIL}"\
}\
},\
{\
"name": "click",\
"parameters": {\
"selector": "#password-input"\
}\
},\
{\
"name": "type",\
"parameters": {\
"text": "${USER_PASSWORD}"\
}\
},\
{\
"name": "click",\
"parameters": {\
"selector": "#login-button"\
}\
}\
]
}'
```

### Monitoring Flow Execution

#### Getting Flow Status

```bash
# Get detailed flow information
curl -X GET http://localhost:31000/api/flows/{flowId}
```

The response includes:

- Current execution state (RUNNING, SUCCESS, FAILED, etc.)
- Progress information
- Token usage
- Start and completion times

#### Listing All Flows

```bash
# Get all flows
curl -X GET http://localhost:31000/api/flows

# Filter flows by state
curl -X GET "http://localhost:31000/api/flows?state=RUNNING"

# Filter flows by date range
curl -X GET "http://localhost:31000/api/flows?startedAfter=1640995200000&limit=10"
```

### Flow States

Understanding flow states helps monitor execution:

- **UNSTARTED**: Flow created but not yet initialized
- **INITIALIZING**: Setting up browser context and initial state
- **RUNNING_ACTION**: Executing a tool call
- **QUERYING_LLM_FOR_NEXT_ACTION**: AI determining next action (AUTONOMOUS mode)
- **WAITING_ON_USER_FOR_NEXT_ACTION**: Waiting for user input (INSTRUCT mode)
- **PAUSED**: Flow execution temporarily suspended
- **RESUMING**: Transitioning from paused to active state
- **FAILED**: Flow terminated unsuccessfully
- **SUCCESS**: Flow completed successfully

### Retrieving Flow Data

#### Getting Tool Calls

View all actions performed during a flow:

```bash
curl -X GET http://localhost:31000/api/flows/{flowId}/tool-calls
```

#### Getting Screenshots

Retrieve screenshots taken during flow execution:

```bash
curl -X GET http://localhost:31000/api/flows/{flowId}/images/{imageId} \
--output screenshot.png
```

#### Getting Video Recording

Download the complete video of the flow execution:

```bash
curl -X GET http://localhost:31000/api/flows/{flowId}/video \
--output flow-recording.webm
```

### Rerunning Flows

#### Get Rerun Configuration

Generate a configuration to rerun a completed flow:

```bash
curl -X GET http://localhost:31000/api/flows/{flowId}/rerun
```

This returns a `CreateDonobuFlow` object that can be used to create an identical flow.

#### Rerun with Modifications

```bash
# Get the rerun configuration
RERUN_CONFIG=$(curl -s -X GET http://localhost:31000/api/flows/{flowId}/rerun)

# Modify and create new flow
echo $RERUN_CONFIG | jq '.name = "Rerun - Modified"' | \
curl -X POST http://localhost:31000/api/flows \
-H "Content-Type: application/json" \
-d @-
```

### Generating Test Code

#### Convert Flow to Playwright Script

```bash
curl -X GET http://localhost:31000/api/flows/{flowId}/code \
--output test-script.js
```

#### Generate Complete Test Project

Create a full Playwright project from multiple flows:

```bash
curl -X POST http://localhost:31000/api/flows/project \
-H "Content-Type: application/json" \
-d '{
"flowIds": ["flow-id-1", "flow-id-2", "flow-id-3"],
"options": {
"runInHeadedMode": true,
"slowMotionDelay": 100,
"disableSelfHealingTests": false,
"playwrightScriptVariant": "ai"
}
}' \
--output playwright-project.zip
```