docker

Docker Engine

developer_tools

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. docker ps is GET /containers/json). The notable exception is running containers, which consists of several API calls.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "message": "page not found"
}

Versioning

The API is usually changed in each release of Docker, so API calls are versioned to ensure that clients don't break.

For Docker Engine 17.09, the API version is 1.32. To lock to this version, you prefix the URL with /v1.32. For example, calling /info is the same as calling /v1.32/info.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

In previous versions of Docker, it was possible to access the API without providing a version. This behaviour is now deprecated will be removed in a future version of Docker.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer Docker daemons.

This documentation is for version 1.33 of the API. Use this table to find documentation for previous versions of the API:

Docker version API version Changes
17.09.x 1.31 API changes
17.07.x 1.31 API changes
17.06.x 1.30 API changes
17.05.x 1.29 API changes
17.04.x 1.28 API changes
17.03.1 1.27 API changes
1.13.1 & 17.03.0 1.26 API changes
1.13.0 1.25 API changes
1.12.x 1.24 API changes
1.11.x 1.23 API changes
1.10.x 1.22 API changes
1.9.x 1.21 API changes
1.8.x 1.20 API changes
1.7.x 1.19 API changes
1.6.x 1.18 API changes

Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as POST /images/(name)/push. These are sent as X-Registry-Auth header as a Base64 encoded (JSON) string with the following structure:

{
  "username": "string",
  "password": "string",
  "email": "string",
  "serveraddress": "string"
}

The serveraddress is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the /auth endpoint, you can just pass this instead of credentials:

{
  "identitytoken": "9cbaf023786cd7..."
}

Resources

Config

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

POST
/configs/create
POST
/configs/{id}/update
DELETE
/configs/{id}
GET
/configs/{id}
GET
/configs
Container

Create and manage containers.

POST
/containers/create
GET
/containers/json
POST
/containers/prune
GET
/containers/{id}/archive
HEAD
/containers/{id}/archive
PUT
/containers/{id}/archive
GET
/containers/{id}/attach/ws
POST
/containers/{id}/attach
GET
/containers/{id}/changes
GET
/containers/{id}/export
GET
/containers/{id}/json
POST
/containers/{id}/kill
GET
/containers/{id}/logs
POST
/containers/{id}/pause
POST
/containers/{id}/rename
POST
/containers/{id}/resize
POST
/containers/{id}/restart
POST
/containers/{id}/start
GET
/containers/{id}/stats
POST
/containers/{id}/stop
GET
/containers/{id}/top
POST
/containers/{id}/unpause
POST
/containers/{id}/update
POST
/containers/{id}/wait
DELETE
/containers/{id}
Distribution
GET
/distribution/{name}/json
Exec

Run new commands inside running containers. See the command-line reference for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, docker exec.

POST
/containers/{id}/exec
GET
/exec/{id}/json
POST
/exec/{id}/resize
POST
/exec/{id}/start
Image
POST
/build/prune
POST
/build
POST
/commit
POST
/images/create
GET
/images/get
GET
/images/json
POST
/images/load
POST
/images/prune
GET
/images/search
GET
/images/{name}/get
GET
/images/{name}/history
GET
/images/{name}/json
POST
/images/{name}/push
POST
/images/{name}/tag
DELETE
/images/{name}