Sign in
Runs

Create Run

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

Failures return the standard error body. The endpoint responds 404 (workflow_version_not_found, environment_not_found), 422 (run_intent_invalid, target_invalid, target_environment_unsupported, pull_request_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

workflow_version_idstring required

SHA-256 identity of validated canonical workflow-version bytes. Hex input is case-insensitive; Fabro emits the canonical lowercase form.

environment_idstring

Server environment catalog ID. Omission selects default.

parent_idstring

Optional orchestration parent run ID.

titlestring

Optional explicit run title, normalized by the server.

goalstring

Optional inline goal override.

Example request

{
  "workflow_version_id": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "target": {
    "repo": "acme/my-app",
    "branch": "feature/foo",
    "tag": "v1.2.3"
  }
}

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 the run's current cost.

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."
    }
  },
  "sandbox": {
    "plan": {
      "provider": "docker"
    },
    "instance": {
      "provider": "docker"
    }
  },
  "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