Template API
Read starter templates and maintain reusable account configurations.
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
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.
{
"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
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
A template replacement uses a wrapper with revision and the complete spec:
{
"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:
{ "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.