Using the API
Runs
Human-in-the-Loop
Run Outputs
More
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",
"args": {
"model": "<string>",
"provider": "<string>",
"sandbox": "<string>",
"verbose": true,
"dry_run": true,
"auto_approve": true,
"no_retro": true,
"preserve_sandbox": true,
"label": [
"<string>"
]
},
"configs": [
{
"type": "project",
"path": "<string>",
"source": "<string>"
}
]
}
'{
"id": "01JNQVR7M0EJ5GKAT2SC4ERS1Z",
"status": "submitted",
"created_at": "2026-03-06T14:30:00Z",
"error": {
"message": "Stage 'apply-changes' exceeded maximum retries."
},
"queue_position": 3,
"status_reason": "completed",
"pending_control": "cancel"
}Create Run
Creates a new workflow run in submitted status from a self-contained manifest.
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",
"args": {
"model": "<string>",
"provider": "<string>",
"sandbox": "<string>",
"verbose": true,
"dry_run": true,
"auto_approve": true,
"no_retro": true,
"preserve_sandbox": true,
"label": [
"<string>"
]
},
"configs": [
{
"type": "project",
"path": "<string>",
"source": "<string>"
}
]
}
'{
"id": "01JNQVR7M0EJ5GKAT2SC4ERS1Z",
"status": "submitted",
"created_at": "2026-03-06T14:30:00Z",
"error": {
"message": "Stage 'apply-changes' exceeded maximum retries."
},
"queue_position": 3,
"status_reason": "completed",
"pending_control": "cancel"
}Authorizations
JWT bearer token issued by fabro-web. See the Authentication guide for details.
Body
Self-contained workflow run manifest.
Manifest schema version.
1
CLI working directory at invocation time.
"/tmp/project"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Optional pre-generated run ID to use instead of allocating a new ULID.
"01HV6D7S5YF4Z4B2M7K4N0Q6T9"
Observable git state from the CLI working directory.
Show child attributes
Show child attributes
Resolved goal with provenance.
Show child attributes
Show child attributes
Sparse command-local args that affect run settings.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
Run created
Current status of a run with optional error and queue position.
Unique run identifier (ULID).
"01JNQVR7M0EJ5GKAT2SC4ERS1Z"
Lifecycle status of a run.
submitted, queued, starting, running, completed, failed, cancelled, paused Timestamp when the run was created.
"2026-03-06T14:30:00Z"
Error information for a failed run.
Show child attributes
Show child attributes
Position in the queue (1-based). Only present when status is queued.
3
Optional reason attached to a run status transition.
completed, partial_success, workflow_error, cancelled, terminated, transient_infra, budget_exhausted, launch_failed, bootstrap_failed, sandbox_init_failed, sandbox_initializing Run control action requested by the API.
cancel, pause, unpause