Skip to content

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

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

Details

TIP

Here examples of API calls are provided using pody utility. More information about pody can be found here.


/user/info

GETGet the information of the user

Example
sh
pody get user/info 
Output:
{
  "user": {
    "name": "limengxun",
    "is_admin": 0
  },
  "quota": {
    "max_pods": -1,
    "gpu_count": -1,
    "memory_limit": -1
  }
}

/user/list

GETList all usernames in this node

Example
sh
pody get 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
sh
pody post 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
sh
pody get pod/info ins:test 
Output:
{
  "name": "limengxun-test",
  "status": "running",
  "image": "exp:latest",
  "port_mapping": [
    "20806:22",
    "20299:8000"
  ],
  "gpu_ids": []
}

/pod/list

GETList all pods for the user

Example
sh
pody get 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
sh
pody post 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

/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
sh
pody post pod/exec ins:myins cmd:pwd 
Output:
{
  "exit_code": 0,
  "log": "/workspace\r\n"
}

/host/images

GETList all available images

Example
sh
pody get 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
sh
pody get 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
    }
  ]
}