API reference · Pods
Reset a pod: recreate its container from the image with a fresh container disk (volumes kept)
/v1/pods/{pod_id}/reset- 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
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Path parameters
pod_idstringrequiredID of the pod
ID with prefix pod_
Response
200 Pod — The pod
objectstringrequiredAlways `pod`: the type of this object
One of
podidstringrequiredUnique ID (`pod_…`)
ID with prefix pod_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
project_idstringrequiredProject it belongs to
ID with prefix prj_
namestringrequiredIts name
hostnamestringrequiredName in the project’s private network; does not change on rename
template_idstring | nullrequiredID of the template
ShowHide 5 fields of
statusstatestringrequiredqueued (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 of
queuedpreemptedpullingstartingrunningrestartingstoppingstoppedexitedfailedunreachableterminatingterminatedreasonstring | nullrequiredMachine-readable cause of the state (why it waits, stopped or failed); null when there is none
messagestringrequiredOne sentence for people
sincestring (date-time)requiredWhen the pod entered this state
image_pullobject | nullrequiredImage download progress while the state is `pulling`; else null
ShowHide 6 fields of
image_pullimagestringrequiredContainer image reference
bytes_doneintegerrequiredBytes downloaded so far
bytes_totalintegerrequiredBytes to download in total (0 while unknown)
layers_doneintegerrequiredImage layers downloaded
layers_totalintegerrequiredImage layers in total
percentinteger | nullrequiredBytes downloaded, 0–100; null while the total is unknown
desired_statestringrequiredWhat was last asked for (create or start: `running`; stop: `stopped`; terminate: `terminated`). `status` shows where the pod actually is.
One of
runningstoppedterminatedShowHide 15 fields of
configimagestringrequiredContainer image reference
hardwareobjectrequiredSKU and number of GPUs the pod runs on
ShowHide 2 fields of
hardwareskustringrequiredHardware type code
gpu_countintegerrequiredNumber of GPUs
regionstringrequiredRegion 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 of
on_demandinterruptiblecontainer_disk_gbintegerrequiredWritable container disk in GB; reset whenever the container is recreated (stop, reconfigure)
volumeobject | nullrequiredThe pod’s own volume and where it is mounted; null for none
ShowHide 2 fields of
volumevolume_idstringrequiredID of the volume
mount_pathstringrequiredAbsolute path the volume is mounted at inside the container
network_volumesarray of objectrequiredNetwork volumes the pod mounts
ShowHide 3 fields of
network_volumesvolume_idstringrequiredID of the volume
mount_pathstringrequiredAbsolute path the volume is mounted at inside the container
read_onlybooleanrequiredMounted read-only
portsarray of objectrequiredExposed container ports
ShowHide 4 fields of
portsportintegerrequiredPort 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 of
httptcpvisibilitystringrequired`public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.
One of
publicprivatenamestringrequiredIts name
envarray of objectrequiredPlain environment variables
ShowHide 2 fields of
envnamestringrequiredIts name
valuestringrequiredValue of the variable
secret_envarray of objectrequiredEnvironment variables taken from project secrets (values are never shown)
ShowHide 2 fields of
secret_envnamestringrequiredIts name
secret_idstringrequiredID of the secret
commandarray of stringrequiredReplaces the image’s entrypoint when non-empty
argsarray of stringrequiredReplaces the image’s default arguments when non-empty
registry_credential_idstring | nullrequiredID of the registry credential
sshbooleanrequiredAllow SSH (and SFTP, port forwarding) with the project’s SSH keys
Models mounted read-only from the host’s model cache
ShowHide 1 field of
modelsreference_idstringrequiredThe model reference mounted
revisionintegerrequiredConfiguration revision (each change recreates the container)
hardwareobjectrequiredThe hardware the pod is configured for
ShowHide 4 fields of
hardwareskustringrequiredHardware type code
display_namestring | nullrequiredName to show people
gpu_countintegerrequiredNumber of GPUs
simulatedbooleanrequiredPlaced on a development host with simulated GPUs
Volumes the pod mounts: its own volume and network volumes
ShowHide 7 fields of
volumesidstringrequiredUnique ID
namestringrequiredIts name
kindstringrequired`pod`: this pod’s own volume. `network`: a network volume it mounts. (`cluster` volumes are never mounted by pods.)
One of
podnetworkclustersize_gbintegerrequiredSize in GB
pinned_to_hostbooleanrequiredThe volume lives on one host; pods using it run there
used_bytesinteger | nullrequiredSpace the volume uses on its host, as last measured; null until a host has measured it
usage_observed_atstring (date-time) | nullrequiredWhen `used_bytes` was measured
Present when reading one pod
ShowHide 3 fields of
connectportsarray of objectrequiredHow to reach each configured port
ShowHide 6 fields of
portsportintegerrequiredPort number the container listens on
namestringrequiredIts name
protocolstringrequired`http`: served at the port’s HTTPS URL (WebSocket included). `tcp`: raw TCP, reachable through SSH port forwarding.
One of
httptcpvisibilitystringrequired`public`: anyone with the URL. `private`: no URL; SSH port forwarding and the project network only.
One of
publicprivateurlstring | nullrequiredHTTPS URL (public HTTP ports)
forward_commandstring | nullrequiredSSH local-forward command reaching the port from your machine (when SSH is on)
sshobject | nullrequiredNull while SSH is off or the pod is not on a host
ShowHide 6 fields of
sshuserstringrequiredUser name to log in with (identifies the pod)
hoststringrequiredSSH host name
portintegerrequiredSSH TCP port
commandstringrequiredReady-to-run ssh command
known_hostsarray of stringrequiredLines for ~/.ssh/known_hosts pinning the host keys
sftp_commandstringrequiredReady-to-run sftp command
private_networkobjectrequiredHow other pods of the project reach this one
ShowHide 2 fields of
private_networkhostnamestringrequiredName this pod answers to in the project’s private network
scopestringrequiredOther 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 of
same_host
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.
ShowHide 3 fields of
container_diskused_bytesintegerrequiredSpace used on the container disk
limit_bytesintegerrequiredThe container disk size enforced on the host (0: not enforced)
observed_atstring (date-time)requiredWhen it was measured
preemptionsobjectrequiredPreemptions of an interruptible pod
ShowHide 2 fields of
preemptionscountintegerrequiredTimes interruptible capacity was reclaimed from the pod
last_atstring (date-time) | nullrequiredTime last (ISO 8601, UTC)
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
terminated_atstring (date-time) | nullrequiredTime terminated (ISO 8601, UTC)
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:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
409 | conflict_error | The resource's current state does not allow this. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |