HTTP API | Pody-doc
Description: Documentation for pody manager.

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 ​

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 ​

podx pody curl

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
sh

    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
sh

    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
sh

    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
sh

    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
sh

    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
sh

    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
sh

    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
sh

    podx pod/exec ins:myins cmd:pwd

Output:

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

### /host/images

GETList all available images

Example
sh

    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
sh

    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
sh

    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
sh

    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