POST/1.0/tasks/:taskId/runs

Starts a run of a saved task. Required scope: workbench:flows:run (scopes reference).

The response comes back as soon as the run is accepted, not when it finishes — a task can wait on a person, or on a timer, for as long as its plan says. Take the runId and check in on it.

Path parameters

taskIdstringRequired

The task to run — from GET /1.0/tasks or the Workbench UI.

Request body

inputany

What the task starts with, when it declares something to start from. Omit it for a task that doesn't.

Response (201)

runIdstring

The run you just started. Everything else about it comes from the run endpoint.

curl -X POST https://api.zerowidth.ai/1.0/tasks/cmpd9k2x10001.../runs \
  -H "Authorization: Bearer zw_live_abc12345_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reconcile-2026-09-15" \
  -d '{"input": {"week": "2026-W37"}}'

{
  "runId": "run_8fd21a9c..."
}

Uses the shared error envelope. 404 not_found when no task with that id lives in the key's workspace, 400 validation when the body doesn't match what the task expects, plus 401 and 403 scope_missing.

2 min read