API Reference

The Docker Engine API is a RESTful API that allows you to interact with the Docker daemon programmatically. All Docker CLI commands use this API under the hood.

API Overview

Base URL and Versioning

# Unix socket (default on Linux/macOS)
http://localhost/v1.45/containers/json

# TCP (remote access)
https://192.168.1.10:2376/v1.45/containers/json

The API is versioned. Always specify the API version to ensure compatibility:

Docker Version	API Version	Release Date
27.x	1.46	2024
26.x	1.45	2024
25.x	1.44	2024
24.x	1.43	2023

Authentication

For remote access, TLS authentication is required:

bash

# Using curl with TLS certificates
curl --cert ~/.docker/cert.pem \
     --key ~/.docker/key.pem \
     --cacert ~/.docker/ca.pem \
     https://docker-host:2376/v1.45/info

Using the API via curl

bash

# Via Unix socket
curl --unix-socket /var/run/docker.sock http://localhost/v1.45/info

# Shorthand alias
alias dapi='curl -s --unix-socket /var/run/docker.sock'
dapi http://localhost/v1.45/info | jq

Container API

List Containers

bash

# GET /containers/json

# List running containers
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/containers/json"

# List all containers (including stopped)
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/containers/json?all=true"

# Filter by status
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/containers/json?filters=%7B%22status%22%3A%5B%22running%22%5D%7D"

Response:

json

[
  {
    "Id": "abc123def456...",
    "Names": ["/my-nginx"],
    "Image": "nginx:latest",
    "ImageID": "sha256:abc123...",
    "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
    "Created": 1700000000,
    "State": "running",
    "Status": "Up 2 hours",
    "Ports": [
      {
        "IP": "0.0.0.0",
        "PrivatePort": 80,
        "PublicPort": 8080,
        "Type": "tcp"
      }
    ],
    "NetworkSettings": {
      "Networks": {
        "bridge": {
          "IPAddress": "172.17.0.2"
        }
      }
    }
  }
]

Create a Container

bash

# POST /containers/create

curl --unix-socket /var/run/docker.sock \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "Image": "nginx:latest",
    "ExposedPorts": {
      "80/tcp": {}
    },
    "HostConfig": {
      "PortBindings": {
        "80/tcp": [{"HostPort": "8080"}]
      },
      "Memory": 536870912,
      "CpuShares": 512,
      "RestartPolicy": {
        "Name": "unless-stopped"
      }
    },
    "Env": [
      "NGINX_HOST=example.com"
    ],
    "Cmd": ["nginx", "-g", "daemon off;"]
  }' \
  "http://localhost/v1.45/containers/create?name=my-nginx"

Response:

json

{
  "Id": "abc123def456...",
  "Warnings": []
}

Start / Stop / Restart a Container

bash

# POST /containers/{id}/start
curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.45/containers/my-nginx/start"

# POST /containers/{id}/stop
curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.45/containers/my-nginx/stop?t=10"

# POST /containers/{id}/restart
curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.45/containers/my-nginx/restart"

# POST /containers/{id}/kill
curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.45/containers/my-nginx/kill?signal=SIGTERM"

Inspect a Container

bash

# GET /containers/{id}/json
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/containers/my-nginx/json" | jq

Container Logs

bash

# GET /containers/{id}/logs
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/containers/my-nginx/logs?stdout=true&stderr=true&tail=100"

# Stream logs
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/containers/my-nginx/logs?stdout=true&follow=true"

Execute a Command

bash

# Step 1: Create exec instance
# POST /containers/{id}/exec
EXEC_ID=$(curl --unix-socket /var/run/docker.sock \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "AttachStdout": true,
    "AttachStderr": true,
    "Cmd": ["ls", "-la", "/app"]
  }' \
  "http://localhost/v1.45/containers/my-nginx/exec" | jq -r '.Id')

# Step 2: Start exec instance
# POST /exec/{id}/start
curl --unix-socket /var/run/docker.sock \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"Detach": false, "Tty": false}' \
  "http://localhost/v1.45/exec/$EXEC_ID/start"

Remove a Container

bash

# DELETE /containers/{id}
curl --unix-socket /var/run/docker.sock \
  -X DELETE "http://localhost/v1.45/containers/my-nginx?force=true&v=true"

Image API

List Images

bash

# GET /images/json
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/images/json" | jq

Pull an Image

bash

# POST /images/create
curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.45/images/create?fromImage=nginx&tag=latest"

Build an Image

bash

# POST /build
tar czf - Dockerfile app.js package.json | \
  curl --unix-socket /var/run/docker.sock \
    -X POST \
    -H "Content-Type: application/tar" \
    --data-binary @- \
    "http://localhost/v1.45/build?t=my-app:1.0&dockerfile=Dockerfile"

Remove an Image

bash

