Orgo - Cloud computers for AI agents

POST

templates

Publish template

curl --request POST \
  --url https://www.orgo.ai/api/templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/yaml' \
  --data '<string>'

import requests

url = "https://www.orgo.ai/api/templates"

payload = "<string>"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/yaml"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/yaml'},
  body: '<string>'
};

fetch('https://www.orgo.ai/api/templates', 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/templates",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "<string>",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/yaml"
  ],
]);

$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/templates"

	payload := strings.NewReader("<string>")

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

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

	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/templates")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/yaml")
  .body("<string>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/templates")

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/yaml'
request.body = "<string>"

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

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "published": "2026-06-08T17:00:00Z",
  "auto_build": "building",
  "build": {
    "queued": true,
    "status": "queued",
    "job_id": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
    "state": "queued",
    "phase": "queued",
    "tier": "standard",
    "ahead": 0
  }
}

Publishes a template to your registry. The request body is a complete orgo.ai/v1 document, sent as YAML (Content-Type: application/yaml) or JSON. The body is parsed as YAML only when the content type contains yaml; anything else is parsed as JSON. A successful publish returns 201.

Publishing templates requires a Scale plan or higher. Launching a computer from a template, curated or your own, is separate: it needs a paid plan and counts against the workspace owner’s computer quota.

Refs are immutable. Once namespace/name@version is published, re-publishing the same ref with different content returns 409. Bump template.version to ship a change, or pass ?force=true to overwrite the version in place while iterating.

Query parameters

boolean

default:"false"

Set to true to build the golden snapshot immediately after publishing. Like calling Build template yourself, except that nothing is queued when this exact content is already built. Omitted, the version is published unbuilt and cannot launch until you build it. Only the exact string true enables it.

boolean

default:"false"

Set to true to overwrite an existing version in place (delete + republish). Useful for fast iteration on a single version number. Omitted, re-publishing an existing ref with different content returns 409. Only the exact string true enables it.

Request body

The raw template document. Validate it first with Validate template to catch errors without writing anything.

Response

string

The published ref, namespace/name@version.

string

Content-addressed SHA-256 digest of the canonical template.

string

ISO 8601 publish timestamp.

string

Present only when ?auto_build=true. building while the build is queued or running, ready when a golden snapshot for this exact content already exists. Absent when no build could be started. Read build.error for the reason, then call Build template.

object

Present only when ?auto_build=true. What happened to the requested build. The publish itself has succeeded either way.

Show build

boolean

true while a build job for this content is queued or running.

string

queued, building, ready, failed, or not_built.

string

Build job ID. Present when a job was queued or found in flight.

string

Queue state of the job this request queued: queued or leased.

string

Current job phase. Present when a job was queued or found in flight.

string

Build runner tier the job was queued on: standard, fast, or turbo. Present when this request queued the job.

integer

Queued jobs across all accounts that will run before this one. Present when this request queued the job.

string

Why no build was started. Present only then.

string

Machine-readable reason, when one exists, e.g. HARDWARE_EXCEEDS_BUILD_RUNNER.

Example

curl -X POST "https://www.orgo.ai/api/templates?auto_build=true" \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @claude-code.yaml

import os, requests

with open("claude-code.yaml") as f:
    body = f.read()

r = requests.post(
    "https://www.orgo.ai/api/templates",
    params={"auto_build": "true"},
    headers={
        "Authorization": f"Bearer {os.environ['ORGO_API_KEY']}",
        "Content-Type": "application/yaml",
    },
    data=body,
)
print(r.json()["ref"])

import { readFileSync } from "node:fs";

const r = await fetch("https://www.orgo.ai/api/templates?auto_build=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORGO_API_KEY}`,
    "Content-Type": "application/yaml",
  },
  body: readFileSync("claude-code.yaml", "utf8"),
});
const { ref, digest } = await r.json();
console.log(ref, digest);

Response

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "published": "2026-06-08T17:00:00Z",
  "auto_build": "building",
  "build": {
    "queued": true,
    "status": "queued",
    "job_id": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
    "state": "queued",
    "phase": "queued",
    "tier": "standard",
    "ahead": 0
  }
}

