Orgo - Cloud computers for AI agents

POST

workflows

{id}

runs

Run a workflow now

curl --request POST \
  --url https://www.orgo.ai/api/workflows/{id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {
    "customer": "Acme"
  }
}
'

import requests

url = "https://www.orgo.ai/api/workflows/{id}/runs"

payload = { "inputs": { "customer": "Acme" } }
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({inputs: {customer: 'Acme'}})
};

fetch('https://www.orgo.ai/api/workflows/{id}/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://www.orgo.ai/api/workflows/{id}/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([
    'inputs' => [
        'customer' => 'Acme'
    ]
  ]),
  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://www.orgo.ai/api/workflows/{id}/runs"

	payload := strings.NewReader("{\n  \"inputs\": {\n    \"customer\": \"Acme\"\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://www.orgo.ai/api/workflows/{id}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {\n    \"customer\": \"Acme\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/workflows/{id}/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  \"inputs\": {\n    \"customer\": \"Acme\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "run": {
    "run_id": "0d9c6c1e-5b8e-4a59-9d3b-7a1f2c3d4e5f",
    "state": "running",
    "at": 1793887204000,
    "by": "Claude Code",
    "inputs": {},
    "steps": [],
    "output": null,
    "finished_at": null
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "Too many API requests this minute (120 a minute on your plan). Try again in 12 seconds.",
  "code": "rate_limited",
  "limit": "api_other_per_minute",
  "retry_after": 12
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

Starts a run of a workflow now, whether it is on or off, and answers 202 at once. The run goes on in the background: read it with Get a run, or follow it with Follow a workflow. A run uses the steps as they are when it starts; a later edit never changes a run already going. A run whose steps use the computer’s agents or screen wakes the computer as it starts, if it is asleep.

Path parameters

string

required

The workflow’s id, like morning-report.

Headers

string

8 to 255 printable characters. A retry with the same key and inputs answers with the run the first request started, with idempotent-replayed: true, instead of starting another. The same key with other inputs answers 409 with code: "idempotency_key_reused".

string

Who started it, at most 30 characters, like Claude Code. The run’s by and the canvas say it.

Request body

object

What the run starts with, name to string value. They fill its settings and {fill-ins} for this run only. Optional.

Response

202, with the run.

object

The run as it is now, in the shape Get a run describes. state is running.

Example

curl -X POST https://www.orgo.ai/api/workflows/morning-report/runs \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"inputs":{}}'

import os, time, uuid, requests

url = "https://www.orgo.ai/api/workflows/morning-report/runs"
headers = {"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"}

run = requests.post(url, headers={**headers, "Idempotency-Key": str(uuid.uuid4())}, json={"inputs": {}}).json()["run"]
while run["state"] == "running":
    time.sleep(3)
    run = requests.get(f"{url}/{run['run_id']}", headers=headers).json()["run"]
print(run["state"], run.get("output"))

const r = await fetch("https://www.orgo.ai/api/workflows/morning-report/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORGO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ inputs: {} }),
});
const { run } = await r.json();

Response

{
  "run": {
    "run_id": "0d9c6c1e-5b8e-4a59-9d3b-7a1f2c3d4e5f",
    "state": "running",
    "at": 1793887204000,
    "by": "Claude Code",
    "inputs": {},
    "steps": [],
    "output": null,
    "finished_at": null
  }
}

Errors

Status	Code	When
`400`	`invalid_body`	`inputs` that are not names to strings, or an `Idempotency-Key` that is not 8 to 255 printable characters.
`401`		No key, or a key Orgo doesn’t know.
`403`	`key_permission`	A restricted key without Workflows write, or without Control write and AI write for a workflow whose steps act on its computer.
`404`	`not_found`	No workflow by that id.
`404`	(no body)	Workflows aren’t open to your account.
`409`	`not_started`	It didn’t start: too many of its runs are open. Carries `Retry-After: 60`.
`409`	`computer_moved`	Its computer isn’t yours any more. Pick another with Update a workflow.
`409`	`idempotency_key_reused`	That key was used with other inputs.
`409`	`idempotency_key_spent`	That key started a run over a day ago. Send a new one to start another.
`409`	`idempotency_busy`	A request with that key is still going. Retry after `retry_after` seconds.
`413`	`body_too_large`	The body is over 64 KB.
`422`	`not_ready`	It can’t run yet. `to_fix` says what to do, and `needs` names apps to connect on its computer.
`422`	`computer_required`	It has no computer. Pick one with Update a workflow.
`429`	`rate_limited`	More than 30 runs a minute for this workflow, or 120 for the account. Carries `Retry-After`.
`503`	`runs_unavailable`	Runs can’t happen here right now. Nothing ran. Retry after a minute.
`503`		Orgo couldn’t verify the key because of a server-side fault. Retry.

Authorizations

Authorization

string

header

required

API key authentication. Get your key at orgo.ai/workspaces

Headers

Idempotency-Key

string

A retry with the same key and body answers as the first request did, for a day.

Required string length: 8 - 255

X-Agent

string

Who you are, as the canvas names you (like Claude Code).

Maximum string length: 30

Path Parameters

string

required

Pattern: ^[a-z0-9-]{1,60}$

Body

application/json

inputs

object

Show child attributes

Response

{ run }, started.

run

object

required

Show child attributes

Run a workflow now

curl --request POST \
  --url https://www.orgo.ai/api/workflows/{id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {
    "customer": "Acme"
  }
}
'

import requests

url = "https://www.orgo.ai/api/workflows/{id}/runs"

payload = { "inputs": { "customer": "Acme" } }
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({inputs: {customer: 'Acme'}})
};

fetch('https://www.orgo.ai/api/workflows/{id}/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://www.orgo.ai/api/workflows/{id}/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([
    'inputs' => [
        'customer' => 'Acme'
    ]
  ]),
  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://www.orgo.ai/api/workflows/{id}/runs"

	payload := strings.NewReader("{\n  \"inputs\": {\n    \"customer\": \"Acme\"\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://www.orgo.ai/api/workflows/{id}/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {\n    \"customer\": \"Acme\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/workflows/{id}/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  \"inputs\": {\n    \"customer\": \"Acme\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "run": {
    "run_id": "0d9c6c1e-5b8e-4a59-9d3b-7a1f2c3d4e5f",
    "state": "running",
    "at": 1793887204000,
    "by": "Claude Code",
    "inputs": {},
    "steps": [],
    "output": null,
    "finished_at": null
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

{
  "error": "Too many API requests this minute (120 a minute on your plan). Try again in 12 seconds.",
  "code": "rate_limited",
  "limit": "api_other_per_minute",
  "retry_after": 12
}

{
  "error": "<string>",
  "code": "<string>",
  "say": "<string>",
  "next": "<string>",
  "to_fix": [
    "<string>"
  ],
  "problems": [
    {}
  ],
  "version": 123,
  "lines": "<string>"
}

Overview

API keys

Support

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Workflows

Start a run

Path parameters

Headers

Request body

Response

Example

Response

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Path parameters

​Headers

​Request body

​Response

​Example

​Response

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Path parameters

Headers

Request body

Response

Example

Response

Errors