Skip to content
Hayonix

API reference · Templates

Create a private (organization) or public template

POST/v1/templates
API keytemplate:createProjectIdempotency-Key
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

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.
Idempotency-KeynoMakes 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.

  • namestringrequired

    Its name

    1–100 characters

  • descriptionstring | null

    Free-text description

    up to 1000 characters

  • imagestringrequired

    Container 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 ofprivatepublic

    default "private"

  • requires_gpuboolean

    Pods from it need a GPU SKU (default false)

  • readmestring | null

    Usage notes shown with the template (Markdown)

    up to 20000 characters

  • registry_credential_idstring | null

    ID of the registry credential

    ID with prefix rcr_

  • defaultsobject

    Launch defaults; fields left out take their default values

    Show 9 fields of defaults
    • commandarray of string

      Replaces the image’s entrypoint when non-empty

      up to 64 items · default []

    • argsarray of string

      Replaces the image’s default arguments when non-empty

      up to 256 items · default []

    • envarray of object

      Values may contain {{random_token}}, replaced with a fresh random token for each pod

      up to 128 items · default []

      Show 2 fields of env
      • namestringrequired

        Its name

        pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$

      • valuestringrequired

        Value of the variable (up to 32,768 characters)

        up to 32768 characters

    • secret_envarray of object

      Private templates only; dropped from public ones

      up to 128 items · default []

      Show 2 fields of secret_env
      • namestringrequired

        Its name

        pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$

      • secret_idstringrequired

        ID of the secret

        ID with prefix sec_

    • portsarray of object

      Container ports each pod exposes

      up to 16 items · default []

      Show 4 fields of ports
      • portintegerrequired

        Port 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 ofhttptcp

        default "http"

      • visibilitystring

        `public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.

        One ofpublicprivate

        default "public"

      • namestring

        Its name

        pattern ^[a-z][a-z0-9-]{0,30}$

    • container_disk_gbinteger

      Writable container disk in GB for each pod

      5–500 · default 20

    • volumeobject | null

      Pod volume created with each pod (null: none)

      default null

      Show 2 fields of volume
      • size_gbintegerrequired

        Size in GB

        1–2000

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

        2–256 characters

    • sshboolean

      Allow SSH (and SFTP, port forwarding) with the project’s SSH keys

      default true

    • categorystring

      Grouping shown in the catalog: `base`, `notebook`, `ml` or `other`

      One ofbasenotebookmlother

      default "other"

Response

201 Template — The new template

  • objectstringrequired

    Always `template`: the type of this object

    One oftemplate

  • idstringrequired

    Unique 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 ofofficialpublicprivate

  • org_idstring | nullrequired

    Null for official templates

  • namestringrequired

    Its name

  • descriptionstring | nullrequired

    Free-text description

  • imagestringrequired

    Container image reference

  • requires_gpubooleanrequired

    Needs a GPU SKU (e.g. built on CUDA)

  • readmestring | nullrequired

    Usage notes (Markdown); null when there are none

  • registry_credential_idstring | nullrequired

    ID of the registry credential

  • defaultsTemplateDefaultsrequired
    Show 9 fields of defaults
    • commandarray of string

      Replaces the image’s entrypoint when non-empty

      up to 64 items · default []

    • argsarray of string

      Replaces the image’s default arguments when non-empty

      up to 256 items · default []

    • envarray of object

      Values may contain {{random_token}}, replaced with a fresh random token for each pod

      up to 128 items · default []

      Show 2 fields of env
      • namestringrequired

        Its name

        pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$

      • valuestringrequired

        Value of the variable (up to 32,768 characters)

        up to 32768 characters

    • secret_envarray of object

      Private templates only; dropped from public ones

      up to 128 items · default []

      Show 2 fields of secret_env
      • namestringrequired

        Its name

        pattern ^[A-Za-z_][A-Za-z0-9_]{0,127}$

      • secret_idstringrequired

        ID of the secret

        ID with prefix sec_

    • portsarray of object

      Container ports each pod exposes

      up to 16 items · default []

      Show 4 fields of ports
      • portintegerrequired

        Port 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 ofhttptcp

        default "http"

      • visibilitystring

        `public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.

        One ofpublicprivate

        default "public"

      • namestring

        Its name

        pattern ^[a-z][a-z0-9-]{0,30}$

    • container_disk_gbinteger

      Writable container disk in GB for each pod

      5–500 · default 20

    • volumeobject | null

      Pod volume created with each pod (null: none)

      default null

      Show 2 fields of volume
      • size_gbintegerrequired

        Size in GB

        1–2000

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

        2–256 characters

    • sshboolean

      Allow SSH (and SFTP, port forwarding) with the project’s SSH keys

      default true

    • categorystring

      Grouping shown in the catalog: `base`, `notebook`, `ml` or `other`

      One ofbasenotebookmlother

      default "other"

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

  • deleted_atstring (date-time) | nullrequired

    When it was deleted (null while it exists) (ISO 8601, UTC)

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.