HTTP API

The API exposes interface for managing your own pods and query server status.

GET method is used for querying data without side effects;
POST method is used for creating or updating data.
All parameters are passed via query string in URLs.
The response is always in json format.

Summary

API	Method	Params
/user/info	GET
/user/list	GET
/user/ch-passwd	GET	passwd
/pod/create	POST	ins, image
/pod/delete	POST	ins
/pod/inspect	GET	ins
/pod/list	GET
/pod/start	POST	ins
/pod/stop	POST	ins
/pod/restart	POST	ins
/pod/exec	POST	ins, cmd, timeout
/pod/commit	POST	ins, tag, msg
/image/list	GET
/image/inspect	GET	image
/image/delete	POST	image
/stat/cputime	GET	user, t
/stat/gputime	GET	user, t
/host/gpu-ps	GET	id
/host/spec	GET
/help	GET	path
/version	GET

Details

podxpodycurl

TIP

Here examples of API calls are provided using podx utility.
podx is a shorthand for pody fetch command, please refer to here for more information.

/user/info

GETGet the information of the user

Example

podx user/info

Output:

{
  "user": {
    "name": "limengxun",
    "is_admin": 0
  },
  "quota": {
    "max_pods": 3,
    "gpu_count": 2,
    "memory_limit": -1,
    "storage_size": -1,
    "shm_size": -1
  }
}

/user/list

GETList all usernames in this node

Example

podx user/list

Output:

[
  "limengxun",
  "lijiayu",
  "wuji"
]

/user/ch-passwd

GETChange password

Parameters

passwd [string] The new password

/pod/create

POSTCreate a new pod

Parameters

ins [string] The instance to create, the actual pod name will be <username>-<ins>
image [string] The image of the pod to create from (e.g. ubuntu2204-cuda12.1:latest)

Example

podx pod/create ins:myins image:ubuntu2204-cuda12.1:latest

Output:

(The output should be the pod info in json)

/pod/delete

POSTDelete a pod. Please be careful, this operation is irreversible

Parameters

ins [string] The instance to delete

/pod/inspect

GETGet the information of a pod

Parameters

ins [string] The instance to get information

Example

podx pod/inspect ins:test

Output:

{
  "container_id": "014031e97c87",
  "name": "limengxun-test",
  "status": "running",
  "image": "exp:latest",
  "port_mapping": [
    "20806:22",
    "20299:8000"
  ],
  "gpu_ids": [],
  "memory_limit": -1,
  "shm_size": 8589934592
}

/pod/list

GETList all pods for the user

Example

podx pod/list

Output:

(A list of all pod names for the user)

/pod/start

POSTStart a pod

Parameters

ins [string] The instance to start

Example

podx pod/start ins:myins

Output:

(Text output of the pod start command)

/pod/stop

POSTStop a pod

Parameters

ins [string] The instance to stop

/pod/restart

POSTRestart a pod

Parameters

ins [string] The instance to restart

Example

podx pod/restart ins:myins

Output:

{log: " * Restarting OpenBSD Secure Shell server sshd..."}

/pod/exec

POSTExecute a command in a pod, the command will be executed as root user using bash. The default timeout is 30 seconds, long-running task will be terminated after the timeout. If you want to run a long-running task, please set the timeout to a larger value.

Parameters

ins [string] The instance id of the pod to execute command
cmd [string] The command to execute
timeout [number] optionalThe timeout of the command in seconds

Example

podx pod/exec ins:myins cmd:pwd

Output:

{
  "exit_code": 0,
  "log": "/workspace\r\n"
}

/pod/commit

POSTCommit a pod to an image, the image will be saved as <pody-commit-prefix>:<username>[-<tag>]. Note there are restrictions for image size and number of committed images for each user, please refer to the user quota for more details.

Parameters

ins [string] The instance id of the pod to commit
tag [string] optionalThe tag of the image to commit
msg [string] optionalThe commit message, this will be used as the image comment

Example

podx pod/commit ins:myins tag:latest

Output:

{
  "image_name": "pody-commit:limengxun-latest",
  "log": "Container myins committed to image: pody-commit:limengxun-latest"
}

/image/list

GETList all available images. The user committed images will omit the image name, leaving only the <username>-<tag>.

Example

