---
title: "Create Run"
method: POST
path: "/api/v1/runs"
tags: ["Runs"]
---

# Create Run

`POST /api/v1/runs`

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`).

## Request body

- union — Transitional create body used while callers migrate independently from self-contained manifests to immutable workflow-version intents.
  - RunManifest — Self-contained workflow run manifest.
    - `version` integer, required — Manifest schema version.
    - `parent_id` string, nullable — Optional orchestration parent run ID. Fork and rewind lineage use separate fields and should not set this value.
    - `title` string, nullable — Optional explicit run title. The server trims leading/trailing whitespace, rejects blank values, rejects control characters and newline characters, and requires at most 100 characters.
    - `cwd` string, required — CLI working directory at invocation time.
    - `git` GitContext — Observable git state captured before the run starts.
      - `origin_url` string, required — Remote origin URL with any embedded credentials removed.
      - `branch` string, required — Current branch name.
      - `sha` string, nullable — Current commit SHA, when known.
      - `dirty` 'clean' | 'dirty' | 'unknown', required
    - `goal` ManifestGoal — Resolved goal kind and content.
      - `type` 'value' | 'file' | 'graph', required
      - `text` string, required — Resolved goal content.
    - `args` ManifestArgs — Sparse command-local args that affect run settings.
      - `model` string
      - `provider` string
      - `environment` string — Named environment slug to select for the run.
      - `verbose` boolean
      - `dry_run` boolean
      - `auto_approve` boolean
      - `preserve_sandbox` boolean
      - `label` string[]
      - `input` string[] — Raw repeated CLI input overrides, each in `KEY=VALUE` form.
    - `target` ManifestTarget, required
      - `path` string, required — Resolved path that keys into the workflows map.
    - `configs` ManifestConfig[]
      - `type` 'project' | 'user', required
      - `path` string, nullable
      - `source` string, nullable
    - `workflows` object, required
  - RunIntent — A request to create, but not start, one run from an immutable workflow version and an explicit workspace target.
    - `workflow_version_id` string, required — SHA-256 identity of validated canonical workflow-version bytes. Hex input is case-insensitive; Fabro emits the canonical lowercase form.
    - `target` union, required — Workspace content and location requested for a run.
      - GitRunTarget — Public github.com repository target.
        - `kind` 'git', required
        - `repo` string, required — GitHub repository slug in `owner/name` form.
        - `branch` string, required — Required branch name, preserved exactly.
        - `sha` string — Optional exact commit. The server lowercase-normalizes its syntax but does not resolve it or prove branch ancestry.
      - NoneRunTarget — Empty workspace with no repository. Docker and Daytona accept this target and suppress cloning even when workflow settings enable it. Local environments reject it; Local scratch allocation is a separate future capability.
        - `kind` 'none', required
    - `args` RunIntentArgs, required — Structured run overrides accepted by workflow-version creation.
      - `model` string
      - `provider` string — LLM provider; this does not select the sandbox environment.
      - `inputs` object
      - `labels` object
    - `environment_id` string — Server environment catalog ID. Omission selects `default`.
    - `parent_id` string — Optional orchestration parent run ID.
    - `title` string — Optional explicit run title, normalized by the server.
    - `goal` string — Optional inline goal override.

## Response `201`

Run created

- Run — Canonical public run shape.
  - `id` string, required
  - `parent_id` string, nullable — Current orchestration parent run ID, if linked.
  - `children_count` integer, required — Number of runs currently linked to this run as their orchestration parent.
  - `title` string, required
  - `goal` string, required
  - `workflow` WorkflowRef, required
    - `slug` string, nullable, required
    - `name` string, nullable, required
    - `graph_name` string, nullable, required
    - `node_count` integer, required — Number of nodes in the workflow graph.
    - `edge_count` integer, required — Number of edges in the workflow graph.
  - `automation` AutomationRef, required
    - `id` string, required
    - `name` string, nullable, required
    - `trigger_id` string, nullable
  - `repository` RepositoryRef, required — Durable repository metadata for a run.
    - `name` string, required
    - `origin_url` string, nullable, required
    - `provider` 'github' | 'git' | 'unknown', required
  - `created_by` union, required
    - PrincipalUser
      - `kind` 'user', required
      - `identity` IdpIdentity, required
        - `issuer` string, required
        - `subject` string, required
      - `login` string, required
      - `auth_method` 'github' | 'dev_token', required — Runtime user authentication method.
      - `avatar_url` string, nullable
    - PrincipalWorker
      - `kind` 'worker', required
      - `run_id` string, required
    - PrincipalWebhook
      - `kind` 'webhook', required
      - `delivery_id` string, required
    - PrincipalSlack
      - `kind` 'slack', required
      - `team_id` string, required
      - `user_id` string, required
      - `user_name` string, nullable
    - PrincipalAgent
      - `kind` 'agent', required
      - `session_id` string, nullable
      - `parent_session_id` string, nullable
      - `model` string, nullable
    - PrincipalSystem
      - `kind` 'system', required
      - `system_kind` 'engine' | 'watchdog' | 'timeout', required
  - `origin` RunOrigin, required
    - `kind` 'api', required
  - `labels` object, required
  - `lifecycle` RunLifecycle, required
    - `status` union, required — Execution status of a run. Archive state is represented separately on `RunLifecycle.archived` so terminal status payloads remain intact.
      - RunStatusSubmitted
        - `kind` 'submitted', required
      - RunStatusPending
        - `kind` 'pending', required
        - `reason` 'approval_required', required — Reason a pre-execution run is pending instead of runnable.
      - RunStatusRunnable
        - `kind` 'runnable', required
      - RunStatusStarting
        - `kind` 'starting', required
      - RunStatusRunning
        - `kind` 'running', required
      - RunStatusBlocked
        - `kind` 'blocked', required
        - `blocked_reason` 'human_input_required', required — Specific reason a run is blocked on external intervention.
      - RunStatusPaused
        - `kind` 'paused', required
        - `prior_block` 'human_input_required', required — Specific reason a run is blocked on external intervention.
      - RunStatusRemoving
        - `kind` 'removing', required
      - RunStatusSucceeded
        - `kind` 'succeeded', required
        - `reason` 'completed' | 'partial_success', required — Reason attached to a successful terminal run status.
      - RunStatusFailed
        - `kind` 'failed', required
        - `reason` 'workflow_error' | 'publish_failed' | 'cancelled' | 'approval_denied' | 'terminated' | 'transient_infra' | 'budget_exhausted' | 'launch_failed' | 'bootstrap_failed' | 'sandbox_init_failed', required — Reason attached to a failed terminal run status.
      - RunStatusDead
        - `kind` 'dead', required
    - `approval` RunApproval, required — Pre-execution approval state for runs that require one-time human approval.
      - `state` 'pending' | 'approved' | 'denied', required — State of a run's pre-execution approval request.
      - `requested_at` string, date-time, required
      - `decided_at` string, date-time, nullable, required
      - `denial_reason` string, nullable, required
    - `pending_control` 'cancel' | 'pause' | 'unpause', required — Run control action requested by the API.
    - `queue_position` integer, nullable, required
    - `error` RunError, required — Error information for a failed run.
      - `message` string, required — Error message.
    - `archived` boolean, required
    - `archived_at` string, date-time, nullable, required
  - `sandbox` RunSandbox, required — Sandbox lifecycle record for a run. A run can have a requested sandbox plan before it has an initialized sandbox instance.
    - `kind` 'planned' | 'initializing' | 'ready' | 'failed', required — Lifecycle state for a run sandbox request.
    - `plan` RunSandboxPlan, required — Requested sandbox provider and base image/snapshot from run settings.
      - `provider` 'local' | 'docker' | 'daytona', required — Sandbox provider discriminator.
      - `image` string, nullable
      - `snapshot` string, nullable
    - `instance` RunSandboxInstance — Initialized sandbox provider and runtime metadata.
      - `provider` 'local' | 'docker' | 'daytona', required — Sandbox provider discriminator.
      - `image` string, nullable
      - `snapshot` string, nullable
      - `runtime` RunSandboxRuntime, required
        - `id` string, required
        - `working_directory` string, required
        - `repo_cloned` boolean, nullable, required
        - `clone_origin_url` string, nullable, required
        - `clone_branch` string, nullable, required
        - `workspace_root` string, nullable
        - `repos_root` string, nullable
        - `primary_repo_path` string, nullable
        - `primary_repo_link` string, nullable
    - `failure` RunSandboxFailure — Sandbox initialization failure details.
      - `provider` string, required — Provider reported by the sandbox initialization event.
      - `error` string, required
      - `causes` string[], required
      - `duration_ms` integer, required
  - `models` RunModel[], required
    - `provider` string, nullable, required
    - `name` string, required
  - `source_directory` string, nullable, required
  - `timestamps` RunTimestamps, required
    - `created_at` string, date-time, required
    - `started_at` string, date-time, nullable, required
    - `last_event_at` string, date-time, nullable, required
    - `completed_at` string, date-time, nullable, required
  - `timing` RunTiming, required — Timing rollup for an entire run. Active fields sum work across stage visits, so `active_time_ms` can exceed `wall_time_ms` when parallel branches run concurrently. For a running run, stages still in flight contribute a live estimate rather than nothing, so wall and active both advance continuously. Unlike `StageTiming`, active is not clamped to wall here — concurrent branches can legitimately sum past run wall time.
    - `wall_time_ms` integer, required
    - `inference_time_ms` integer, required
    - `tool_time_ms` integer, required
    - `active_time_ms` integer, required — Equals `inference_time_ms + tool_time_ms`.
  - `billing` RunBillingSummary, required
    - `total_usd_micros` integer, nullable, required
  - `size` 'XS' | 'S' | 'M' | 'L' | 'XL', required — Run size bucket derived from current best-effort billed usage.
  - `ask_fabro` AskFabro, required — Readiness and defaults for starting an Ask Fabro session on this run.
    - `available` boolean, required
    - `unavailable_reason` 'no_sandbox' | 'sandbox_not_ready' | 'llm_unconfigured' | 'null', nullable, required
    - `default_model` string, nullable, required
  - `diff` DiffSummary, required — Cheap aggregate file and line counts for a run diff.
    - `files_changed` integer, required — Total number of changed files, including binary files.
    - `additions` integer, required — Total lines added across text files.
    - `deletions` integer, required — Total lines deleted across text files.
  - `pull_request` PullRequestLink, required — Minimal GitHub pull request link associated with a run.
    - `owner` string, required
    - `repo` string, required
    - `number` integer, required
    - `html_url` string, uri, required — Computed GitHub web URL for the pull request.
  - `current_question` RunQuestion, required — A pending human-in-the-loop question summary.
    - `text` string, required — Question text.
  - `superseded_by` string, nullable, required — Run ID that superseded this run via rewind, if any.
  - `retried_from` string, nullable, required — Source run ID when this run was created by manual retry.
  - `links` RunLinks, required
    - `web` string, uri, nullable, required

## Other responses

- `400` — Invalid JSON or legacy manifest

## Changes

- **2026-08-23** `cfd12cf45afb` — 6 info
  - added `none` discriminator mapping keys to the `oneOf[#/components/schemas/RunIntent]/target` request property
  - added `#/components/schemas/NoneRunTarget` to the `oneOf[#/components/schemas/RunIntent]/target` request property `oneOf` list
  - removed the non-success response with the status `404`
  - removed the non-success response with the status `422`
  - …2 more
- **2026-08-21** `6ed5f1557b9b` — 1 breaking, 10 warning, 5 info
  - the request's body type changed from `object` to no type
  - removed the request property `args`
  - removed the request property `configs`
  - removed the request property `cwd`
  - …12 more
- **2026-08-04** `bee030053823` — 4 warning
  - removed the request property `git/push_outcome`
  - removed the request property `goal/path`
  - removed the request property `run_id`
  - removed the request property `target/identifier`
- **2026-08-04** `359433692f06` — 2 breaking, 2 info
  - added the new required request property `git/push_outcome`
  - added the new required request property `target/identifier`
  - added the new optional request property `goal/path`
  - added the new optional request property `run_id`
- **2026-08-03** `3a47e2b7312f` — 1 warning
  - removed the request property `git/push_outcome`

[Full history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/runs/post.md)

---

[API](https://skmtc.dev/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.dev/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fabro-sh/apis/fabro-run-api/revisions/cfd12cf45afb?raw)