Docker Engine API

Docker provides an API for interacting with the Docker daemon (called the Docker Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and scale Docker apps and solutions. If Go or Python don't work for you, you can use the Docker Engine API directly.

For information about Docker Engine SDKs, see Develop with Docker Engine SDKs.

The Docker Engine API is a RESTful API accessed by an HTTP client such as wget or curl, or the HTTP library which is part of most modern programming languages.

View the API reference

You can view the reference for the latest version of the API or choose a specific version.

Versioned API and SDK

The version of the Docker Engine API you should use depends upon the version of your Docker daemon and Docker client.

A given version of the Docker Engine SDK supports a specific version of the Docker Engine API, as well as all earlier versions. If breaking changes occur, they are documented prominently.

Note

The Docker daemon and client don't necessarily need to be the same version at all times. However, keep the following in mind.

• If the daemon is newer than the client, the client doesn't know about new features or deprecated API endpoints in the daemon.

• If the client is newer than the daemon, the client can request API endpoints that the daemon doesn't know about.

A new version of the API is released when new features are added. The Docker API is backward-compatible, so you don't need to update code that uses the API unless you need to take advantage of new features.

To see the highest version of the API your Docker daemon and client support, use docker version:

$ docker version
Client: Docker Engine - Community
 Version:           27.1.2
 API version:       1.46
 Go version:        go1.21.13
 Git commit:        d01f264
 Built:             Mon Aug 12 11:51:13 2024
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          27.1.2
  API version:      1.46 (minimum version 1.24)
  Go version:       go1.21.13
  Git commit:       f9522e5
  Built:            Mon Aug 12 11:51:13 2024
  OS/Arch:          linux/amd64
  Experimental:     false
  ...

You can specify the API version to use in any of the following ways:

• When using the SDK, use the latest version. At a minimum, use the version that incorporates the API version with the features you need.

• When using curl directly, specify the version as the first part of the URL. For instance, if the endpoint is /containers/ you can use /v1.46/containers/.

• To force the Docker CLI or the Docker Engine SDKs to use an older version of the API than the version reported by docker version, set the environment variable DOCKER_API_VERSION to the correct version. This works on Linux, Windows, or macOS clients.

  $ DOCKER_API_VERSION='1.44'
  

  While the environment variable is set, that version of the API is used, even if the Docker daemon supports a newer version. This environment variable disables API version negotiation, so you should only use it if you must use a specific version of the API, or for debugging purposes.

• The Docker Go SDK allows you to enable API version negotiation, automatically selects an API version that's supported by both the client and the Docker Engine that's in use.

• For the SDKs, you can also specify the API version programmatically as a parameter to the client object. See the Go constructor or the Python SDK documentation for client.

API version matrix

Deprecated API versions

API versions before v1.24 are deprecated. You can find archived documentation for deprecated versions of the API in the code repository on GitHub:

• Documentation for API versions 1.23 and before.
• Documentation for API versions 1.17 and before.