Deploy and run
Durable workflows
Run multi-step jobs that call your apps, wait for events and retry until they're done, even across restarts and deploys.
Some jobs take several steps and must finish: charge a card, wait for the warehouse, then email the customer. A workflow runs those steps for you, saves each result before the next, and picks up where it left off after a crash or a deploy.
How to do it: describe the steps (call your app, wait, retry, send an email) in project settings under Workflows, or ask your agent.
"Make a workflow that emails new users on day 1, 3 and 7."
Some jobs take more than one request and must finish: charge a card, then wait for the warehouse, then email the customer; onboard a user over three days; retry a flaky partner API until it answers. A workflow runs those steps for you. It saves every step's result before starting the next, so a run picks up where it left off after a restart, a deploy or an outage, with no queue or cron to manage.
Steps
| Type | What it does |
|---|---|
http | Calls one of the project's apps (service) or any url over https, and saves the status and JSON body |
sleep | Waits seconds (up to 30 days) without using anything |
wait | Pauses until an event is sent to the run, or fails after timeoutSeconds |
An http step retries failures (non-2xx, timeouts) retries times, three by default. The wait between tries starts at backoffSeconds (10) and doubles each time. Every try of a step carries the same Idempotency-Key header, so make the endpoint ignore a key it has already handled, and a retry can never charge twice.
Define one
PUT /v1/projects/:id/workflows/order{
"steps": [
{ "name": "charge", "type": "http", "service": "api", "path": "/charge", "body": { "order": "{{input.orderId}}", "amount": "{{input.amount}}" } },
{ "name": "shipped", "type": "wait", "event": "order.shipped", "timeoutSeconds": 604800 },
{ "name": "email", "type": "http", "service": "api", "path": "/emails/shipped", "body": { "charge": "{{steps.charge.body.id}}", "tracking": "{{steps.shipped.data.tracking}}" } }
]
}Templates fill in values: {{input.x}} from the run's input, {{steps.<name>.body.x}} from an earlier HTTP step's response, {{steps.<name>.data.x}} from an event, and {{run.id}}. A value that is exactly one template keeps its type, so a number stays a number. Add "when": "{{steps.lookup.body.vip}}" to a step to skip it when the value is false, empty or missing.
Add "schedule": "0 9 * * 1" (five-field cron, UTC) to start a run on a schedule.
Run it
POST /v1/workflows/:id/runs {"input": {"orderId": "o_1", "amount": 1999}, "idempotencyKey": "o_1"}
POST /v1/workflow-runs/:runId/events {"name": "order.shipped", "data": {"tracking": "1Z999"}}
GET /v1/workflow-runs/:runIdThe same idempotencyKey (or Idempotency-Key header) returns the existing run instead of starting another. That makes it safe to start runs from webhooks that may be delivered twice. Your app sends events to a run with its API key.
GET on a run shows each step's result and a log of every try. A failed run raises workflow_failed; fix the cause, then POST /v1/workflow-runs/:id/retry carries on from the step that failed, keeping earlier results. cancel stops a run.
Cost
Each HTTP step that runs costs a hundredth of a cent from the project's credit (the operator can change this). Sleeping and waiting are free. Agents use cli_workflow.