Skip to content
Hayonix

API reference · Templates

Get a template

GET/v1/templates/{template_id}
API keytemplate:readProject
TypeScript
client.templates.get()
Python
client.templates.get()
CLI
hayonix templates show

Returns an official or public template, or one of your organization’s private ones. Other organizations’ private templates and deleted templates are not found.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the template:read 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/tpl_01jc5zq4m8k3v6x9t2w7r0b1e4" \
  -H "Authorization: Bearer $API_KEY"

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.

Path parameters

  • template_idstringrequired

    ID of the template

    ID with prefix tpl_

Response

200 Template — The 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.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.