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 and their admin status in this node


/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:myins 
Output:
(TO BE FILLED)

/pod/list

GETList all pods for the user

Example
sh
pody get pod/list 
Output:
(A list of all pods 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 /bin/bashThere is a timeout of 10 seconds for the command to execute, long running will be terminated.

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

/host/images

GETList all available images

Example
sh
pody get host/images 
Output:
(A list of all available images)

/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 gpu-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
        }
    ]
}