# DELETE /images/{name}
curl --unix-socket /var/run/docker.sock \
  -X DELETE "http://localhost/v1.45/images/nginx:latest"

Network API

bash

# List networks
# GET /networks
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/networks" | jq

# Create a network
# POST /networks/create
curl --unix-socket /var/run/docker.sock \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "my-network",
    "Driver": "bridge",
    "IPAM": {
      "Config": [{"Subnet": "172.20.0.0/16", "Gateway": "172.20.0.1"}]
    }
  }' \
  "http://localhost/v1.45/networks/create"

# Connect container to network
# POST /networks/{id}/connect
curl --unix-socket /var/run/docker.sock \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"Container": "my-container"}' \
  "http://localhost/v1.45/networks/my-network/connect"

# Remove a network
# DELETE /networks/{id}
curl --unix-socket /var/run/docker.sock \
  -X DELETE "http://localhost/v1.45/networks/my-network"

Volume API

bash

# List volumes
# GET /volumes
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/volumes" | jq

# Create a volume
# POST /volumes/create
curl --unix-socket /var/run/docker.sock \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"Name": "my-data", "Driver": "local"}' \
  "http://localhost/v1.45/volumes/create"

# Remove a volume
# DELETE /volumes/{name}
curl --unix-socket /var/run/docker.sock \
  -X DELETE "http://localhost/v1.45/volumes/my-data"

System API

bash

# System information
# GET /info
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/info" | jq

# Docker version
# GET /version
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/version" | jq

# Ping
# GET /_ping
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/_ping"

# Disk usage
# GET /system/df
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/system/df" | jq

# System events (streaming)
# GET /events
curl --unix-socket /var/run/docker.sock \
  "http://localhost/v1.45/events?since=1700000000"

# Prune unused data
# POST /system/prune (available for containers, images, volumes, networks)
curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.45/containers/prune"

SDK Examples

Python SDK (docker-py)

python

import docker

# Connect to Docker daemon
client = docker.from_env()

# List containers
containers = client.containers.list()
for c in containers:
    print(f"{c.name}: {c.status}")

# Run a container
container = client.containers.run(
    "nginx:latest",
    name="my-nginx",
    detach=True,
    ports={"80/tcp": 8080}
)

# Build an image
image, logs = client.images.build(
    path=".",
    tag="my-app:1.0",
    rm=True
)

# Stream logs
for line in container.logs(stream=True):
    print(line.decode("utf-8"), end="")

Go SDK

package main

import (
    "context"
    "fmt"
    "github.com/docker/docker/api/types"
    "github.com/docker/docker/client"
)

func main() {
    ctx := context.Background()
    cli, err := client.NewClientWithOpts(client.FromEnv)
    if err != nil {
        panic(err)
    }

    containers, err := cli.ContainerList(ctx, types.ContainerListOptions{})
    if err != nil {
        panic(err)
    }

    for _, container := range containers {
        fmt.Printf("%s %s\n", container.ID[:12], container.Image)
    }
}

API Endpoints Summary

Method	Endpoint	Description
GET	`/containers/json`	List containers
POST	`/containers/create`	Create a container
POST	`/containers/{id}/start`	Start a container
POST	`/containers/{id}/stop`	Stop a container
DELETE	`/containers/{id}`	Remove a container
GET	`/containers/{id}/logs`	Get container logs
GET	`/images/json`	List images
POST	`/images/create`	Pull an image
POST	`/build`	Build an image
GET	`/networks`	List networks
POST	`/networks/create`	Create a network
GET	`/volumes`	List volumes
POST	`/volumes/create`	Create a volume
GET	`/info`	System information
GET	`/version`	Docker version

Next Steps

Docker Engine Architecture — Understand the API's role in Docker
CLI Commands Reference — CLI commands that use the API
Configuration Management — Configure API access
Security Best Practices — Secure API access
CLI Reference — Complete command reference

API Reference ​

API Overview ​

Base URL and Versioning ​

Authentication ​

Using the API via curl ​

Container API ​

List Containers ​

Create a Container ​

Start / Stop / Restart a Container ​

Inspect a Container ​

Container Logs ​

Execute a Command ​

Remove a Container ​

Image API ​

List Images ​

Pull an Image ​

Build an Image ​

Remove an Image ​

Network API ​

Volume API ​

System API ​

SDK Examples ​

Python SDK (docker-py) ​

Go SDK ​

API Endpoints Summary ​

Next Steps ​

API Reference

API Overview

Base URL and Versioning

Authentication

Using the API via curl

Container API

List Containers

Create a Container

Start / Stop / Restart a Container

Inspect a Container

Container Logs

Execute a Command

Remove a Container

Image API

List Images

Pull an Image

Build an Image

Remove an Image

Network API

Volume API

System API

SDK Examples

Python SDK (docker-py)

Go SDK

API Endpoints Summary

Next Steps