# Template API

Source: https://docs.oiy.ai/docs/api/templates

Read starter templates and maintain reusable account configurations.



## Read [#read]

`GET /api/templates` returns the templates available to the account. Built-in starters are also included in the unauthenticated public catalog. Workspace templates are account-isolated.

## Create [#create]

`POST /api/templates` requires authentication and `Idempotency-Key`. A template specification includes name, description, image, command, resources, HTTP port, container disk, workspace size, sleep timeout, and required environment variable names.

```json
{
  "name": "CPU workspace",
  "description": "A simple HTTP workspace for development",
  "image": "python:3.12-slim",
  "command": ["python", "-m", "http.server", "8080", "--bind", "0.0.0.0"],
  "resources": { "gpuCount": 0, "cpu": 2, "memoryGb": 4 },
  "httpPort": 8080,
  "requiredEnvironment": []
}
```

Templates store required variable **names**, never values. Supply actual environment secrets when creating a service.

## Update and delete [#update-and-delete]

`PUT /api/templates/{id}` and `DELETE /api/templates/{id}` require the current revision and an idempotency key. Read a template before modifying it. Updating or deleting a template does not retroactively reconfigure or delete existing services.

Use the console or MCP `oiy_save_template` tool for guided revision-checked edits. Templates remain subject to image compatibility and live resource availability when deployed.

## Exact update bodies [#exact-update-bodies]

A template replacement uses a wrapper with `revision` and the complete `spec`:

```json
{
  "revision": 1,
  "spec": {
    "name": "CPU workspace",
    "image": "python:3.12-slim",
    "resources": { "gpuCount": 0, "cpu": 2, "memoryGb": 4 },
    "requiredEnvironment": []
  }
}
```

Omitted specification fields use their defaults. This is a replacement, not a partial merge. Replace the example revision with the value read from the current template.

Deletion also includes a JSON body:

```json
{ "revision": 1 }
```

Create returns a bare template with HTTP `201`; update returns a bare template with HTTP `200`. Delete returns `{ "id": "TEMPLATE_ID", "deleted": true }`. Listing returns `{ "templates": [...] }`. Up to 50 workspace templates are allowed per account.