Create Run

Creates a new workflow run in submitted status from a self-contained manifest.

POST /api/v1/runs

Create Run

cURL

curl --request POST \
  --url https://api.example.com/api/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": 1,
  "cwd": "/tmp/project",
  "target": {
    "identifier": "smoke",
    "path": ".fabro/workflows/smoke/workflow.fabro"
  },
  "workflows": {},
  "run_id": "01HV6D7S5YF4Z4B2M7K4N0Q6T9",
  "parent_id": "01HV6D7S5YF4Z4B2M7K4N0Q6T8",
  "title": "Add rate limiting to auth endpoints",
  "args": {
    "model": "<string>",
    "provider": "<string>",
    "environment": "<string>",
    "verbose": true,
    "dry_run": true,
    "auto_approve": true,
    "preserve_sandbox": true,
    "label": [
      "<string>"
    ],
    "input": [
      "<string>"
    ]
  },
  "configs": [
    {
      "path": "<string>",
      "source": "<string>"
    }
  ]
}
'

201

{
  "id": "<string>",
  "children_count": 1,
  "title": "<string>",
  "goal": "<string>",
  "workflow": {
    "slug": "<string>",
    "name": "<string>",
    "graph_name": "<string>",
    "node_count": 123,
    "edge_count": 123
  },
  "automation": {
    "id": "<string>",
    "name": "<string>",
    "trigger_id": "<string>"
  },
  "repository": {
    "name": "fabro-sh/fabro",
    "origin_url": "https://github.com/fabro-sh/fabro.git"
  },
  "created_by": {
    "kind": "user",
    "identity": {
      "issuer": "<string>",
      "subject": "<string>"
    },
    "login": "<string>",
    "avatar_url": "<string>"
  },
  "origin": {
    "kind": "api"
  },
  "labels": {},
  "lifecycle": {
    "status": {
      "kind": "submitted"
    },
    "approval": {
      "requested_at": "2023-11-07T05:31:56Z",
      "decided_at": "2023-11-07T05:31:56Z",
      "denial_reason": "<string>"
    },
    "queue_position": 123,
    "error": {
      "message": "Stage 'apply-changes' exceeded maximum retries."
    },
    "archived": true,
    "archived_at": "2023-11-07T05:31:56Z"
  },
  "sandbox": {
    "plan": {
      "image": "<string>",
      "snapshot": "<string>"
    },
    "instance": {
      "runtime": {
        "id": "<string>",
        "working_directory": "<string>",
        "repo_cloned": true,
        "clone_origin_url": "<string>",
        "clone_branch": "<string>",
        "workspace_root": "<string>",
        "repos_root": "<string>",
        "primary_repo_path": "<string>",
        "primary_repo_link": "<string>"
      },
      "image": "<string>",
      "snapshot": "<string>"
    },
    "failure": {
      "provider": "<string>",
      "error": "<string>",
      "causes": [
        "<string>"
      ],
      "duration_ms": 1
    }
  },
  "models": [
    {
      "provider": "<string>",
      "name": "<string>"
    }
  ],
  "source_directory": "<string>",
  "timestamps": {
    "created_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "last_event_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "timing": {
    "wall_time_ms": 420000,
    "inference_time_ms": 120000,
    "tool_time_ms": 60000,
    "active_time_ms": 180000
  },
  "billing": {
    "total_usd_micros": 123
  },
  "ask_fabro": {
    "available": true,
    "default_model": "<string>"
  },
  "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?"
  },
  "superseded_by": "<string>",
  "retried_from": "<string>",
  "links": {
    "web": "<string>"
  },
  "parent_id": "<string>"
}

Authorizations

BearerAuthSessionCookie

Authorization · string · header · required

Raw dev token passed as Authorization: Bearer fabro_dev_... when server.auth.methods includes dev-token.

Body

application/json

Self-contained workflow run manifest.

version · integer · required

Manifest schema version.

Example:

1

cwd · string · required

CLI working directory at invocation time.

Example:

"/tmp/project"

target · object · required

Show child attributes

workflows · object · required

Show child attributes

run_id · string | null

Optional pre-generated run ID to use instead of allocating a new ULID.

Example:

"01HV6D7S5YF4Z4B2M7K4N0Q6T9"

parent_id · string | null

Optional orchestration parent run ID. Fork and rewind lineage use separate fields and should not set this value.

Example:

"01HV6D7S5YF4Z4B2M7K4N0Q6T8"

title · string | null

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.

Maximum string length: 100

Example:

"Add rate limiting to auth endpoints"

git · object

Observable git state captured before the run starts.

Show child attributes

goal · object

Resolved goal with provenance.

Show child attributes

args · object

Sparse command-local args that affect run settings.

Show child attributes

configs · object[]

Show child attributes

Response

201

application/json

Run created

Canonical public run shape.

id · string · required

children_count · integer<uint64> · required

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

Required range: x >= 0

title · string · required

goal · string · required

workflow · object · required

Show child attributes

automation · object | null · required

Show child attributes

repository · object | null · required

Durable repository metadata for a run.

Show child attributes

created_by · object · required

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

origin · object · required

Show child attributes

labels · object · required

Show child attributes

lifecycle · object · required

Show child attributes

sandbox · object | null · required

Sandbox lifecycle record for a run. A run can have a requested sandbox plan before it has an initialized sandbox instance.

Show child attributes

models · object[] · required

Show child attributes

source_directory · string | null · required

timestamps · object · required

Show child attributes

timing · object | null · required

Run-level timing rollup. Wall time is the run's clock duration; active timing sums work across stage visits.

Show child attributes

billing · object | null · required

Show child attributes

size · enum<string> · required

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

Available options: XS, S, M, L, XL

ask_fabro · object · required

Readiness and defaults for starting an Ask Fabro session on this run.

Show child attributes

diff · object | null · required

Cheap aggregate file and line counts for a run diff.

Show child attributes

pull_request · object | null · required

Minimal GitHub pull request link associated with a run.

Show child attributes

current_question · object | null · required

A pending human-in-the-loop question summary.

Show child attributes

superseded_by · string | null · required

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

retried_from · string | null · required

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

links · object · required

Show child attributes

parent_id · string | null

Current orchestration parent run ID, if linked.