Orgo - Cloud computers for AI agents

PATCH

workflows

{id}

Rename a workflow, turn it on or off, or set its settings

curl --request PATCH \
  --url https://www.orgo.ai/api/workflows/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "on": true,
  "settings": {
    "channel": "#sales"
  }
}
'

import requests

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

payload = {
    "on": True,
    "settings": { "channel": "#sales" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({on: true, settings: {channel: '#sales'}})
};

fetch('https://www.orgo.ai/api/workflows/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'on' => true,
    'settings' => [
        'channel' => '#sales'
    ]
  ]),
  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}"

	payload := strings.NewReader("{\n  \"on\": true,\n  \"settings\": {\n    \"channel\": \"#sales\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://www.orgo.ai/api/workflows/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"on\": true,\n  \"settings\": {\n    \"channel\": \"#sales\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/workflows/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"on\": true,\n  \"settings\": {\n    \"channel\": \"#sales\"\n  }\n}"

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

{
  "id": "morning-report",
  "name": "Morning report",
  "on": true,
  "version": 4,
  "lines": "{\"id\":\"a\",\"kind\":\"start\",\"title\":\"9:00 AM\",\"sub\":\"Weekdays\",\"name\":\"Morning report\"}\n{\"id\":\"b\",\"after\":[\"a\"],\"kind\":\"agent\",\"agent\":\"hermes\",\"title\":\"Write the report\",\"task\":\"Write a short report on yesterday’s new customers.\"}\n{\"id\":\"c\",\"after\":[\"b\"],\"kind\":\"app\",\"app\":\"slack\",\"title\":\"Post\",\"where\":\"{channel}\",\"message\":\"{report}\"}",
  "settings": {},
  "to_fix": [
    "Fill in channel"
  ],
  "problems": [
    {
      "step": "a",
      "say": "Fill in channel"
    }
  ]
}

{
  "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": "Service temporarily unavailable. The database is not accepting requests. Retry shortly."
}

Changes what a workflow is set to, never its steps. Send only the fields you change. To change its steps, use Replace a workflow’s steps. Turning a workflow on sets up its start: a timed start is scheduled, and an app event is watched on the computer’s own sign-in of that app. When it can’t run yet, turning it on answers 422 with code: "not_ready" and a to_fix list, and nothing changes. Any other change that leaves it unable to run turns it off, and the answer says turned_off: true.

Path parameters

string

required

The workflow’s id, like morning-report.

Headers

string

The version you read. A newer version answers 409 with code: "version_conflict".

string

Who is writing, at most 30 characters, like Claude Code. The canvas names you on the change.

Request body

boolean

true to turn it on, false to turn it off.

string

A new name, at most 40 characters. Its id doesn’t change.

object

What it asks for once, name to value, like { "channel": "sales" }. Only the names you send change. "" or null takes one out.

string | null

The UUID of the computer its steps run on, one of yours (from List workspaces or Get workspace). null or "" takes it off. Picking one takes a key with Control write and AI write.

string

An IANA zone its times and date words are read in, like America/New_York. A timed start needs one.

Response

The workflow as kept, in the same shape Get a workflow answers, with the new version in version and the ETag header. turned_off: true appears when this change turned it off.

Example

curl -X PATCH https://www.orgo.ai/api/workflows/morning-report \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"computer\":\"$COMPUTER_ID\",\"time_zone\":\"America/New_York\",\"settings\":{\"channel\":\"sales\"}}"

curl -X PATCH https://www.orgo.ai/api/workflows/morning-report \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on":true}'

import os, requests

r = requests.patch(
    "https://www.orgo.ai/api/workflows/morning-report",
    headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
    json={"on": True},
)
if r.status_code == 422:
    print("Can’t run yet:", r.json()["to_fix"])

const r = await fetch("https://www.orgo.ai/api/workflows/morning-report", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ on: true }),
});

Replace $COMPUTER_ID with the computer’s UUID.

It can’t run yet (`422`)

{
  "error": "It can’t run yet. Fix these first.",
  "say": "It can’t run yet.",
  "code": "not_ready",
  "to_fix": ["Connect Slack"],
  "next": "Fix each item in to_fix: a step with PUT /api/workflows/morning-report, settings, the computer or the time zone with PATCH /api/workflows/morning-report. Then try again."
}

