API reference · Templates
Create a private (organization) or public template
/v1/templates- TypeScript
client.templates.create()- Python
client.templates.create()- CLI
hayonix templates create
Creates a template owned by your organization. A private template is usable by all its projects; a public one by every organization, and it keeps no secret references or registry credential.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the template:create permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/templates" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Team base image",
"image": "ubuntu:26.04",
"visibility": "private",
"defaults": {
"command": [
"sleep",
"infinity"
],
"volume": {
"size_gb": 20,
"mount_path": "/workspace"
}
}
}'Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Body
JSON (application/json): CreateTemplateRequest.
namestringrequiredIts name
1–100 characters
descriptionstring | nullFree-text description
up to 1000 characters
imagestringrequiredContainer image reference
1–512 characters
visibilitystring`private`: every project of your organization can use it. `public`: every organization can; secret references and the registry credential are dropped.
One of
privatepublicdefault "private"
requires_gpubooleanPods from it need a GPU SKU (default false)
readmestring | nullUsage notes shown with the template (Markdown)
up to 20000 characters
registry_credential_idstring | nullID of the registry credential
ID with prefix rcr_
defaultsobjectLaunch defaults; fields left out take their default values
ShowHide 9 fields of
defaultscommandarray of stringReplaces the image’s entrypoint when non-empty
up to 64 items · default []
argsarray of stringReplaces the image’s default arguments when non-empty
up to 256 items · default []
envarray of objectValues may contain {{random_token}}, replaced with a fresh random token for each pod
up to 128 items · default []
ShowHide 2 fields of
envnamestringrequiredIts name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$
valuestringrequiredValue of the variable (up to 32,768 characters)
up to 32768 characters
secret_envarray of objectPrivate templates only; dropped from public ones
up to 128 items · default []
ShowHide 2 fields of
secret_envnamestringrequiredIts name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$
secret_idstringrequiredID of the secret
ID with prefix sec_
portsarray of objectContainer ports each pod exposes
up to 16 items · default []
ShowHide 4 fields of
portsportintegerrequiredPort number the container listens on
1–65535
protocolstring`http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.
One of
httptcpdefault "http"
visibilitystring`public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.
One of
publicprivatedefault "public"
namestringIts name
pattern ^[a-z][a-z0-9-]{0,30}$
container_disk_gbintegerWritable container disk in GB for each pod
5–500 · default 20
volumeobject | nullPod volume created with each pod (null: none)
default null
ShowHide 2 fields of
volumesize_gbintegerrequiredSize in GB
1–2000
mount_pathstringrequiredAbsolute path the volume is mounted at inside the container
2–256 characters
sshbooleanAllow SSH (and SFTP, port forwarding) with the project’s SSH keys
default true
categorystringGrouping shown in the catalog: `base`, `notebook`, `ml` or `other`
One of
basenotebookmlotherdefault "other"
Response
201 Template — The new template
objectstringrequiredAlways `template`: the type of this object
One of
templateidstringrequiredUnique ID (`tpl_…`)
ID with prefix tpl_
sourcestringrequired`official`: provided by the platform. `public`: shared by an organization with everyone. `private`: your organization’s own.
One of
officialpublicprivateorg_idstring | nullrequiredNull for official templates
namestringrequiredIts name
descriptionstring | nullrequiredFree-text description
imagestringrequiredContainer image reference
requires_gpubooleanrequiredNeeds a GPU SKU (e.g. built on CUDA)
readmestring | nullrequiredUsage notes (Markdown); null when there are none
registry_credential_idstring | nullrequiredID of the registry credential
ShowHide 9 fields of
defaultscommandarray of stringReplaces the image’s entrypoint when non-empty
up to 64 items · default []
argsarray of stringReplaces the image’s default arguments when non-empty
up to 256 items · default []
envarray of objectValues may contain {{random_token}}, replaced with a fresh random token for each pod
up to 128 items · default []
ShowHide 2 fields of
envnamestringrequiredIts name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$
valuestringrequiredValue of the variable (up to 32,768 characters)
up to 32768 characters
secret_envarray of objectPrivate templates only; dropped from public ones
up to 128 items · default []
ShowHide 2 fields of
secret_envnamestringrequiredIts name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$
secret_idstringrequiredID of the secret
ID with prefix sec_
portsarray of objectContainer ports each pod exposes
up to 16 items · default []
ShowHide 4 fields of
portsportintegerrequiredPort number the container listens on
1–65535
protocolstring`http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.
One of
httptcpdefault "http"
visibilitystring`public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.
One of
publicprivatedefault "public"
namestringIts name
pattern ^[a-z][a-z0-9-]{0,30}$
container_disk_gbintegerWritable container disk in GB for each pod
5–500 · default 20
volumeobject | nullPod volume created with each pod (null: none)
default null
ShowHide 2 fields of
volumesize_gbintegerrequiredSize in GB
1–2000
mount_pathstringrequiredAbsolute path the volume is mounted at inside the container
2–256 characters
sshbooleanAllow SSH (and SFTP, port forwarding) with the project’s SSH keys
default true
categorystringGrouping shown in the catalog: `base`, `notebook`, `ml` or `other`
One of
basenotebookmlotherdefault "other"
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
deleted_atstring (date-time) | nullrequiredWhen it was deleted (null while it exists) (ISO 8601, UTC)
Example response
{
"object": "template",
"id": "tpl_01jc5zq4m8k3v6x9t2w7r0b1e4",
"source": "official",
"org_id": "string",
"name": "string",
"description": "string",
"image": "string",
"requires_gpu": true,
"readme": "string",
"registry_credential_id": "string",
"defaults": {
"command": [],
"args": [],
"env": [],
"secret_env": [],
"ports": [],
"container_disk_gb": 20,
"volume": null,
"ssh": true,
"category": "other"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"deleted_at": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |