Container information API

Containers API provides access to container inventory data collected from hosts, including running containers, container images, and container volumes. It also exposes a per-host summary endpoint with aggregated counts.

List containers

URI: https://hub.cfengine.com/api/inventory/containers

Method: GET

Parameters:

• hostkey (string) Filter by host key (exact match).
• owner (string) Filter by owner (exact match).
• name (string) Filter by container name (case-insensitive substring match).
• image (string) Filter by image (case-insensitive substring match).
• status (string) Filter by container state (case-insensitive substring match).
• engine (string) Filter by container engine (exact match, e.g. docker, podman).
• page (integer, default: 1) Page number for pagination.
• per_page (integer, default: 20) Number of items per page. Allowed range: 1–100.
• sort (string, default: “started_at”) Column to sort by. Allowed values:
  • hostkey
  • owner
  • id
  • name
  • image
  • state
  • engine
  • started_at
  • collected_at
• order (string, default: “desc”) Sort direction. Allowed values:
  • asc
  • desc

Example request (curl):

curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/containers

Successful response example:

HTTP 200 OK
{
    "data": [
        {
            "hostkey": "SHA=abc123...",
            "owner": "root",
            "id": "9f1c7e2b4a55",
            "name": "web",
            "image": "nginx:1.27",
            "image_id": "sha256:7d3f...",
            "command": "nginx -g 'daemon off;'",
            "state": "running",
            "ports": [
                {
                    "container_port": 80,
                    "host_ip": "0.0.0.0",
                    "host_port": 8080,
                    "protocol": "tcp"
                }
            ],
            "engine": "docker",
            "started_at": "2026-05-20 12:30:00",
            "collected_at": "2026-05-26 09:00:00",
            "details": null
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1748246400,
        "total": 1
    }
}

Responses:

List container images

URI: https://hub.cfengine.com/api/inventory/container-images

Method: GET

Parameters:

• hostkey (string) Filter by host key (exact match).
• owner (string) Filter by owner (exact match).
• repository (string) Filter by image repository (case-insensitive substring match).
• tag (string) Filter by image tag (case-insensitive substring match).
• page (integer, default: 1) Page number for pagination.
• per_page (integer, default: 20) Number of items per page. Allowed range: 1–100.
• sort (string, default: “created_at”) Column to sort by. Allowed values:
  • hostkey
  • owner
  • id
  • repository
  • tag
  • size_bytes
  • created_at
  • collected_at
• order (string, default: “desc”) Sort direction. Allowed values:
  • asc
  • desc

Example request (curl):

curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/container-images

Successful response example:

HTTP 200 OK
{
    "data": [
        {
            "hostkey": "SHA=abc123...",
            "owner": "root",
            "id": "sha256:7d3f...",
            "repository": "nginx",
            "tag": "1.27",
            "size_bytes": 142000000,
            "created_at": "2026-05-01 10:00:00",
            "collected_at": "2026-05-26 09:00:00"
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1748246400,
        "total": 1
    }
}

Responses:

List container volumes

URI: https://hub.cfengine.com/api/inventory/container-volumes

Method: GET

Parameters:

• hostkey (string) Filter by host key (exact match).
• owner (string) Filter by owner (exact match).
• volume_name (string) Filter by volume name (case-insensitive substring match).
• driver (string) Filter by volume driver (case-insensitive substring match).
• page (integer, default: 1) Page number for pagination.
• per_page (integer, default: 20) Number of items per page. Allowed range: 1–100.
• sort (string, default: “created_at”) Column to sort by. Allowed values:
  • hostkey
  • owner
  • name
  • driver
  • size_bytes
  • created_at
  • collected_at
• order (string, default: “desc”) Sort direction. Allowed values:
  • asc
  • desc

Example request (curl):

curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/container-volumes

Successful response example:

HTTP 200 OK
{
    "data": [
        {
            "hostkey": "SHA=abc123...",
            "owner": "root",
            "name": "web-data",
            "driver": "local",
            "size_bytes": 5242880,
            "created_at": "2026-05-15 08:00:00",
            "collected_at": "2026-05-26 09:00:00"
        }
    ],
    "meta": {
        "count": 1,
        "page": 1,
        "timestamp": 1748246400,
        "total": 1
    }
}

Responses:

Get containers summary for a host

Returns aggregated container, image, and volume counts for a single host, along with the list of distinct container engines detected on it.

URI: https://hub.cfengine.com/api/inventory/containers/summary/:hostkey

Method: GET

Path parameters:

• hostkey (string) Host key to compute the summary for. The caller must have access to the host.

Example request (curl):

curl --user <username>:<password> -X GET https://hub.cfengine.com/api/inventory/containers/summary/SHA=abc123

Successful response example:

HTTP 200 OK
{
    "hostkey": "SHA=abc123...",
    "containers": {
        "running": 3,
        "total": 5
    },
    "images": {
        "named": 8,
        "total": 12
    },
    "volumes": {
        "count": 4,
        "total_size_bytes": 20971520
    },
    "engines": [
        "docker",
        "podman"
    ]
}

Responses:

Permissions

All Containers API endpoints are gated by the same RBAC permission used for the Query API (query.post). The /inventory/containers/summary/:hostkey endpoint additionally requires the caller to have access to the requested host.