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/info	GET	ins
/pod/list	GET
/pod/start	POST	ins
/pod/stop	POST	ins
/pod/restart	POST	ins
/pod/exec	POST	ins, cmd
/host/images	GET
/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

GETList all usernames and their admin status in this node

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/info

GETGet the information of a pod

Parameters

• ins [string] The instance to get information

Example

podx pod/info 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
}

---

/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. There is a timeout of 10 seconds for the command to execute, long running task will be terminated.

Parameters

• ins [string] The instance id of the pod to execute command
• cmd [string] The command to execute

Example

podx pod/exec ins:myins cmd:pwd 

Output:

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

---

/host/images

GETList all available images

Example

podx host/images 

Output:

(A list of all available image names)

---

/host/gpu-ps

GETGet the process list running on the GPU(s)

Parameters

• id [string] The 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