Workflows
Replace steps
Write a workflow’s whole lines, only over the version you read. Every open canvas shows the change at once.
PUT
/
workflows
/
{id}
Write a workflow’s steps
curl --request PUT \
--url https://www.orgo.ai/api/workflows/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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}\"}"
}
'import requests
url = "https://www.orgo.ai/api/workflows/{id}"
payload = { "lines": "{\"id\":\"a\",\"kind\":\"start\",\"title\":\"9:00 AM\",\"sub\":\"Weekdays\",\"name\":\"Morning report\"}
{\"id\":\"b\",\"after\":[\"a\"],\"kind\":\"agent\",\"agent\":\"hermes\",\"title\":\"Write the report\",\"task\":\"Write a short report on yesterday’s new customers.\"}
{\"id\":\"c\",\"after\":[\"b\"],\"kind\":\"app\",\"app\":\"slack\",\"title\":\"Post\",\"where\":\"{channel}\",\"message\":\"{report}\"}" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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}"}'
})
};
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 => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'lines' => '{"id":"a","kind":"start","title":"9:00 AM","sub":"Weekdays","name":"Morning report"}
{"id":"b","after":["a"],"kind":"agent","agent":"hermes","title":"Write the report","task":"Write a short report on yesterday’s new customers."}
{"id":"c","after":["b"],"kind":"app","app":"slack","title":"Post","where":"{channel}","message":"{report}"}'
]),
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 \"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}\\\"}\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://www.orgo.ai/api/workflows/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"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}\\\"}\"\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::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"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}\\\"}\"\n}"
response = http.request(request)
puts response.read_body{
"id": "morning-report",
"name": "Morning report",
"on": false,
"version": 3,
"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."
}Replaces a workflow’s steps with the lines you send. Read the workflow with Get a workflow, change its
A version conflict (
When the workflow was deleted since you read it,
lines, and send them back with If-Match set to the version you read. A change made since then is never written over: the answer is 409 with the newest version and lines, so you can merge your change into them and send it again.
A PUT to an id no workflow has makes a new one. A workflow that is on and can no longer run after the change is turned off, and the answer says turned_off: true. A write that changes nothing writes nothing, and the version stays.
Path parameters
Headers
The version you read, as Get a workflow gave it in
version or the ETag header. Without it, the write is made over whatever is there now.Request body
The whole workflow, one JSON object per step, the start first. The format is at orgo.ai/workflows.md.
Response
The workflow as kept, in the same shape Get a workflow answers, with the new version inversion and the ETag header. lines are the lines as the canvas reads them, and the next GET hands back exactly those. Two more fields appear only when they apply:
Example
# Read it, edit morning-report.jsonl, then write it back over the version you read
curl -s https://www.orgo.ai/api/workflows/morning-report \
-H "Authorization: Bearer $ORGO_API_KEY" | jq -r .lines > morning-report.jsonl
jq -Rs '{lines: .}' morning-report.jsonl | curl -X PUT https://www.orgo.ai/api/workflows/morning-report \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "3"' \
-H "X-Agent: Claude Code" \
-d @-
import os, requests
url = "https://www.orgo.ai/api/workflows/morning-report"
headers = {"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"}
current = requests.get(url, headers=headers).json()
lines = current["lines"].replace('"title":"9:00 AM"', '"title":"8:00 AM"')
r = requests.put(url, headers={**headers, "If-Match": str(current["version"])}, json={"lines": lines})
if r.status_code == 409:
print("Changed since you read it. Merge into:", r.json()["lines"])
const url = "https://www.orgo.ai/api/workflows/morning-report";
const headers = { Authorization: `Bearer ${process.env.ORGO_API_KEY}` };
const current = await (await fetch(url, { headers })).json();
const r = await fetch(url, {
method: "PUT",
headers: { ...headers, "Content-Type": "application/json", "If-Match": String(current.version) },
body: JSON.stringify({ lines: current.lines.replace('"title":"9:00 AM"', '"title":"8:00 AM"') }),
});
Response
{
"id": "morning-report",
"name": "Morning report",
"on": false,
"version": 4,
"lines": "{\"id\":\"a\",\"kind\":\"start\",\"title\":\"8: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" }]
}
A version conflict (409)
{
"error": "The workflow changed since you read it. Merge your change into these lines and send it again.",
"code": "version_conflict",
"version": 5,
"lines": "<the newest lines>",
"next": "Read it again (GET /api/workflows/morning-report), make your change on its lines, and PUT them with If-Match: <its version>."
}
version and lines are null: send it again without If-Match to make it again.
Errors
| Status | Code | When |
|---|---|---|
400 | invalid_body | A body that is not { "lines": "..." }, or a time_zone that is not an IANA zone. |
400 | invalid_id | An id that is not lowercase letters, digits and -, at most 60. |
401 | No key, or a key Orgo doesn’t know. | |
403 | key_permission | A restricted key without Workflows write, or steps that act on its computer from a key without Control write and AI write. |
404 | (no body) | Workflows aren’t open to your account. |
409 | version_conflict | If-Match names an older version. The body carries the newest version and lines. |
409 | too_many_workflows | A new id, and you have 200 workflows already. |
413 | body_too_large | The body is over 128 KB. |
422 | invalid_lines | Lines that could not be read, named in dropped. Nothing was written. |
429 | rate_limited | Too many writes. Carries Retry-After. |
503 | Orgo couldn’t verify the key because of a server-side fault. Retry. |
Authorizations
Headers
Body
application/json
One JSON object per step, the start first (https://www.orgo.ai/workflows.md).
Response
The workflow, as kept.
The workflow, one JSON object per step, the start first (https://www.orgo.ai/workflows.md).
⌘I
Write a workflow’s steps
curl --request PUT \
--url https://www.orgo.ai/api/workflows/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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}\"}"
}
'import requests
url = "https://www.orgo.ai/api/workflows/{id}"
payload = { "lines": "{\"id\":\"a\",\"kind\":\"start\",\"title\":\"9:00 AM\",\"sub\":\"Weekdays\",\"name\":\"Morning report\"}
{\"id\":\"b\",\"after\":[\"a\"],\"kind\":\"agent\",\"agent\":\"hermes\",\"title\":\"Write the report\",\"task\":\"Write a short report on yesterday’s new customers.\"}
{\"id\":\"c\",\"after\":[\"b\"],\"kind\":\"app\",\"app\":\"slack\",\"title\":\"Post\",\"where\":\"{channel}\",\"message\":\"{report}\"}" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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}"}'
})
};
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 => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'lines' => '{"id":"a","kind":"start","title":"9:00 AM","sub":"Weekdays","name":"Morning report"}
{"id":"b","after":["a"],"kind":"agent","agent":"hermes","title":"Write the report","task":"Write a short report on yesterday’s new customers."}
{"id":"c","after":["b"],"kind":"app","app":"slack","title":"Post","where":"{channel}","message":"{report}"}'
]),
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 \"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}\\\"}\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://www.orgo.ai/api/workflows/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"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}\\\"}\"\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::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"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}\\\"}\"\n}"
response = http.request(request)
puts response.read_body{
"id": "morning-report",
"name": "Morning report",
"on": false,
"version": 3,
"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."
}