Skip to main content
POST
/
api
/
v1
/
runs
Create Run
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>",
    "docker_image": "<string>",
    "verbose": true,
    "dry_run": true,
    "auto_approve": true,
    "preserve_sandbox": true,
    "label": [
      "<string>"
    ],
    "input": [
      "<string>"
    ]
  },
  "configs": [
    {
      "path": "<string>",
      "source": "<string>"
    }
  ]
}
'
import requests

url = "https://api.example.com/api/v1/runs"

payload = {
    "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>",
        "docker_image": "<string>",
        "verbose": True,
        "dry_run": True,
        "auto_approve": True,
        "preserve_sandbox": True,
        "label": ["<string>"],
        "input": ["<string>"]
    },
    "configs": [
        {
            "path": "<string>",
            "source": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>',
      docker_image: '<string>',
      verbose: true,
      dry_run: true,
      auto_approve: true,
      preserve_sandbox: true,
      label: ['<string>'],
      input: ['<string>']
    },
    configs: [{path: '<string>', source: '<string>'}]
  })
};

fetch('https://api.example.com/api/v1/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>',
        'docker_image' => '<string>',
        'verbose' => true,
        'dry_run' => true,
        'auto_approve' => true,
        'preserve_sandbox' => true,
        'label' => [
                '<string>'
        ],
        'input' => [
                '<string>'
        ]
    ],
    'configs' => [
        [
                'path' => '<string>',
                'source' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/runs"

	payload := strings.NewReader("{\n  \"version\": 1,\n  \"cwd\": \"/tmp/project\",\n  \"target\": {\n    \"identifier\": \"smoke\",\n    \"path\": \".fabro/workflows/smoke/workflow.fabro\"\n  },\n  \"workflows\": {},\n  \"run_id\": \"01HV6D7S5YF4Z4B2M7K4N0Q6T9\",\n  \"parent_id\": \"01HV6D7S5YF4Z4B2M7K4N0Q6T8\",\n  \"title\": \"Add rate limiting to auth endpoints\",\n  \"args\": {\n    \"model\": \"<string>\",\n    \"provider\": \"<string>\",\n    \"environment\": \"<string>\",\n    \"docker_image\": \"<string>\",\n    \"verbose\": true,\n    \"dry_run\": true,\n    \"auto_approve\": true,\n    \"preserve_sandbox\": true,\n    \"label\": [\n      \"<string>\"\n    ],\n    \"input\": [\n      \"<string>\"\n    ]\n  },\n  \"configs\": [\n    {\n      \"path\": \"<string>\",\n      \"source\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": 1,\n  \"cwd\": \"/tmp/project\",\n  \"target\": {\n    \"identifier\": \"smoke\",\n    \"path\": \".fabro/workflows/smoke/workflow.fabro\"\n  },\n  \"workflows\": {},\n  \"run_id\": \"01HV6D7S5YF4Z4B2M7K4N0Q6T9\",\n  \"parent_id\": \"01HV6D7S5YF4Z4B2M7K4N0Q6T8\",\n  \"title\": \"Add rate limiting to auth endpoints\",\n  \"args\": {\n    \"model\": \"<string>\",\n    \"provider\": \"<string>\",\n    \"environment\": \"<string>\",\n    \"docker_image\": \"<string>\",\n    \"verbose\": true,\n    \"dry_run\": true,\n    \"auto_approve\": true,\n    \"preserve_sandbox\": true,\n    \"label\": [\n      \"<string>\"\n    ],\n    \"input\": [\n      \"<string>\"\n    ]\n  },\n  \"configs\": [\n    {\n      \"path\": \"<string>\",\n      \"source\": \"<string>\"\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": 1,\n  \"cwd\": \"/tmp/project\",\n  \"target\": {\n    \"identifier\": \"smoke\",\n    \"path\": \".fabro/workflows/smoke/workflow.fabro\"\n  },\n  \"workflows\": {},\n  \"run_id\": \"01HV6D7S5YF4Z4B2M7K4N0Q6T9\",\n  \"parent_id\": \"01HV6D7S5YF4Z4B2M7K4N0Q6T8\",\n  \"title\": \"Add rate limiting to auth endpoints\",\n  \"args\": {\n    \"model\": \"<string>\",\n    \"provider\": \"<string>\",\n    \"environment\": \"<string>\",\n    \"docker_image\": \"<string>\",\n    \"verbose\": true,\n    \"dry_run\": true,\n    \"auto_approve\": true,\n    \"preserve_sandbox\": true,\n    \"label\": [\n      \"<string>\"\n    ],\n    \"input\": [\n      \"<string>\"\n    ]\n  },\n  \"configs\": [\n    {\n      \"path\": \"<string>\",\n      \"source\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "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,
    "active_time_ms": 180000,
    "inference_time_ms": 120000,
    "tool_time_ms": 60000
  },
  "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>"
}
{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Run not found.",
      "code": "access_token_expired",
      "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "leftover_env_keys": [
    "<string>"
  ],
  "removed_env_keys": [
    "<string>"
  ]
}

Authorizations

​
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
​
workflows
object
required
​
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.

​
goal
object

Resolved goal with provenance.

​
args
object

Sparse command-local args that affect run settings.

​
configs
object[]

Response

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
​
automation
object | null
required
​
repository
object | null
required

Durable repository metadata for a run.

​
created_by
object
required
​
origin
object
required
​
labels
object
required
​
lifecycle
object
required
​
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.

​
models
object[]
required
​
source_directory
string | null
required
​
timestamps
object
required
​
timing
object | null
required

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

​
billing
object | null
required
​
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.

​
diff
object | null
required

Cheap aggregate file and line counts for a run diff.

​
pull_request
object | null
required

Minimal GitHub pull request link associated with a run.

​
current_question
object | null
required

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

​
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
​
parent_id
string | null

Current orchestration parent run ID, if linked.