Orgo - Cloud computers for AI agents

POST

templates

{namespace}

{name}

{version}

build

Build template

curl --request POST \
  --url https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build', 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/{namespace}/{name}/{version}/build",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "status": "queued",
  "jobId": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
  "phase": "queued",
  "tier": "standard",
  "ahead": 0,
  "launchOnReady": false
}

Builds the golden snapshot for a version: Orgo boots a computer, runs the build steps and app installs, then captures a paused snapshot. A built template launches in seconds; an unbuilt one cannot launch at all. This call is asynchronous and returns immediately with 202 Accepted. The build is queued for a dedicated build runner. Track progress by polling Get build status. Requests are idempotent while a build is in flight: if a job for the same content is already queued or running, you get that job back instead of a second one. At most 10 of your builds can be queued or running at once.

Building templates requires a Scale plan or higher. You can also build at publish time with POST /templates?auto_build=true. Reading the build status is not gated.

The build is where on_first_boot runs, and it never runs again on a launch. on_every_boot runs during the build and again on any launch that cold-boots, such as one that injects secrets. See hooks.

Path parameters

string

required

Template namespace.

string

required

Template name.

string

required

Version (semver) to build.

Query parameters

string

Build runner to use: standard (2 vCPU, 8 GB), fast (4 vCPU, 16 GB), or turbo (8 vCPU, 32 GB). Omitted, Orgo picks the smallest runner that holds the template’s hardware. Any other value returns 400. A runner smaller than the template’s hardware returns 422.

boolean

default:"false"

Set to true to create a computer from the template as soon as the build is ready. Only the exact string true enables it. The launch goes through the same plan and quota checks as Create computer.

string

Workspace ID for the computer that launch=true creates. You must belong to the workspace, or the call returns 403. Omitted, Orgo picks one of your workspaces.

Response

string

Template ref.

string

Content-addressed digest being built.

string

queued while the job waits for a runner, building once a runner has claimed it.

string

Build job ID.

string

Current job phase, e.g. queued.

string

Build runner tier: standard, fast, or turbo.

integer

Queued jobs across all accounts that will run before this one.

boolean

Whether a computer is created when the build is ready. For a job that was already in flight, this is that job’s setting, not this request’s.

The shape above comes from the build queue. Production runs with the queue on, so this is the shape you get from www.orgo.ai. The queue is off by default in a deployment that does not enable it, and there the call still returns 202, but with the older build-result shape: ref, digest, and status (building, or ready when a golden snapshot for this content already exists), without jobId, phase, tier, ahead, or launchOnReady. The tier, launch, and project query parameters are ignored in that mode.

Example

curl -X POST https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build \
  -H "Authorization: Bearer $ORGO_API_KEY"

import os, requests, time

ref = "default/claude-code/1.0.0"
base = f"https://www.orgo.ai/api/templates/{ref}/build"
hdr = {"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"}

requests.post(base, headers=hdr)                 # kick off
while True:                                       # poll to ready
    status = requests.get(base, headers=hdr).json()["status"]
    print(status)
    if status in ("ready", "failed", "not_built"):
        break
    time.sleep(5)

const base =
  "https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build";
const hdr = { Authorization: `Bearer ${process.env.ORGO_API_KEY}` };

await fetch(base, { method: "POST", headers: hdr });
let status = "building";
while (status === "building") {
  await new Promise((r) => setTimeout(r, 5000));
  status = (await (await fetch(base, { headers: hdr })).json()).status;
}
console.log(status);

Response

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "status": "queued",
  "jobId": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
  "phase": "queued",
  "tier": "standard",
  "ahead": 0,
  "launchOnReady": false
}

Cancel a build

Send a DELETE to the same build path to cancel a build that no runner has claimed yet. It returns 202 with { "status": "cancelled" }, and the version’s status reads not_built afterwards. A build a runner has already claimed runs to completion. When nothing is queued, Orgo falls back to cancelling on the template registry host: if that host had a build to cancel, the call returns 202 with { "status": "cancelling" }. Otherwise, including for a build a runner has already claimed, it returns 404 with { "status": "idle" }.

curl -X DELETE https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build \
  -H "Authorization: Bearer $ORGO_API_KEY"

Errors

Status	Body	Meaning
`400`	`{ "error": "unknown build tier \"<tier>\"" }`	`tier` is not `standard`, `fast`, or `turbo`.
`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 no build starts.
`403`	`{ "error": string, "code": "PLAN_LIMIT", "upgradeTier": "enterprise" }`	Your account is on a custom plan that does not include templates. No build starts.
`403`	`{ "error": "you do not have access to that workspace" }`	`project` names a workspace you do not belong to.
`409`	`{ "error": string }`	No such version is published in your namespaces, so there is nothing to build. Publish it first.
`422`	`{ "error": string, "code": "HARDWARE_EXCEEDS_BUILD_RUNNER" }`	The template’s `hardware` does not fit the requested `tier`, or any runner. The message names the smallest runner that fits.
`429`	`{ "error": string }`	You already have 10 builds queued or running. Wait for one to finish.
`500`	`{ "error": "internal error" }`	Unexpected server error.

DELETE (cancel) is not plan-gated and takes no query parameters. Its 404 body is { "status": "idle" }, not an error object.

Authorizations

Authorization

string

header

required

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

Path Parameters

namespace

string

required

name

string

required

version

string

required

Query Parameters

tier

enum<string>

Build runner: standard (2 vCPU, 8 GB), fast (4 vCPU, 16 GB), or turbo (8 vCPU, 32 GB). Omitted, the smallest runner that holds the template's hardware. Any other value returns 400; a runner smaller than the template's hardware returns 422.

Available options:

standard,

fast,

turbo

launch

string

default:false

true creates a computer from the template as soon as the build is ready, with the same plan and quota checks as POST /computers. Only the exact string true enables it.

project

string

Workspace ID for the computer that launch=true creates. You must belong to it, or the call returns 403. Omitted, Orgo picks one of your workspaces.

Response

Build queued, or the in-flight job for the same content

A build queued for a dedicated build runner.

ref

string

Example:

"default/claude-code@1.0.0"

digest

string

Content-addressed digest being built.

status

enum<string>

queued while the job waits for a runner, building once a runner has claimed it.

Available options:

queued,

building

jobId

string

Build job ID.

phase

string

Current job phase, such as queued.

tier

enum<string>

Build runner tier.

Available options:

standard,

fast,

turbo

ahead

integer

Queued jobs across all accounts that will run before this one.

launchOnReady

boolean

Whether a computer is created when the build is ready. For a job already in flight, that job's setting, not this request's.

Build template

curl --request POST \
  --url https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build"

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build', 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/{namespace}/{name}/{version}/build",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/templates/{namespace}/{name}/{version}/build")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "status": "queued",
  "jobId": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
  "phase": "queued",
  "tier": "standard",
  "ahead": 0,
  "launchOnReady": false
}

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Build template

Path parameters

Query parameters

Response

Example

Response

Cancel a build

Errors

Authorizations

Path Parameters

Query Parameters

Response

​Path parameters

​Query parameters

​Response

​Example

​Response

​Cancel a build

​Errors

Authorizations

Path Parameters

Query Parameters

Response

Path parameters

Query parameters

Response

Example

Response

Cancel a build

Errors