> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Publish template
> Publish a template document to your registry.
Publishes a template to your registry. The request body is a complete [`orgo.ai/v1`](/guides/templates/schema) 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](https://orgo.ai/pricing) 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
Set to `true` to build the [golden snapshot](/guides/templates/introduction#golden-snapshots) immediately after publishing. Like calling [Build template](/api-reference/templates/build) 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.
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](/api-reference/templates/validate) to catch errors without writing anything.
## Response
The published ref, `namespace/name@version`.
Content-addressed SHA-256 digest of the canonical template.
ISO 8601 publish timestamp.
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](/api-reference/templates/build).
Present only when `?auto_build=true`. What happened to the requested build. The publish itself has succeeded either way.
`true` while a build job for this content is queued or running.
`queued`, `building`, `ready`, `failed`, or `not_built`.
Build job ID. Present when a job was queued or found in flight.
Queue state of the job this request queued: `queued` or `leased`.
Current job phase. Present when a job was queued or found in flight.
Build runner tier the job was queued on: `standard`, `fast`, or `turbo`. Present when this request queued the job.
Queued jobs across all accounts that will run before this one. Present when this request queued the job.
Why no build was started. Present only then.
Machine-readable reason, when one exists, e.g. `HARDWARE_EXCEEDS_BUILD_RUNNER`.
## Example
```bash cURL theme={null}
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
```
```python Python theme={null}
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"])
```
```javascript JavaScript theme={null}
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
```json theme={null}
{
"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.
## OpenAPI
````yaml POST /templates
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
paths:
/templates:
post:
tags:
- Templates
summary: Publish template
description: >-
Publishes a template document to your registry and returns `201`. Send
YAML (`Content-Type: application/yaml`) or JSON; the body is parsed as
YAML only when the content type contains `yaml`. Refs are immutable:
re-publishing the same `namespace/name@version` with different content
returns `409` unless `force=true`. Requires a Scale plan.
operationId: publishTemplate
parameters:
- name: auto_build
in: query
required: false
description: >-
`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.
schema:
type: string
default: 'false'
- name: force
in: query
required: false
description: >-
`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.
schema:
type: string
default: 'false'
requestBody:
required: true
content:
application/yaml:
schema:
type: string
description: The orgo.ai/v1 template document as YAML.
application/json:
schema:
$ref: '#/components/schemas/Template'
responses:
'201':
description: Published
content:
application/json:
schema:
$ref: '#/components/schemas/PublishResponse'
example:
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
'400':
description: >-
Empty body, or 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.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
examples:
empty:
summary: Empty body
value:
error: request body required
parse:
summary: Unparseable
value:
error: …
'401':
$ref: '#/components/responses/UnauthorizedTemplates'
'403':
description: >-
Below Scale, or your plan could not be verified
(`UPGRADE_REQUIRED`), or your account is on a custom plan that does
not include templates (`PLAN_LIMIT`). The gate fails closed, and
nothing is written.
content:
application/json:
schema:
$ref: '#/components/schemas/QuotaError'
examples:
upgrade:
summary: Below Scale
value:
error: …
code: UPGRADE_REQUIRED
upgradeTier: scale_v2
plan-limit:
summary: A custom plan that does not include templates
value:
error: >-
Your plan doesn't include building templates. Contact us
to add them to your plan.
code: PLAN_LIMIT
upgradeTier: enterprise
'409':
description: >-
A different template is already published at this
`namespace/name@version`. Bump the version or use `?force=true`.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
example:
error: …
code: version_exists
'422':
description: >-
The template failed validation. Each entry in `errors` pinpoints one
problem. `details`, when present, repeats the same list.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
example:
error: template validation failed
errors:
- field: hardware.cpu
code: invalid_enum
message: must be 1, 2, 4, 8, or 16
details:
- field: hardware.cpu
code: invalid_enum
message: must be 1, 2, 4, 8, or 16
'429':
description: >-
Publish rate limit or registry quota reached, such as
`publish_rate_limited` or `tenant_quota_exceeded`. Back off and
retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
example:
error: …
code: publish_rate_limited
'500':
$ref: '#/components/responses/TemplateInternalError'
'503':
description: >-
No template-capable host in the fleet could serve the request, or
the fleet lookup itself failed, or the template record could not be
read or written (`publish_authority_unavailable`). Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
examples:
host:
summary: No template-capable host
value:
error: >-
no template launch host available in env=production: every
fleet_servers row was excluded (disabled, draining,
unhealthy, dedicated, legacy/parked, or not accepting user
VMs). Check the fleet
authority:
summary: The template record could not be read or written
value:
error: template authority unavailable
code: publish_authority_unavailable
components:
schemas:
Template:
type: object
description: >-
An orgo.ai/v1 template document. Only `api_version` and `template` are
required. See the full JSON Schema at GET /template-schema, or the
schema guide at https://docs.orgo.ai/guides/templates/schema.
required:
- api_version
- template
additionalProperties: true
properties:
api_version:
type: string
enum:
- orgo.ai/v1
template:
type: object
required:
- name
- version
properties:
name:
type: string
description: Lowercase kebab-case, 1-64 chars.
example: claude-code
version:
type: string
description: Semver, immutable once published.
example: 1.0.0
description:
type: string
hardware:
type: object
secrets:
type: array
items:
type: object
vars:
type: object
env:
type: object
build:
type: object
files:
type: array
apps:
type: array
triggers:
type: array
terminal:
type: array
hooks:
type: object
telemetry:
type: object
egress_policy:
type: object
streaming:
type: array
PublishResponse:
type: object
properties:
ref:
type: string
example: default/claude-code@1.0.0
digest:
type: string
published:
type: string
format: date-time
auto_build:
type: string
enum:
- building
- ready
description: >-
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`.
build:
type: object
description: >-
Present only with `?auto_build=true`. What happened to the requested
build. The publish itself has succeeded either way.
properties:
queued:
type: boolean
description: '`true` while a build job for this content is queued or running.'
status:
type: string
enum:
- queued
- building
- ready
- failed
- not_built
job_id:
type: string
description: Build job ID. Present when a job was queued or found in flight.
state:
type: string
enum:
- queued
- leased
description: Queue state of the job this request queued.
phase:
type: string
description: >-
Current job phase. Present when a job was queued or found in
flight.
tier:
type: string
enum:
- standard
- fast
- turbo
description: Build runner tier. Present when this request queued the job.
ahead:
type: integer
description: >-
Queued jobs across all accounts that will run before this one.
Present when this request queued the job.
error:
type: string
description: Why no build was started. Present only then.
code:
type: string
description: >-
Machine-readable reason, when one exists, such as
`HARDWARE_EXCEEDS_BUILD_RUNNER`.
TemplateError:
type: object
description: >-
A failure from the template registry, relayed with the registry's own
status and code.
required:
- error
properties:
error:
type: string
code:
type: string
description: Machine-readable reason, when the registry supplied one.
details:
description: >-
Per-field validation errors, or the raw upstream body when it was
not JSON.
oneOf:
- type: array
items:
$ref: '#/components/schemas/ValidationError'
- type: string
QuotaError:
type: object
description: >-
The request was refused by the plan the workspace owner is on rather
than by ownership. See https://orgo.ai/pricing for what each plan
includes.
required:
- error
properties:
error:
type: string
code:
type: string
description: >-
Machine-readable reason. Values this API emits: `UPGRADE_REQUIRED`,
`DESKTOP_LIMIT`, `VM_SLOT_ADDON`, `RAM_ADDON`,
`PER_COMPUTER_RAM_CAP`, `VCPU_ADDON`, `PER_COMPUTER_CPU_CAP`,
`DISK_QUOTA_EXCEEDED`, `disk_exceeds_quota`,
`WINDOWS_REQUIRES_SCALE`, `GUEST_RESTRICTED`, `NOT_A_MEMBER`,
`CHANGE_PLAN`, `PLAN_LIMIT`, `upgrade_required`.
upgradeTier:
type: string
description: The plan that would allow the request.
canManageCapacity:
type: boolean
description: True when you own the workspace and can raise the limit yourself.
max_ram_gb:
type: integer
description: >-
On a RAM refusal from resize: the largest RAM a live resize can
reach for this computer.
max_disk_gb:
type: integer
description: 'On a storage refusal: the largest disk this computer may have.'
ValidationErrorResponse:
type: object
properties:
error:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
details:
type: array
description: The same list as `errors`, when present.
items:
$ref: '#/components/schemas/ValidationError'
ValidationError:
type: object
properties:
field:
type: string
description: Dotted path to the offending field.
example: hardware.cpu
code:
type: string
example: invalid_enum
message:
type: string
hint:
type: string
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
responses:
UnauthorizedTemplates:
description: >-
No usable credential, or a workspace-scoped key. Template endpoints need
an account-wide key and answer a scoped one with `401`, not `403`. A
server-side fault while verifying the credential also returns `401`,
with a `Service temporarily unavailable` message. Retry that one; the
key is fine.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
account-wide-required:
summary: The API key is workspace-scoped
value:
error: >-
This endpoint requires an account-wide credential
(workspace_scope_mismatch).
service-unavailable:
summary: Server-side fault while verifying the credential. Retry.
value:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
TemplateInternalError:
description: >-
Unexpected server error (`internal error`), or the template registry
host failed or timed out, with the underlying message in `error`. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
examples:
internal:
summary: Unexpected server error
value:
error: internal error
timeout:
summary: The registry host did not answer in time
value:
error: timeout of 30000ms exceeded
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.