All requests require an API key in the X-API-Key header. See API Reference for authentication details.
Run Flows
Trigger flow execution. Returns a batch_id to poll via Run Status.
POST /api/v1/flows/run — Returns 200 OK
Request Body
App bundle identifier (mobile). Required if app_id is not provided.
ios or android. Required with bundle_id.
Web app identifier. Required if bundle_id is not provided.
Suite UUIDs to run. At least one of suite_ids or flow_ids is required.
Flow UUIDs to run. At least one of suite_ids or flow_ids is required.
Key-value variables to attach to the active build and inject into flow instructions via ${env:KEY}. Accepts a string ("KEY1=VALUE1,KEY2=VALUE2") or a JSON object ({"KEY1": "VALUE1"}). See Build Variables. Example Request
curl -X POST https://backend.autosana.ai/api/v1/flows/run \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"bundle_id": "com.company.app",
"platform": "android",
"suite_ids": ["550e8400-e29b-41d4-a716-446655440000"],
"variables": "PR_NUMBER=42,BRANCH=feature/login"
}'
Example Response
{
"status": "success",
"batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"flow_group_run_ids": ["f1a2b3c4-d5e6-7890-abcd-ef1234567890"],
"flow_run_count": 5
}
Run Status
Poll execution status for a batch triggered by Run Flows.
GET /api/v1/runs/status — Returns 200 OK
Query Parameters
The batch_id from /api/v1/flows/run.
Example Request
curl -X GET "https://backend.autosana.ai/api/v1/runs/status?batch_id=BATCH_ID" \
-H "X-API-Key: YOUR_API_KEY"
Example Response
{
"batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"is_complete": true,
"timestamp": "2025-01-31T12:34:56.789Z",
"app": {
"id": "com.company.app",
"name": "My App",
"platform": "android",
"url": "https://storage.example.com/builds/app.apk"
},
"git": {
"commit_sha": "abc123",
"branch": "main"
},
"summary": {
"total_groups": 2,
"passed_groups": 1,
"failed_groups": 1,
"total_flows": 10,
"passed_flows": 8,
"failed_flows": 2,
"error_flows": 0,
"terminated_flows": 0,
"skipped_flows": 0
},
"run_groups": [
{
"name": "Login Suite",
"status": "passed",
"url": "https://autosana.ai/runs/groups/group-uuid-1",
"runs": [
{
"id": "run-uuid-1",
"name": "Login with valid credentials",
"status": "passed",
"url": "https://autosana.ai/runs/flow/run-uuid-1",
"summary": "Successfully logged in and verified the dashboard loaded."
}
]
},
{
"name": "Checkout Suite",
"status": "failed",
"url": "https://autosana.ai/runs/groups/group-uuid-2",
"runs": [
{
"id": "run-uuid-2",
"name": "Checkout with expired card",
"status": "failed",
"url": "https://autosana.ai/runs/flow/run-uuid-2"
}
]
}
]
}
Get Run Results
Get full details of a run, including metadata, summary, and all actions with screenshot URLs. Use the id from individual runs in the Run Status response.
GET /api/v1/runs/{run_id} — Returns 200 OK
Path Parameters
UUID of the run. Available in the runs[].id field from Run Status. Example Request
curl -X GET "https://backend.autosana.ai/api/v1/runs/run-uuid-1" \
-H "X-API-Key: YOUR_API_KEY"
Example Response
{
"run_id": "run-uuid-1",
"flow_name": "Login with valid credentials",
"status": "passed",
"started_at": "2025-01-31T12:34:50.000000+00:00",
"completed_at": "2025-01-31T12:35:01.000000+00:00",
"summary": "Successfully logged in and verified the dashboard loaded.",
"issues": [
{
"type": "ux",
"severity": "minor",
"title": "No loading indicator on login",
"description": "After tapping 'Sign In', there is no visual loading state before the dashboard appears.",
"actions": [4,5]
}
],
"url": "https://autosana.ai/runs/flow/run-uuid-1",
"actions": [
{
"id": "action-uuid-1",
"position": 1,
"type": "tap",
"status": "passed",
"description": "Tap the 'Sign In' button",
"value": null,
"screenshot_url": "https://storage-path/screenshot1.png",
"annotated_screenshot_url": "https://example.com/screenshot1_annotated.png",
"executed_at": "2025-01-31T12:34:56.789000+00:00"
},
{
"id": "action-uuid-2",
"position": 2,
"type": "send_keys",
"status": "passed",
"description": "Type email into the email field",
"value": "user@example.com",
"screenshot_url": "https://storage-path/screenshot2.png",
"annotated_screenshot_url": "https://example.com/screenshot2_annotated.png",
"executed_at": "2025-01-31T12:34:58.789000+00:00"
},
{
"id": "action-uuid-3",
"position": 3,
"type": "pass",
"status": "passed",
"description": "Login completed successfully — dashboard is visible",
"value": null,
"screenshot_url": "https://storage-path/screenshot3.png",
"annotated_screenshot_url": null,
"executed_at": "2025-01-31T12:35:00.789000+00:00"
}
]
}
Polling
Poll /api/v1/runs/status every 10-15 seconds until is_complete is true.
while true; do
RESPONSE=$(curl -s "https://backend.autosana.ai/api/v1/runs/status?batch_id=$BATCH_ID" \
-H "X-API-Key: YOUR_API_KEY")
if [ "$(echo "$RESPONSE" | jq -r '.is_complete')" = "true" ]; then
echo "$RESPONSE" | jq '.summary'
break
fi
sleep 15
done
