Skip to content
Hayonix

API reference · Templates

Templates you can launch: official, public and your organization’s private ones

GET/v1/templates
API keytemplate:readProjectPaginated
TypeScript
client.templates.list()
Python
client.templates.list()
CLI
hayonix templates list

Official templates, public templates from any organization and your organization’s private ones, newest first. Deleted templates are left out; narrow the list with source.

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" \
  -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.

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • sourcestring

    `private` lists your organization’s own private templates

    One ofallofficialpublicprivate

    default "all"

Response

200 a page of results — A page of templates, newest first

  • dataarray of Templaterequired

    The items of this page.

    Show 14 fields of data
    • 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)

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "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"
    }
  ],
  "next_cursor": "string"
}

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.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.