Orchestrating Multi-Step Automations with the Workflows API
Automated workflows often need more than a single task. You might need to start a service, wait for it to be ready, run a test, and then roll back if it fails. The Workflows API is a versioned JSON DSL that lets you compose many steps into a single, stateful pipeline. You define all the logic once, then use the runs endpoint to execute it on real desktops, browsers, and terminals.
How the Workflows API works
You POST a workflow definition to POST /v1/workflows, receive a workflow ID, and then POST /v1/workflows/{id}/runs to start an execution. The DSL includes step types such as task, assert, if, loop, parallel, human_approval, retry, succeed, and fail. Variables can reference inputs or step outputs using {{inputs.x}} and {{stepId.field}} formats. Built-in guards include budget_cents, max_iterations, and deadline_seconds. Each task step is billed at $0.05 per agent step.
curl -X POST https://coasty.ai/v1/workflows \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "setup-and-test",
"version": "1.0.0",
"steps": [
{
"id": "start_up",
"type": "task",
"task": "Start the web server and wait for it to listen on port 8080",
"max_steps": 20
},
{
"id": "assert_ready",
"type": "assert",
"condition": {
"type": "field_equals",
"field": "start_up.status",
"value": "succeeded"
}
},
{
"id": "run_test",
"type": "task",
"task": "Run the integration test suite",
"max_steps": 50
},
{
"id": "check_test",
"type": "assert",
"condition": {
"type": "field_equals",
"field": "run_test.status",
"value": "succeeded"
}
},
{
"id": "human_ok",
"type": "human_approval",
"instruction": "Review the test results"
},
{
"id": "cleanup",
"type": "task",
"task": "Stop the web server",
"max_steps": 10
},
{
"id": "final",
"type": "succeed",
"message": "Setup and test workflow completed successfully"
}
]
}'Running a workflow
- ●POST /v1/workflows/{id}/runs accepts machine_id, task, cua_version (default 'v3', 'v4' adds pass/fail verifier), optional instructions, system_prompt, max_steps, deadline_seconds, on_awaiting_human ('pause', 'fail', or 'cancel'), and webhook_url.
- ●Each workflow run is billed at $0.05 per agent step, the same rate as a direct task step.
- ●Monitor runs via GET /v1/runs and GET /v1/runs/{id}, cancel or resume with POST /v1/runs/{id}/cancel and POST /v1/runs/{id}/resume.
- ●GET /v1/runs/{id}/events streams Server-Sent Events with a Last-Event-ID header for reconnection.
- ●Workflow states include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out.
Use POST /v1/workflows/{id}/runs to start a workflow execution, then GET /v1/runs/{id}/events to stream progress.
Why computer use beats brittle automation
Selectors and API-only tools break as soon as UI changes or APIs evolve. The computer use agent sees the screen and acts like a human: it reads text, clicks visible elements, types into fields, and watches for visual cues. When you compose those actions into a workflow, you get a versioned pipeline that runs on real desktops and browsers. You can add asserts to validate state at any step, retry loops for reliability, and human approval for sensitive actions, all without brittle selectors.
The Workflows API gives you a declarative, versioned DSL for multi-step computer use agents. Build pipelines with tasks, asserts, loops, and human approval, then run them on real VMs via /v1/workflows and /v1/workflows/{id}/runs. Ready to build your first workflow? Get an API key at https://coasty.ai/developers.