2.1.3.2 Image API Routes

A focused guide to Image API Routes, connecting core concepts with practical Docker and container operations.

Image API routes are the set of HTTP endpoints, under the /images and /build paths, that the Docker daemon exposes for building, listing, inspecting, pulling, pushing, and removing images.

Listing Local Images

A route returns every image currently stored on the daemon's host, including its tags, size, and creation date.

curl --unix-socket /var/run/docker.sock http://localhost/images/json

This is the same data docker images formats into a table for display.

Building an Image

The build route accepts a tar archive of the build context (the Dockerfile and any files it references) and streams back build progress as the daemon executes each instruction.

tar -czf context.tar.gz Dockerfile .
curl --unix-socket /var/run/docker.sock -X POST \
  --data-binary @context.tar.gz \
  "http://localhost/build?t=myapp:1.0"

The streamed response reports each build step's output as it happens, which is what the CLI's live build log is rendered from.

Pulling and Pushing Images

Routes for pulling and pushing handle transferring image layers to and from a registry, streaming progress information about each layer being transferred.

curl --unix-socket /var/run/docker.sock -X POST "http://localhost/images/create?fromImage=postgres&tag=16"

Inspecting a Specific Image

A dedicated route returns full metadata about a particular image — its layers, configuration, exposed ports, and default startup command.

curl --unix-socket /var/run/docker.sock http://localhost/images/myapp:1.0/json

Removing Images

A route removes an image by name or ID, which fails if any existing container still depends on it, mirroring the same dependency check the CLI's docker rmi performs.

curl --unix-socket /var/run/docker.sock -X DELETE http://localhost/images/myapp:1.0

Why These Routes Matter

Tooling that needs to manage images programmatically — build automation, custom registries, dashboards showing local image state — relies on these same routes directly, since they represent the complete set of operations the daemon supports for image management.