Working with Flows

[!NOTE] For a complete list of endpoints and parameters, please refer to the API Reference.

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:

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:

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

# 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

# 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:

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

Getting Screenshots

Retrieve screenshots taken during flow execution:

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:

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:

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

# 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

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:

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