When you need to string together multiple agent actions, install software, configure a browser, and validate the result, managing individual task runs quickly gets messy. The Workflows API gives you a versioned JSON DSL to define multi-step automations, handle conditional branches, implement retries, and pause for human approval all in a single workflow definition. You then POST a workflow and let the server drive the agent to completion, receiving states like queued, running, succeeded, or failed. This post shows you how to structure a workflow, spin up a run, and monitor its progress.
The Workflows DSL in a nutshell
- POST /v1/workflows creates a versioned workflow (JSON DSL).
- POST /v1/workflows/{id}/runs or POST /v1/workflows/runs launches a workflow run.
- Step types include task, assert, if, loop, parallel, human_approval, retry, succeed, fail.
- Variables are double-braced like {{inputs.name}} or stepId.field.
- Hard guards include budget_cents, max_iterations, and deadline_seconds.
- Task steps are billed $0.05 each.
How it works
You first POST /v1/workflows to define your automation. The payload contains a versioned workflow object with steps and any hard guards. Then you POST /v1/workflows/{id}/runs (or POST /v1/workflows/runs for an ad-hoc inline workflow) with machine_id, cua_version (default v3, v4 is autonomous with pass/fail), optional instructions appended to the base prompt, system_prompt, max_steps, deadline_seconds, on_awaiting_human ('pause', 'fail', or 'cancel'), and webhook_url. The server returns a run object with id, status (queued, running, awaiting_human, succeeded, failed, cancelled, timed_out), and other run-level fields. You can stream events with GET /v1/runs/{id}/events using Last-Event-ID for reconnection.
curl -s -X POST https://coasty.ai/v1/workflows \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version": 1,
"hard_guards": {
"budget_cents": 500,
"max_iterations": 100,
"deadline_seconds": 3600
},
"steps": [
{
"id": "install_chrome",
"type": "task",
"description": "Install Google Chrome",
"cua_version": "v3"
},
{
"id": "open_chrome",
"type": "task",
"description": "Open Chrome and navigate to https://example.com",
"cua_version": "v3"
},
{
"id": "verify_title",
"type": "assert",
"condition": {
"type": "string_contains",
"field": "run.outputs.open_chrome.outputs.page_title",
"value": "Example Domain"
}
},
{
"id": "screenshot",
"type": "task",
"description": "Take a screenshot of the page",
"cua_version": "v3"
},
{
"id": "upload_screenshot",
"type": "task",
"description": "Upload screenshot to S3",
"cua_version": "v3"
},
{
"id": "notify_success",
"type": "task",
"description": "Send Slack notification",
"cua_version": "v3"
},
{
"id": "finish",
"type": "succeed"
}
]
}'Launch and monitor a workflow run
- POST /v1/workflows/{id}/runs starts the workflow with machine_id and optional parameters.
- GET /v1/runs/{id} returns the current status and fields.
- GET /v1/runs/{id}/events streams Server-Sent Events; reconnect with Last-Event-ID.
- States include queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- You can cancel a run with POST /v1/runs/{id}/cancel or resume with POST /v1/runs/{id}/resume.
POST /v1/workflows/{id}/runs and GET /v1/runs/{id}/events are the core operations for launching and monitoring multi-step automations.
Where this beats brittle automation
Traditional automation relies on brittle selectors, XPath, or API endpoints that might change without notice. The Workflows API lets you describe what to do in natural language instructions, and the computer use agent sees the screen and acts like a human, clicking, typing, navigating, and validating visually. This approach handles layout shifts, new UI elements, and unexpected errors gracefully, because the agent reasons about the current state rather than brittle selectors. Plus, the workflow DSL captures the full intent (task, assert, if, loop, parallel, human_approval, retry), making your automation intent clear and versionable.
Now you can model complex, multi-step automations as versioned workflows, launch runs with POST /v1/workflows/{id}/runs, and monitor progress via GET /v1/runs/{id} and GET /v1/runs/{id}/events. Task steps are billed $0.05 each, and hard guards keep runs within budget and time limits. Ready to build your first multi-step computer use agent workflow? Get an API key at https://coasty.ai/developers and start orchestrating at scale.
Want to see this in action?
View Case Studies