Skip to content
Hayonix

API reference · Pods

Reset a pod: recreate its container from the image with a fresh container disk (volumes kept)

POST/v1/pods/{pod_id}/reset
API keyworkload:updateProject
TypeScript
client.pods.reset()
Python
client.pods.reset()
CLI
hayonix pods reset

Recreates the container in place, on the same host with the same GPUs. Everything written to the container disk is lost, and processes started inside the container end. The pod volume, network volumes, the pod ID, hostname, addresses and settings are kept. Only a pod on a host can be reset (409 pod_not_running); a stopped pod already starts with a fresh container disk. A restart in progress becomes a reset.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the workload:update 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 -X POST "$API_BASE_URL/pods/pod_01jc5zq4m8k3v6x9t2w7r0b1e4/reset" \
  -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

  • pod_idstringrequired

    ID of the pod

    ID with prefix pod_

Response

200 Pod — The pod

  • objectstringrequired

    Always `pod`: the type of this object

    One ofpod

  • idstringrequired

    Unique ID (`pod_…`)

    ID with prefix pod_

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • namestringrequired

    Its name

  • hostnamestringrequired

    Name in the project’s private network; does not change on rename

  • template_idstring | nullrequired

    ID of the template

  • statusPodStatusrequired
    Show 5 fields of status
    • statestringrequired

      queued (waiting for capacity) · preempted (interruptible capacity reclaimed; waiting again) · pulling (downloading the image) · starting · running · restarting · stopping · stopped (compute released, volumes kept) · exited (the main process finished) · failed (see reason) · unreachable (its host stopped reporting) · terminating · terminated

      One ofqueuedpreemptedpullingstartingrunningrestartingstoppingstoppedexitedfailedunreachableterminatingterminated

    • reasonstring | nullrequired

      Machine-readable cause of the state (why it waits, stopped or failed); null when there is none

    • messagestringrequired

      One sentence for people

    • sincestring (date-time)required

      When the pod entered this state

    • image_pullobject | nullrequired

      Image download progress while the state is `pulling`; else null

      Show 6 fields of image_pull
      • imagestringrequired

        Container image reference

      • bytes_doneintegerrequired

        Bytes downloaded so far

      • bytes_totalintegerrequired

        Bytes to download in total (0 while unknown)

      • layers_doneintegerrequired

        Image layers downloaded

      • layers_totalintegerrequired

        Image layers in total

      • percentinteger | nullrequired

        Bytes downloaded, 0–100; null while the total is unknown

  • desired_statestringrequired

    What was last asked for (create or start: `running`; stop: `stopped`; terminate: `terminated`). `status` shows where the pod actually is.

    One ofrunningstoppedterminated

  • configPodConfigrequired
    Show 15 fields of config
    • imagestringrequired

      Container image reference

    • hardwareobjectrequired

      SKU and number of GPUs the pod runs on

      Show 2 fields of hardware
      • skustringrequired

        Hardware type code

      • gpu_countintegerrequired

        Number of GPUs

    • regionstringrequired

      Region code

    • pricing_classstringrequired

      `interruptible` costs less and may be stopped (preempted) when on-demand work needs the capacity; it then waits in the queue to run again. On-demand pods are never preempted.

      One ofon_demandinterruptible

    • container_disk_gbintegerrequired

      Writable container disk in GB; reset whenever the container is recreated (stop, reconfigure)

    • volumeobject | nullrequired

      The pod’s own volume and where it is mounted; null for none

      Show 2 fields of volume
      • volume_idstringrequired

        ID of the volume

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

    • network_volumesarray of objectrequired

      Network volumes the pod mounts

      Show 3 fields of network_volumes
      • volume_idstringrequired

        ID of the volume

      • mount_pathstringrequired

        Absolute path the volume is mounted at inside the container

      • read_onlybooleanrequired

        Mounted read-only

    • portsarray of objectrequired

      Exposed container ports

      Show 4 fields of ports
      • portintegerrequired

        Port number the container listens on

      • protocolstringrequired

        `http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.

        One ofhttptcp

      • visibilitystringrequired

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

        One ofpublicprivate

      • namestringrequired

        Its name

    • envarray of objectrequired

      Plain environment variables

      Show 2 fields of env
      • namestringrequired

        Its name

      • valuestringrequired

        Value of the variable

    • secret_envarray of objectrequired

      Environment variables taken from project secrets (values are never shown)

      Show 2 fields of secret_env
      • namestringrequired

        Its name

      • secret_idstringrequired

        ID of the secret

    • commandarray of stringrequired

      Replaces the image’s entrypoint when non-empty

    • argsarray of stringrequired

      Replaces the image’s default arguments when non-empty

    • registry_credential_idstring | nullrequired

      ID of the registry credential

    • sshbooleanrequired

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

    • Models mounted read-only from the host’s model cache

      Show 1 field of models
      • reference_idstringrequired

        The model reference mounted

  • revisionintegerrequired

    Configuration revision (each change recreates the container)

  • hardwareobjectrequired

    The hardware the pod is configured for

    Show 4 fields of hardware
    • skustringrequired

      Hardware type code

    • display_namestring | nullrequired

      Name to show people

    • gpu_countintegerrequired

      Number of GPUs

    • simulatedbooleanrequired

      Placed on a development host with simulated GPUs

  • Volumes the pod mounts: its own volume and network volumes

    Show 7 fields of volumes
    • idstringrequired

      Unique ID

    • namestringrequired

      Its name

    • kindstringrequired

      `pod`: this pod’s own volume. `network`: a network volume it mounts. (`cluster` volumes are never mounted by pods.)

      One ofpodnetworkcluster

    • size_gbintegerrequired

      Size in GB

    • pinned_to_hostbooleanrequired

      The volume lives on one host; pods using it run there

    • used_bytesinteger | nullrequired

      Space the volume uses on its host, as last measured; null until a host has measured it

    • usage_observed_atstring (date-time) | nullrequired

      When `used_bytes` was measured

  • connectPodConnectrequired

    Present when reading one pod

    Show 3 fields of connect
    • portsarray of objectrequired

      How to reach each configured port

      Show 6 fields of ports
      • portintegerrequired

        Port number the container listens on

      • namestringrequired

        Its name

      • protocolstringrequired

        `http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.

        One ofhttptcp

      • visibilitystringrequired

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

        One ofpublicprivate

      • urlstring | nullrequired

        HTTPS URL (public HTTP ports)

      • forward_commandstring | nullrequired

        SSH local-forward command reaching the port from your machine (when SSH is on)

    • sshobject | nullrequired

      Null while SSH is off or the pod is not on a host

      Show 6 fields of ssh
      • userstringrequired

        User name to log in with (identifies the pod)

      • hoststringrequired

        SSH host name

      • portintegerrequired

        SSH TCP port

      • commandstringrequired

        Ready-to-run ssh command

      • known_hostsarray of stringrequired

        Lines for ~/.ssh/known_hosts pinning the host keys

      • sftp_commandstringrequired

        Ready-to-run sftp command

    • private_networkobjectrequired

      How other pods of the project reach this one

      Show 2 fields of private_network
      • hostnamestringrequired

        Name this pod answers to in the project’s private network

      • scopestringrequired

        Other pods of this project reach this one at `hostname` when they run on the same host (pods sharing a network volume always do). Pods of other projects cannot reach it.

        One ofsame_host

  • container_diskPodContainerDiskUsagerequired

    Container disk use of the running container against its size; null when nothing runs or the host has not measured it yet. It starts empty with every new container.

    Show 3 fields of container_disk
    • used_bytesintegerrequired

      Space used on the container disk

    • limit_bytesintegerrequired

      The container disk size enforced on the host (0: not enforced)

    • observed_atstring (date-time)required

      When it was measured

  • preemptionsobjectrequired

    Preemptions of an interruptible pod

    Show 2 fields of preemptions
    • countintegerrequired

      Times interruptible capacity was reclaimed from the pod

    • last_atstring (date-time) | nullrequired

      Time last (ISO 8601, UTC)

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

  • terminated_atstring (date-time) | nullrequired

    Time terminated (ISO 8601, UTC)

Example response
Example response
{
  "object": "pod",
  "id": "pod_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "name": "string",
  "hostname": "string",
  "template_id": "string",
  "status": {
    "state": "queued",
    "reason": "waiting_for_capacity",
    "message": "string",
    "since": "2026-01-01T00:00:00.000Z",
    "image_pull": {
      "image": "string",
      "bytes_done": 1,
      "bytes_total": 1,
      "layers_done": 1,
      "layers_total": 1,
      "percent": 1
    }
  },
  "desired_state": "running",
  "config": {
    "image": "string",
    "hardware": {
      "sku": "string",
      "gpu_count": 1
    },
    "region": "string",
    "pricing_class": "on_demand",
    "container_disk_gb": 1,
    "volume": {
      "volume_id": "string",
      "mount_path": "string"
    },
    "network_volumes": [
      {
        "volume_id": "string",
        "mount_path": "string",
        "read_only": true
      }
    ],
    "ports": [
      {
        "port": 1,
        "protocol": "http",
        "visibility": "public",
        "name": "string"
      }
    ],
    "env": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "secret_env": [
      {
        "name": "string",
        "secret_id": "string"
      }
    ],
    "command": [
      "string"
    ],
    "args": [
      "string"
    ],
    "registry_credential_id": "string",
    "ssh": true,
    "models": [
      {
        "reference_id": "string"
      }
    ]
  },
  "revision": 1,
  "hardware": {
    "sku": "string",
    "display_name": "string",
    "gpu_count": 1,
    "simulated": true
  },
  "volumes": [
    {
      "id": "string",
      "name": "string",
      "kind": "pod",
      "size_gb": 1,
      "pinned_to_host": true,
      "used_bytes": 1,
      "usage_observed_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "connect": {
    "ports": [
      {
        "port": 1,
        "name": "string",
        "protocol": "http",
        "visibility": "public",
        "url": "string",
        "forward_command": "string"
      }
    ],
    "ssh": {
      "user": "string",
      "host": "string",
      "port": 1,
      "command": "string",
      "known_hosts": [
        "string"
      ],
      "sftp_command": "string"
    },
    "private_network": {
      "hostname": "string",
      "scope": "same_host"
    }
  },
  "container_disk": {
    "used_bytes": 1,
    "limit_bytes": 1,
    "observed_at": "2026-01-01T00:00:00.000Z"
  },
  "preemptions": {
    "count": 1,
    "last_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "terminated_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).
409conflict_errorThe resource's current state does not allow this.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.