> ## 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.
# Validate template
> Check a template document for errors without publishing it.
Validates a template against the `orgo.ai/v1` schema and returns either the normalized document or a structured list of errors. This endpoint has **no side effects**. Nothing is written, so it is cheap enough to call on every keystroke in an editor.
Validate is also the right way to check a [sugar-form](/guides/templates/schema#sugar-form) template: it desugars server-side, which the published JSON Schema cannot do.
## Request body
The raw template document. Send `Content-Type: application/yaml` to parse it as YAML. The body is parsed as YAML whenever the content type contains `yaml`; anything else is parsed as JSON. An empty body returns `400`.
## Response
`true` if the template is valid.
The normalized template (sugar expanded into canonical form). Present when `ok` is `true`.
Present when `ok` is `false`, alongside a `422` status. Each entry pinpoints one problem.
Dotted path to the offending field, e.g. `hardware.cpu` or `files[2].to`.
Machine-readable code, one of: `required`, `invalid_enum`, `invalid_format`, `invalid_value`, `unsafe_path`, `mutex_conflict`, `unknown_reference`, `duplicate`, `unknown_api_version`.
Human-readable explanation.
Suggestion for fixing it. Present on some errors only.
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/templates/validate \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/yaml" \
--data-binary @claude-code.yaml
```
```python Python theme={null}
import os, requests
r = requests.post(
"https://www.orgo.ai/api/templates/validate",
headers={
"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}",
"Content-Type": "application/yaml",
},
data=open("claude-code.yaml").read(),
)
result = r.json()
if not result["ok"]:
for e in result["errors"]:
print(f"{e['field']}: {e['message']}")
```
```javascript JavaScript theme={null}
import { readFileSync } from "node:fs";
const r = await fetch("https://www.orgo.ai/api/templates/validate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ORGO_API_KEY}`,
"Content-Type": "application/yaml",
},
body: readFileSync("claude-code.yaml", "utf8"),
});
const result = await r.json();
if (!result.ok) console.error(result.errors);
```
### Valid response
```json theme={null}
{
"ok": true,
"template": {
"api_version": "orgo.ai/v1",
"template": { "name": "claude-code", "version": "1.0.0" }
}
}
```
### Invalid response (`422`)
```json theme={null}
{
"ok": false,
"errors": [
{
"field": "hardware.cpu",
"code": "invalid_enum",
"message": "must be 1, 2, 4, 8, or 16"
}
]
}
```
## Errors
A validation failure is the `422` above: `ok` is `false` and the body carries `errors`, with no `error` field. Everything else is a transport-level failure.
| 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. |
| `422` | `{ "ok": false, "errors": [...] }` | The template is invalid. |
| `429` | `{ "error": string, "code": "validate_rate_limited" }` | Validate rate limit reached. Back off and retry. |
| `500` | `{ "error": string }` | Unexpected server error (`"internal error"`), or the validator host failed or timed out. Retry. |
| `503` | `{ "error": string }` | No fleet host is available to run the validator. Retry. |
## OpenAPI
````yaml POST /templates/validate
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/validate:
post:
tags:
- Templates
summary: Validate template
description: >-
Validates a template against the `orgo.ai/v1` schema without writing
anything, and returns the normalized document or a list of errors. Also
the way to check a sugar-form template. Send `Content-Type:
application/yaml` to parse YAML; anything else is parsed as JSON.
operationId: validateTemplate
requestBody:
required: true
content:
application/yaml:
schema:
type: string
application/json:
schema:
$ref: '#/components/schemas/Template'
responses:
'200':
description: Validation result
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateResponse'
'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'
'422':
description: >-
The template is invalid. `ok` is `false` and the body carries
`errors`, with no `error` field.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateResponse'
example:
ok: false
errors:
- field: hardware.cpu
code: invalid_enum
message: must be 1, 2, 4, 8, or 16
'429':
description: Validate rate limit reached. Back off and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
example:
error: …
code: validate_rate_limited
'500':
$ref: '#/components/responses/TemplateInternalError'
'503':
$ref: '#/components/responses/TemplateHostUnavailable'
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
ValidateResponse:
type: object
properties:
ok:
type: boolean
template:
$ref: '#/components/schemas/Template'
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
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
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
TemplateHostUnavailable:
description: >-
No template-capable host in the fleet could serve the request, or the
fleet lookup itself failed. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateError'
example:
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
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.