When the missing piece is an app to connect on its computer, the body also carries needs, the apps to connect.

Errors

Status	Code	When
`400`	`invalid_body`	A value of the wrong kind, or a `time_zone` that is not an IANA zone.
`400`	`invalid_computer`	A computer that isn’t one of yours, or one the key doesn’t reach.
`401`		No key, or a key Orgo doesn’t know.
`403`	`key_permission`	A restricted key without Workflows write, or picking a computer (or turning on a workflow whose steps act on it) from a key without Control write and AI write.
`403`	`computer_key_held`	A restricted or expiring key, and the computer holds its own Orgo key.
`404`	`not_found`	No workflow by that id.
`404`	(no body)	Workflows aren’t open to your account.
`409`	`version_conflict`	`If-Match` names an older version.
`413`	`body_too_large`	The body is over 64 KB.
`422`	`not_ready`	It can’t run yet, so it was not turned on. `to_fix` says what to do.
`429`	`rate_limited`	Too many writes. Carries `Retry-After`.
`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

If-Match

string

The version you read (GET’s version, or its ETag).

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

name

string

Maximum string length: 40

boolean

settings

object

Only the names sent change; "" or null takes one out.

Show child attributes

computer

string | null

The computer its steps run on (its UUID, from List workspaces or Get workspace); null takes it off.

time_zone

string

An IANA zone, like America/New_York.

Response

The workflow, as kept.

string

required

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

name

string | null

required

boolean

required

Whether its start runs it. It is on only while it can run.

version

integer

required

Send it as If-Match on a write.

lines

string

required

The workflow, one JSON object per step, the start first (https://www.orgo.ai/workflows.md).

settings

object

required

What it asks for once, name to value.

Show child attributes

to_fix

string[]

required

What still has to be done before it can run, in the person’s words. Empty: ready.

problems

object[]

required

Show child attributes

turned_off

boolean

This write left it unable to run, so it was turned off.

dropped

string[]

What of the lines sent was left out or rewritten.

Rename a workflow, turn it on or off, or set its settings

curl --request PATCH \
  --url https://www.orgo.ai/api/workflows/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "on": true,
  "settings": {
    "channel": "#sales"
  }
}
'

import requests

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

payload = {
    "on": True,
    "settings": { "channel": "#sales" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({on: true, settings: {channel: '#sales'}})
};

fetch('https://www.orgo.ai/api/workflows/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'on' => true,
    'settings' => [
        'channel' => '#sales'
    ]
  ]),
  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}"

	payload := strings.NewReader("{\n  \"on\": true,\n  \"settings\": {\n    \"channel\": \"#sales\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://www.orgo.ai/api/workflows/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"on\": true,\n  \"settings\": {\n    \"channel\": \"#sales\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/workflows/{id}")

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

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"on\": true,\n  \"settings\": {\n    \"channel\": \"#sales\"\n  }\n}"

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

{
  "id": "morning-report",
  "name": "Morning report",
  "on": true,
  "version": 4,
  "lines": "{\"id\":\"a\",\"kind\":\"start\",\"title\":\"9:00 AM\",\"sub\":\"Weekdays\",\"name\":\"Morning report\"}\n{\"id\":\"b\",\"after\":[\"a\"],\"kind\":\"agent\",\"agent\":\"hermes\",\"title\":\"Write the report\",\"task\":\"Write a short report on yesterday’s new customers.\"}\n{\"id\":\"c\",\"after\":[\"b\"],\"kind\":\"app\",\"app\":\"slack\",\"title\":\"Post\",\"where\":\"{channel}\",\"message\":\"{report}\"}",
  "settings": {},
  "to_fix": [
    "Fill in channel"
  ],
  "problems": [
    {
      "step": "a",
      "say": "Fill in channel"
    }
  ]
}

{
  "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": "Service temporarily unavailable. The database is not accepting requests. Retry shortly."
}

Overview

API keys

Support

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Workflows

Update a workflow

Path parameters

Headers

Request body

Response

Example

It can’t run yet (`422`)

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Path parameters

​Headers

​Request body

​Response

​Example

​It can’t run yet (422)

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Path parameters

Headers

Request body

Response

Example

It can’t run yet (`422`)

Errors