How to use Podman REST API service to query and manage Linux containers system

How to use Podman REST API service to query and manage Linux containers system


Here in this article we will see how we can start the Podman API service and interact with the API service to gather information related to our Linux containers and images hosted on Podman managed standalone Linux container system.

Test Environment

Fedora 32

What is Podman API service

Podman API service helps in connecting to the linux system where Podman containers and running. These API service help in carrying out various task related to containers and images using the API call.

If you are interested in watching the video. Here is the YouTube video on the same step by step procedure outlined below.


Step1: Start the Podman API service

In order to use the Podman API service we first need to start the service on a linux. We can start the service to accept connection on tcp channel or using a socket. Below is an example of starting the service using tcp channel and port.

[root@fed32 ~]# podman system service tcp:localhost:8080 --time=0 &

This will enable the podman api service and it will run as long as sytem in up and running or until we manually stop it.

Step2: Install jq for structuring the JSON data

The Podman API service query responses are in the format of JSON data. jq package help in formatting the JSON data in a structured and readable format. It helps in slicing and filtering the JSON data. So if this package is not already available on your system. Please install it for JSON data querying.

[root@fed32 tmp]# dnf -y install jq
Last metadata expiration check: 0:08:06 ago on Tue 24 Nov 2020 09:38:19 PM IST.
Dependencies resolved.
 Package                        Architecture                Version                                 Repository                    Size
 jq                             x86_64                      1.6-4.fc32                              fedora                       180 k
Installing dependencies:
 oniguruma                      x86_64                      6.9.5-4.rev1.fc32                       updates                      221 k
  jq-1.6-4.fc32.x86_64                                        oniguruma-6.9.5-4.rev1.fc32.x86_64                                       


Step3: Query Podman information using REST API call

Lets try to connect to the podman api service started on tcp port 8080 to gather the Podman system information as shown below.

You can also directly access the following URL in browser to fetch the information.

URL – http://localhost:8080/v1.0.0/libpod/info

[root@fed32 tmp]# dnf -y install jq
[root@fed32 ~]# curl -k http://localhost:8080/v1.0.0/libpod/info | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1682  100  1682    0     0   2674      0 --:--:-- --:--:-- --:--:--  2669
  "host": {
    "arch": "amd64",
    "buildahVersion": "1.16.1",
    "cgroupManager": "systemd",
    "cgroupVersion": "v2",
    "conmon": {
      "package": "conmon-2.0.21-2.fc32.x86_64",
      "path": "/usr/bin/conmon",
      "version": "conmon version 2.0.21, commit: 81d18b6c3ffc266abdef7ca94c1450e669a6a388"
    "cpus": 1,
    "distribution": {
      "distribution": "fedora",
      "version": "32"


Step4: List all the available containers in the system and images

Here lets try to list the available containers in our system whether they are active or in active state. As you could see from the below output i have one container names busyman2 which is currently in the exited state.

[root@fed32 ~]# curl -k http://localhost:8080/v1.40.0/libpod/containers/json?all=true |jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1165  100  1165    0     0   103k      0 --:--:-- --:--:-- --:--:--  103k
    "Command": [
    "Created": 1603670870,
    "CreatedAt": "",
    "Exited": false,
    "ExitedAt": 1603774767,
    "ExitCode": 0,
    "Id": "a74a040b886f026ae19b48cd8247257d00439958e9208748ef44563e3686a07e",
    "Image": "",
    "ImageID": "f0b02e9d092d905d0d87a8455a1ae3e9bb47b4aa3dc125125ca5cd10d6441c9f",
    "IsInfra": false,
    "Labels": null,
    "Mounts": [
    "Names": [
[root@fed32 ~]# curl -k http://localhost:8080/v1.40.0/libpod/images/json | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1042  100  1042    0     0   6058      0 --:--:-- --:--:-- --:--:--  6058
    "Id": "b6611cf6b4a9352cb972700e3c6d5cfa965b3b3550b635dcb7ec3a6ee9aba59d",
    "RepoTags": [
    "Created": 1603499017,
    "Size": 457388557,
    "Labels": {
      "io.buildah.version": "1.16.1",
      "license": "MIT",
      "name": "fedora",
      "vendor": "Fedora Project",
      "version": "32"
    "Containers": 1,
    "Names": [

Step5: Pull an image from registry

Let’s try to pull an nginx images from registry. In order to pull the image from a registry we need to pass the image name in the reference as a parameter to API URL as shown below.

[root@fed32 ~]# curl -XPOST http://localhost:8080/v1.40.0/libpod/images/pull?
{"stream":"Trying to pull"}
{"stream":"Getting image source signaturesn"}
{"stream":"Copying blob sha256:571d7e8523079365a306fa2fefb9bea2b500135098c32c829cd6bd738e2838a5n"}
{"stream":"Copying blob sha256:d20aa7ccdb7773f8f448eef3f7a79a3181efa5dad07a899e9313835038a68dc9n"}
{"stream":"Copying blob sha256:852e50cd189dfeb54d97680d9fa6bed21a6d7d18cfb56d6abfe2de9d7f173795n"}
{"stream":"Copying blob sha256:8b03f1e11359b03ca2aba5f3436526fd523dc4dfa0f1b5c10a9257a9cb9f37ccn"}
{"stream":"Copying blob sha256:addb10abd9cb2f0b7497496559d847a5c53c73d891d0825a4d75cca7f246944en"}
{"stream":"Copying config sha256:bc9a0695f5712dcaaa09a5adc415a3936ccba13fc2587dfd76b1b8aeea3f221cn"}
{"stream":"Writing manifest to image destinationn"}
{"stream":"Storing signaturesn"}
[root@fed32 ~]# podman images
REPOSITORY                   TAG     IMAGE ID      CREATED       SIZE      latest  bc9a0695f571  11 hours ago  137 MB

Step6: Create a container from nginx image and pull the stats of the container using API url

Now we have the nginx image available on our system. Lets try to create a container from the nginx image as shown below and try to get the statistics from the API url.

[root@fed32 ~]# podman run -d -p 8081:80 --name nginxTest
curl -k http://localhost:8080/v1.40.0/libpod/containers/nginxTest/stats

This API service can be further utlizied by calling them from with the Python or Bash script and the response can be further filtered formatted as per your requirements.

Hope you enjoyed reading this article. Thank you..