Orchestrating Multi-Step Automations with the Workflows API
Building complex automations with only one API endpoint means you must handle retries, conditional logic, parallel steps, and human approval all in your own code. The Workflows API lets you define that logic in a versioned JSON DSL and submit it with a single POST /v1/workflows request. The server executes steps in order, tracks variables, and manages sub-runs, so you can focus on the automation logic instead of the orchestration boilerplate.
How the Workflows API works
A workflow is a versioned JSON object that defines the steps an agent will run on each task run. The workflow itself is immutable once created. When you POST /v1/workflows you provide the workflow DSL and receive a workflow id. Then you POST /v1/workflows/{id}/runs (or POST /v1/workflows/runs for ad-hoc inline workflows) with a task payload and machine_id. The server starts a task run, steps through the workflow, and returns a run id. You can stream events with GET /v1/runs/{id}/events and inspect the final state with GET /v1/runs/{id}. Task steps are billed $0.05 each. Variables in conditions and assertions use double-brace syntax like {{inputs.x}} or stepId.field. Hard guards include budget_cents, max_iterations, and deadline_seconds.
curl -X POST https://coasty.ai/v1/workflows \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"version": "1.0",
"steps": [
{
"id": "step1",
"type": "task",
"task": "Open Chrome and go to https://example.com",
"on_awaiting_human": "pause"
},
{
"id": "step2",
"type": "assert",
"condition": {
"type": "text_present",
"selector": "body",
"expected_text": "Example Domain"
},
"on_awaiting_human": "pause"
},
{
"id": "step3",
"type": "retry",
"max_attempts": 3,
"condition": {
"type": "text_present",
"selector": "body",
"expected_text": "Example Domain"
},
"on_awaiting_human": "pause"
},
{
"id": "step4",
"type": "parallel",
"steps": [
{
"id": "sub1",
"type": "task",
"task": "Click the first link",
"on_awaiting_human": "pause"
},
{
"id": "sub2",
"type": "task",
"task": "Wait 2 seconds",
"on_awaiting_human": "pause"
}
]
},
{
"id": "step5",
"type": "succeed"
}
],
"guards": {
"budget_cents": 500,
"deadline_seconds": 300
}
}'Step types and execution behavior
- ●task: runs a computer use agent step using POST /v1/runs. Billed at $0.05 per step.
- ●assert: verifies a condition (e.g., text_present) and fails the run if the condition is not met.
- ●if: evaluates a condition and executes the trueSteps or falseSteps array.
- ●loop: iterates over steps while a condition holds, respecting max_iterations.
- ●parallel: executes multiple steps concurrently, then waits for all to finish.
- ●human_approval: pauses the workflow and sets run state to awaiting_human until you resume with POST /v1/runs/{id}/resume.
- ●retry: repeats a task step up to max_attempts when a condition fails.
- ●succeed: marks the workflow run as successful and stops further execution.
- ●fail: marks the workflow run as failed and stops further execution.
Task steps are billed $0.05 each; define guards like budget_cents and deadline_seconds to control costs.
Where this beats brittle automation
Traditional automation relies on brittle selectors and API-specific endpoints that break when UIs change. The Workflows API lets you describe the intent of each step in plain English instructions. The computer use agent sees the screen and acts like a human, so it can adapt to layout shifts, new buttons, or dynamic content without you rewriting selectors. Parallel steps let you speed up workflows by running multiple tasks at once. Human approval steps let you gate sensitive actions, and retries automatically handle transient failures. All of this is expressed in a versioned JSON DSL, so you can audit, version, and roll back workflows with confidence.
The Workflows API gives you a versioned, declarative way to orchestrate multi-step automations with retries, parallelism, and human approval built-in. Start by defining a simple workflow with a few task and assert steps, then iterate with loops and parallel sections. Get your API key at https://coasty.ai/developers and build resilient computer use agents for real desktops, browsers, and terminals.