podx image/list

Output:

['limengxun-cu126_base', 'captain-cuda:12.6.3-cudnn-devel-ubuntu22.04']

/image/inspect

GETGet the information of an image

Parameters

image [string] The image to inspect, should be a full image name.

Example

podx image/inspect image:limengxun-latest

Output:

{
  "name": "pody-commit:limengxun-latest",
  "id": "sha256:b9dbbd6961b98d2e489076b876dcb6fff37a57265b379066f7730cf8578aed05",
  "tags": [
    "pody-commit:limengxun-latest"
  ],
  "comment": "",
  "size": 28695585758,
  "exposed_ports": {
    "22/tcp": {},
    "8000/tcp": {}
  },
  "created": "2025-07-21T13:29:07.17395499Z"
}

/image/delete

POSTDelete a user committed image, please be careful, this operation is irreversible

Parameters

image [string] The image to delete, can only be user commit images.

Example

podx image/delete image:limengxun

Output:

{
  "log": "Image pody-commit:limengxun deleted"
}

/stat/cputime

GETGet the CPU time of the user(s) in seconds. The time is calculated using the [user CPU time] + [system CPU time] of all processes by the user(s)

Parameters

user [string] optionalThe usernames to get CPU time for, can be a comma-separated list, if not provided, will include all users
t [string] optionalThe start time of the process to include in the statistics, should be like: 1y, 1w, 1d, 1h, 1s, or a timestamp in seconds. If not provided, will include all time ranges.

Example

podx stat/cputime user:limengxun,lijiayu t:1w

Output:

{
  "limengxun": 1234567.89,
  "lijiayu": 9876543.21
}

/stat/gputime

GETGet the (rough) GPU time of the user(s) in seconds. The time is calculated as [the number of GPUs used] * [the time the GPU is used] for all processes by the user(s)

Parameters

user [string] optionalThe usernames to get GPU time for, can be a comma-separated list, if not provided, will include all users.
t [string] optionalThe start time of the process to include in the statistics, should be like: 1y, 1w, 1d, 1h, 1s, or a timestamp in seconds. If not provided, will include all time ranges

Example

podx stat/gputime user:limengxun,lijiayu t:1w

Output:

{
  "limengxun": 1234567.89,
  "lijiayu": 9876543.21
}

/host/gpu-ps

GETGet the process list running on the GPU(s)

Parameters

id [string] optionalThe id(s) of the GPU, multiple ids can be separated by comma

Example

podx host/gpu-ps id:0,1

Output:

{
  "0": [
    {
      "pid": 3936,
      "pod": "limengxun-main",
      "cmd": "python -m ...",
      "uptime": 2309249.4564814568,
      "memory_used": 709079040,
      "gpu_memory_used": 721420288
    }
  ],
  "1": [
    {
      "pid": 28963,
      "pod": "lijiayu-exp",
      "cmd": "/home/user/miniconda3/envs/vllm/bin/python -c from multiprocessing.spawn ...",
      "uptime": 1446117.9469604492,
      "memory_used": 8506048512,
      "gpu_memory_used": 22248685568
    }
  ]
}

/host/spec

GETGet the specification of the node

Example

podx host/spec

Output:

{
  "pody_version": "0.1.10",
  "docker_version": "26.1.5-ce",
  "nvidia_driver_version": "550.78",
  "nvidia_ctk_version": "NVIDIA Container Toolkit CLI version 1.17.5 commit:..."
}

/help

GETGet the help for a endpoint

Parameters

path [string] The path to get help for

Example

podx help path:"/pod/create"

Output:

[
  {
    "path": "/pod/create",
    "methods": [
      "POST"
    ],
    "params": [
      {
        "name": "ins",
        "optional": false
      },
      {
        "name": "image",
        "optional": false
      }
    ]
  }
]

/version

GETGet the version of the API

HTTP API ​

Summary ​

Details ​

/user/info

/user/list

/user/ch-passwd

/pod/create

/pod/delete

/pod/inspect

/pod/list

/pod/start

/pod/stop

/pod/restart

/pod/exec

/pod/commit

/image/list

/image/inspect

/image/delete

/stat/cputime

/stat/gputime

/host/gpu-ps

/host/spec

/help

/version

HTTP API

Summary

Details