Skip to content
Hayonix

API reference · Volumes

Unmount the volume from a pod (recreates the pod’s container; the data is kept)

POST/v1/volumes/{volume_id}/detach
API keyworkload:updateProject
TypeScript
client.volumes.detach()
Python
client.volumes.detach()
CLI
hayonix volumes detach

Removes the volume from the pod’s configuration; the volume and its data are kept and still billed. This is a reconfiguration, so the pod’s container is recreated. Refused when the volume is not mounted in that pod.

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 "$API_BASE_URL/volumes/vol_01jc5zq4m8k3v6x9t2w7r0b1e4/detach" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pod_id": "pod_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "dry_run": true
}'

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

  • volume_idstringrequired

    ID of the volume

    ID with prefix vol_

Body

JSON (application/json): DetachVolumeRequest.

  • pod_idstringrequired

    ID of the pod

    ID with prefix pod_

  • dry_runboolean

    Only report what would change (nothing is applied)

    default false

Response

200 PodReconfiguration — The pod reconfiguration

  • objectstringrequired

    Always `pod_reconfiguration`: the type of this object

    One ofpod_reconfiguration

  • appliedbooleanrequired

    The change was made; false for a dry run or when nothing differs

  • dry_runbooleanrequired

    The request was a dry run

  • revisionintegerrequired

    The pod’s configuration revision after the call (unchanged when not applied)

  • planPodChangePlanrequired
    Show 5 fields of plan
    • changed_fieldsarray of stringrequired

      Configuration fields that differ from the current ones

    • recreates_containerbooleanrequired

      True whenever anything changes: the container is recreated

    • requeuesbooleanrequired

      The pod leaves its host and is placed again (hardware, region, pricing class or volumes changed)

    • data_lostarray of stringrequired

      What does not survive, in words; empty when nothing changes

    • data_keptarray of stringrequired

      What survives, in words: the volumes and their mount paths

  • podPodrequired
    Show 19 fields of 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_reconfiguration",
  "applied": true,
  "dry_run": true,
  "revision": 1,
  "plan": {
    "changed_fields": [
      "string"
    ],
    "recreates_container": true,
    "requeues": true,
    "data_lost": [
      "string"
    ],
    "data_kept": [
      "string"
    ]
  },
  "pod": {
    "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.