Skip to main content
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>'
{
  "ref": "<string>",
  "digest": "<string>",
  "golden_dir": "<string>",
  "build_time_ms": 123,
  "reused": true,
  "error": "<string>"
}
Builds the golden snapshot for a version: Orgo boots a VM, 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 — it returns immediately with 202 Accepted. Track progress by polling Get build status or streaming build logs. A typical build takes around two minutes.
Building templates requires a Scale plan. You can also build at publish time with POST /templates?auto_build=true.

​
Path parameters

​
namespace
string
required
Template namespace.
​
name
string
required
Template name.
​
version
string
required
Version (semver) to build.

​
Response

​
ref
string
Template ref.
​
digest
string
Content-addressed digest being built.
​
status
string
Build state: building, ready, failed, or not_built. A fresh build returns building; if an identical digest is already built, you get ready immediately with reused: true.
​
reused
boolean
true when an existing golden with the same digest was reused instead of rebuilt.

​
Example

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

​
Response

{
  "ref": "default/claude-code@1.0.0",
  "digest": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "status": "building"
}

​
Cancel a build

Send a DELETE to the same build path to cancel an in-flight build. It returns 202 with { "status": "cancelling" }, or 404 with { "status": "idle" } when nothing is building. 
curl -X DELETE https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build \
  -H "Authorization: Bearer $ORGO_API_KEY"

​
Errors

StatusMeaning
401Missing or invalid API key.
403Building requires a Scale plan or higher.
404No such template version.
429Build rate limit or host capacity reached. Back off and retry.

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

Response

Build started (or reused)

​
ref
string
​
digest
string
​
status
enum<string>
Available options:
ready,
building,
failed,
not_built
​
golden_dir
string
​
build_time_ms
integer

Build duration in milliseconds. Present when ready.

​
reused
boolean

Whether an existing golden with the same digest was reused.

​
error
string

Failure reason. Present when status is failed.