> ## 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.

# Build template

> Bake a template version into a golden snapshot.

Builds the [golden snapshot](/guides/templates/introduction#golden-snapshots) 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](/api-reference/templates/build-status) or streaming [build logs](/api-reference/templates/build-events). A typical build takes around two minutes.

<Note>
  Building templates requires a **Scale** plan. You can also build at publish time with [`POST /templates?auto_build=true`](/api-reference/templates/publish).
</Note>

## Path parameters

<ParamField path="namespace" type="string" required>Template namespace.</ParamField>
<ParamField path="name" type="string" required>Template name.</ParamField>
<ParamField path="version" type="string" required>Version (semver) to build.</ParamField>

## Response

<ResponseField name="ref" type="string">Template ref.</ResponseField>
<ResponseField name="digest" type="string">Content-addressed digest being built.</ResponseField>

<ResponseField name="status" type="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`.
</ResponseField>

<ResponseField name="reused" type="boolean">
  `true` when an existing golden with the same digest was reused instead of rebuilt.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build \
    -H "Authorization: Bearer $ORGO_API_KEY"
  ```

  ```python Python theme={null}
  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"):
          break
      time.sleep(5)
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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.

```bash theme={null}
curl -X DELETE https://www.orgo.ai/api/templates/default/claude-code/1.0.0/build \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

## Errors

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


## OpenAPI

````yaml POST /templates/{namespace}/{name}/{version}/build
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/{namespace}/{name}/{version}/build:
    post:
      tags:
        - Templates
      summary: Build template
      description: >-
        Kicks off an asynchronous golden-snapshot build and returns immediately.
        Requires a Scale plan. If an identical digest is already built, returns
        the existing golden with reused=true.
      operationId: buildTemplate
      parameters:
        - name: namespace
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Build started (or reused)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Building requires a Scale plan or higher
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Build rate limit or host capacity reached. Back off and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BuildResult:
      type: object
      properties:
        ref:
          type: string
        digest:
          type: string
        status:
          type: string
          enum:
            - ready
            - building
            - failed
            - not_built
        golden_dir:
          type: string
        build_time_ms:
          type: integer
          description: Build duration in milliseconds. Present when ready.
        reused:
          type: boolean
          description: Whether an existing golden with the same digest was reused.
        error:
          type: string
          description: Failure reason. Present when status is failed.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API key
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Resource not found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````