> ## 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 (`Content-Type: application/json`).
Publishing templates requires a **Scale** plan. Every account can still launch [curated templates](/api-reference/templates/list-curated) and any template you've published.
**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
Build the [golden snapshot](/guides/templates/introduction#golden-snapshots) immediately after publishing. Equivalent to calling [Build template](/api-reference/templates/build) yourself.
Overwrite an existing version in place (delete + republish). Useful for fast iteration on a single version number.
## 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`. The status of the build that was kicked off, e.g. `"building"`.
## 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"
}
```
## Errors
| Status | Meaning |
| ------ | ------------------------------------------------------------------------------------------------------------------ |
| `400` | Empty body, or unparseable YAML / JSON. |
| `401` | Missing or invalid API key. |
| `403` | Publishing requires a Scale plan or higher. |
| `409` | A different template is already published at this `namespace/name@version`. Bump the version or use `?force=true`. |
| `422` | The template failed validation. The `errors` array lists each problem with its `field`, `code`, and `message`. |
## 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: 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: Streaming
description: Stream computer display via RTMP
- 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 (YAML or JSON) to your registry. Requires
a Scale plan. Refs are immutable: re-publishing the same
`namespace/name@version` with different content returns 409 unless
`force=true`.
operationId: publishTemplate
parameters:
- name: auto_build
in: query
required: false
description: Build the golden snapshot immediately after publishing.
schema:
type: boolean
- name: force
in: query
required: false
description: >-
Overwrite an existing version in place (delete + republish). Useful
while iterating on one version number.
schema:
type: boolean
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'
'400':
description: Empty or unparseable body
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Publishing requires a Scale plan or higher
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: >-
A different template is already published at this ref. Bump the
version or use force=true.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: The template failed validation
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
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
description: >-
Present only with ?auto_build=true. The kicked-off build's status,
e.g. "building".
Error:
type: object
properties:
error:
type: string
description: Error message
ValidationErrorResponse:
type: object
properties:
error:
type: string
errors:
type: array
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
responses:
Unauthorized:
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Invalid API key
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````