Runs

Create Run

Creates a new workflow run in submitted status from either a self-contained legacy manifest or an immutable workflow-version intent. Creation does not start or schedule the run.

Failures return the standard error body. The intent lane responds 404 (workflow_version_not_found, environment_not_found), 422 (run_intent_invalid, target_invalid, target_environment_unsupported, workflow_version_unusable, run_compile_invalid), 503 (integration_unavailable), or 500 (workflow_version_store_error, credential_store_error, variable_store_error, run_persistence_failed).

post/api/v1/runs

Request body

Example request

{
  "version": 1,
  "parent_id": "01HV6D7S5YF4Z4B2M7K4N0Q6T8",
  "title": "Add rate limiting to auth endpoints",
  "cwd": "/tmp/project",
  "git": {
    "origin_url": "https://github.com/acme/my-app.git",
    "branch": "feature/foo",
    "sha": "abc123def"
  },
  "target": {
    "path": ".fabro/workflows/smoke/workflow.fabro"
  }
}

Response

Run created

idstring required

parent_idstring nullable

Current orchestration parent run ID, if linked.

children_countinteger required

Number of runs currently linked to this run as their orchestration parent.

titlestring required

goalstring required

labelsobject required

source_directorystring nullable required

size'XS' | 'S' | 'M' | 'L' | 'XL' required

Run size bucket derived from current best-effort billed usage.

superseded_bystring nullable required

Run ID that superseded this run via rewind, if any.

retried_fromstring nullable required

Source run ID when this run was created by manual retry.

Example response

{
  "repository": {
    "name": "fabro-sh/fabro",
    "origin_url": "https://github.com/fabro-sh/fabro.git"
  },
  "lifecycle": {
    "error": {
      "message": "Stage 'apply-changes' exceeded maximum retries."
    }
  },
  "timing": {
    "wall_time_ms": 420000,
    "inference_time_ms": 120000,
    "tool_time_ms": 60000,
    "active_time_ms": 180000
  },
  "diff": {
    "files_changed": 42,
    "additions": 567,
    "deletions": 234
  },
  "pull_request": {
    "owner": "fabro-sh",
    "repo": "fabro",
    "number": 123,
    "html_url": "https://github.com/fabro-sh/fabro/pull/123"
  },
  "current_question": {
    "text": "Accept or push for another round?"
  }
}

Changes

Changed in 28 of the 134 revisions of this API.142542

Aug 26, 202613262755c97f1See the full diff
- ○
  added the new optional request property oneOf[RunIntent]/target/oneOf[GitRunTarget]/tag
  new-optional-request-property
Aug 26, 2026e7fd6d8532042See the full diff
- ○
  added folder discriminator mapping keys to the oneOf[RunIntent]/target request property
  request-property-discriminator-mapping-added
- ○
  added FolderRunTarget to the oneOf[RunIntent]/target request property oneOf list
  request-property-one-of-added
Aug 25, 20269abd94e6cfbe2See the full diff
- ○
  added none discriminator mapping keys to the oneOf[RunIntent]/target request property
  request-property-discriminator-mapping-added
- ○
  added NoneRunTarget to the oneOf[RunIntent]/target request property oneOf list
  request-property-one-of-added
Aug 24, 20265290add6d36f11See the full diff
- ▲
  removed NoneRunTarget from the oneOf[RunIntent]/target request property oneOf list
  request-property-one-of-removed
- ○
  removed none discriminator mapping keys from the oneOf[RunIntent]/target request property
  request-property-discriminator-mapping-deleted
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 23, 2026cfd12cf45afb6See the full diff
- ○
  added none discriminator mapping keys to the oneOf[RunIntent]/target request property
  request-property-discriminator-mapping-added
- ○
  added NoneRunTarget to the oneOf[RunIntent]/target request property oneOf list
  request-property-one-of-added
- ○
  removed the non-success response with the status 404
  response-non-success-status-removed
- ○
  removed the non-success response with the status 422
  response-non-success-status-removed
- ○
  removed the non-success response with the status 500
  response-non-success-status-removed
- ○
  removed the non-success response with the status 503
  response-non-success-status-removed
Aug 21, 20266ed5f1557b9b1105See the full diff
- ▲
  the request's body type/format changed from object/ to /
  request-body-type-changed
- ●
  removed the request property args
  request-property-removed
- ●
  removed the request property configs
  request-property-removed
- ●
  removed the request property cwd
  request-property-removed
- ●
  removed the request property git
  request-property-removed
- ●
  removed the request property goal
  request-property-removed
- ●
  removed the request property parent_id
  request-property-removed
- ●
  removed the request property target
  request-property-removed
- ●
  removed the request property title
  request-property-removed
- ●
  removed the request property version
  request-property-removed
- ●
  removed the request property workflows
  request-property-removed
- ○
  added RunManifest RunIntent to the request body oneOf list
  request-body-one-of-added
- ○
  added the non-success response with the status 404
  response-non-success-status-added
- ○
  added the non-success response with the status 422
  response-non-success-status-added
- ○
  added the non-success response with the status 500
  response-non-success-status-added
- ○
  added the non-success response with the status 503
  response-non-success-status-added
Aug 4, 2026bee0300538234See the full diff
- ●
  removed the request property git/push_outcome
  request-property-removed
- ●
  removed the request property goal/path
  request-property-removed
- ●
  removed the request property run_id
  request-property-removed
- ●
  removed the request property target/identifier
  request-property-removed
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 4, 2026359433692f0622See the full diff
- ▲
  added the new required request property git/push_outcome
  new-required-request-property
- ▲
  added the new required request property target/identifier
  new-required-request-property
- ○
  added the new optional request property goal/path
  new-optional-request-property
- ○
  added the new optional request property run_id
  new-optional-request-property
Aug 3, 20263a47e2b7312f1See the full diff
- ●
  removed the request property git/push_outcome
  request-property-removed
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 3, 2026d0531013c74c2See the full diff
- ●
  removed the request property goal/path
  request-property-removed
- ●
  removed the request property target/identifier
  request-property-removed

Full history (28 revisions)