Errors

Status	Body	Meaning
`400`	`{ "error": "request body required" }`	Empty body.
`400`	`{ "error": string }`	The body could not be parsed as a template: not valid YAML or JSON, or not a canonical, sugar, or `{namespace, name, version, template}` envelope document.
`401`	`{ "error": "Invalid API key" }`	The Bearer token starts with `sk_` but is not a known Orgo key.
`401`	`{ "error": "Authentication required" }`	No `Authorization` header, or a Bearer token that is not an `sk_` key.
`401`	`{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch)." }`	The key is workspace-scoped. Template endpoints need an account-wide key. This route answers with `401`, not `403`.
`401`	`{ "error": "Service temporarily unavailable. …" }`	Orgo could not verify the key because of a server-side fault. The key is fine. Retry.
`403`	`{ "error": string, "code": "UPGRADE_REQUIRED", "upgradeTier": "scale_v2" }`	Below Scale, or your plan could not be verified. The gate fails closed, and nothing is written.
`403`	`{ "error": string, "code": "PLAN_LIMIT", "upgradeTier": "enterprise" }`	Your account is on a custom plan that does not include templates. Nothing is written.
`409`	`{ "error": string, "code": "version_exists" }`	A different template is already published at this `namespace/name@version`. Bump the version or use `?force=true`.
`422`	`{ "error": "template validation failed", "errors": [{ "field", "code", "message", "hint"? }] }`	The template failed validation. Each entry pinpoints one problem. A `details` field, when present, repeats the same list.
`429`	`{ "error": string, "code": string }`	Publish rate limit or registry quota reached, e.g. `publish_rate_limited` or `tenant_quota_exceeded`. Back off and retry.
`500`	`{ "error": string }`	Unexpected server error (`"internal error"`), or the template registry host failed or timed out. Retry.
`503`	`{ "error": string, "code"?: string }`	No fleet host is available to serve the template registry, or the template record could not be read or written (`publish_authority_unavailable`). Retry.

Branch on code rather than on the message text: UPGRADE_REQUIRED with upgradeTier is the upsell signal, and the rate-limit codes tell you what to back off from.

Authorizations

Authorization

string

header

required

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

Query Parameters

auto_build

string

default:false

true queues a golden-snapshot build right after publishing. Omitted, the version is published unbuilt and cannot launch until you build it. Only the exact string true enables it.

force

string

default:false

true overwrites an existing version in place (delete + republish). Omitted, re-publishing an existing ref with different content returns 409. Only the exact string true enables it.

Body

The orgo.ai/v1 template document as YAML.

Response

Published

ref

string

Example:

"default/claude-code@1.0.0"

digest

string

published

string<date-time>

auto_build

enum<string>

Present only with ?auto_build=true. building while the build is queued or running, ready when a golden snapshot for this exact content already exists. Absent when no build could be started; read build.error.

Available options:

building,

ready

build

object

Present only with ?auto_build=true. What happened to the requested build. The publish itself has succeeded either way.

Show child attributes

Publish template

curl --request POST \
  --url https://www.orgo.ai/api/templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/yaml' \
  --data '<string>'

import requests

url = "https://www.orgo.ai/api/templates"

payload = "<string>"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/yaml"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/yaml'},
  body: '<string>'
};

fetch('https://www.orgo.ai/api/templates', 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/templates",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "<string>",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/yaml"
  ],
]);

$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/templates"

	payload := strings.NewReader("<string>")

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

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

	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/templates")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/yaml")
  .body("<string>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/templates")

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/yaml'
request.body = "<string>"

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

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "published": "2026-06-08T17:00:00Z",
  "auto_build": "building",
  "build": {
    "queued": true,
    "status": "queued",
    "job_id": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
    "state": "queued",
    "phase": "queued",
    "tier": "standard",
    "ahead": 0
  }
}

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Publish template

Query parameters

Request body

Response

Example

Response

Errors

Authorizations

Query Parameters

Body

Response

​Query parameters

​Request body

​Response

​Example

​Response

​Errors

Authorizations

Query Parameters

Body

Response

Query parameters

Request body

Response

Example

Response

Errors