16 KiB
Docker Remote API
Docker's Remote API uses an open schema model. In this model, unknown properties in incoming messages are ignored. Client applications need to take this behavior into account to ensure they do not break when talking to newer Docker daemons.
The API tends to be REST, but for some complex commands, like attach or pull, the HTTP connection is hijacked to transport STDOUT, STDIN, and STDERR.
By default the Docker daemon listens on unix:///var/run/docker.sock
and the
client must have root
access to interact with the daemon. If a group named
docker
exists on your system, docker
applies ownership of the socket to the
group.
To connect to the Docker daemon with cURL you need to use cURL 7.40 or
later, as these versions have the --unix-socket
flag available. To
run curl
against the daemon on the default socket, use the
following:
curl --unix-socket /var/run/docker.sock http:/containers/json
If you have bound the Docker daemon to a different socket path or TCP port, you would reference that in your cURL rather than the default.
The current version of the API is v1.24 which means calling /info
is the same
as calling /v1.24/info
. To call an older version of the API use
/v1.23/info
.
Use the table below to find the API version for a Docker version:
Docker version | API version | 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 |
Refer to the GitHub repository for older releases.
Authentication
Authentication configuration is handled client side, so the
client has to send the authConfig
as a POST
in /images/(name)/push
. The
authConfig
, set as the X-Registry-Auth
header, is currently a Base64 encoded
(JSON) string with the following structure:
{"username": "string", "password": "string", "email": "string",
"serveraddress" : "string", "auth": ""}
Callers should leave the auth
empty. The serveraddress
is a domain/ip
without protocol. Throughout this structure, double quotes are required.
Using Docker Machine with the API
If you are using docker-machine
, the Docker daemon is on a host that
uses an encrypted TCP socket using TLS. This means, for Docker Machine users,
you need to add extra parameters to curl
or wget
when making test
API requests, for example:
curl --insecure \
--cert $DOCKER_CERT_PATH/cert.pem \
--key $DOCKER_CERT_PATH/key.pem \
https://YOUR_VM_IP:2376/images/json
wget --no-check-certificate --certificate=$DOCKER_CERT_PATH/cert.pem \
--private-key=$DOCKER_CERT_PATH/key.pem \
https://YOUR_VM_IP:2376/images/json -O - -q
Docker Events
The following diagram depicts the container states accessible through the API.
Some container-related events are not affected by container state, so they are not included in this diagram. These events are:
- export emitted by
docker export
- exec_create emitted by
docker exec
- exec_start emitted by
docker exec
after exec_create - detach emitted when client is detached from container process
- exec_detach emitted when client is detached from exec process
Running docker rmi
emits an untag event when removing an image name. The rmi
command may also emit delete events when images are deleted by ID directly or by deleting the last tag referring to the image.
Acknowledgment: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post Docker Events Explained.
Version history
This section lists each version from latest to oldest. Each listing includes a link to the full documentation set and the changes relevant in that release.
v1.24 API changes
Docker Remote API v1.24 documentation
POST /containers/create
now takesStorageOpt
field.GET /info
now returnsSecurityOptions
field, showing ifapparmor
,seccomp
, orselinux
is supported.GET /networks
now supports filtering bylabel
anddriver
.GET /containers/json
now supports filtering containers bynetwork
name or id.POST /containers/create
now takesMaximumIOps
andMaximumIOBps
fields. Windows daemon only.POST /containers/create
now returns an HTTP 400 "bad parameter" message if no command is specified (instead of an HTTP 500 "server error")GET /images/search
now takes afilters
query parameter.GET /events
now supports areload
event that is emitted when the daemon configuration is reloaded.GET /events
now supports filtering by daemon name or ID.GET /events
now supports adetach
event that is emitted on detaching from container process.GET /events
now supports anexec_detach
event that is emitted on detaching from exec process.GET /images/json
now supports filterssince
andbefore
.POST /containers/(id or name)/start
no longer accepts aHostConfig
.POST /images/(name)/tag
no longer has aforce
query parameter.GET /images/search
now supports maximum returned search resultslimit
.POST /containers/{name:.*}/copy
is now removed and errors out starting from this API version.- API errors are now returned as JSON instead of plain text.
POST /containers/create
andPOST /containers/(id)/start
allow you to configure kernel parameters (sysctls) for use in the container.POST /v1.23/containers/<container ID>/exec
andPOST /v1.23/exec/<exec ID>/start
no longer expects a "Container" field to be present. This property was not used and is no longer sent by the docker client.
v1.23 API changes
Docker Remote API v1.23 documentation
GET /containers/json
returns the state of the container, one ofcreated
,restarting
,running
,paused
,exited
ordead
.GET /containers/json
returns the mount points for the container.GET /networks/(name)
now returns anInternal
field showing whether the network is internal or not.GET /networks/(name)
now returns anEnableIPv6
field showing whether the network has ipv6 enabled or not.POST /containers/(name)/update
now supports updating container's restart policy.POST /networks/create
now supports enabling ipv6 on the network by setting theEnableIPv6
field (doing this with a label will no longer work).GET /info
now returnsCgroupDriver
field showing what cgroup driver the daemon is using;cgroupfs
orsystemd
.GET /info
now returnsKernelMemory
field, showing if "kernel memory limit" is supported.POST /containers/create
now takesPidsLimit
field, if the kernel is >= 4.3 and the pids cgroup is supported.GET /containers/(id or name)/stats
now returnspids_stats
, if the kernel is >= 4.3 and the pids cgroup is supported.POST /containers/create
now allows you to override usernamespaces remapping and use privileged options for the container.POST /containers/create
now allows specifyingnocopy
for named volumes, which disables automatic copying from the container path to the volume.POST /auth
now returns anIdentityToken
when supported by a registry.POST /containers/create
with bothHostname
andDomainname
fields specified will result in the container's hostname being set toHostname
, rather thanHostname.Domainname
.GET /volumes
now supports more filters, new added filters arename
anddriver
.GET /containers/(id or name)/logs
now accepts adetails
query parameter to stream the extra attributes that were provided to the containersLogOpts
, such as environment variables and labels, with the logs.
v1.22 API changes
Docker Remote API v1.22 documentation
POST /container/(name)/update
updates the resources of a container.GET /containers/json
supports filterisolation
on Windows.GET /containers/json
now returns the list of networks of containers.GET /info
Now returnsArchitecture
andOSType
fields, providing information about the host architecture and operating system type that the daemon runs on.GET /networks/(name)
now returns aName
field for each container attached to the network.GET /version
now returns theBuildTime
field in RFC3339Nano format to make it consistent with other date/time values returned by the API.AuthConfig
now supports aregistrytoken
for token based authenticationPOST /containers/create
now has a 4M minimum value limit forHostConfig.KernelMemory
- Pushes initiated with
POST /images/(name)/push
and pulls initiated withPOST /images/create
will be cancelled if the HTTP connection making the API request is closed before the push or pull completes. POST /containers/create
now allows you to set a read/write rate limit for a device (in bytes per second or IO per second).GET /networks
now supports filtering byname
,id
andtype
.POST /containers/create
now allows you to set the static IPv4 and/or IPv6 address for the container.POST /networks/(id)/connect
now allows you to set the static IPv4 and/or IPv6 address for the container.GET /info
now includes the number of containers running, stopped, and paused.POST /networks/create
now supports restricting external access to the network by setting theInternal
field.POST /networks/(id)/disconnect
now includes aForce
option to forcefully disconnect a container from networkGET /containers/(id)/json
now returns theNetworkID
of containers.POST /networks/create
Now supports an options field in the IPAM config that provides options for custom IPAM plugins.GET /networks/{network-id}
Now returns IPAM config options for custom IPAM plugins if any are available.GET /networks/<network-id>
now returns subnets info for user-defined networks.GET /info
can now return aSystemStatus
field useful for returning additional information about applications that are built on top of engine.
v1.21 API changes
Docker Remote API v1.21 documentation
GET /volumes
lists volumes from all volume drivers.POST /volumes/create
to create a volume.GET /volumes/(name)
get low-level information about a volume.DELETE /volumes/(name)
remove a volume with the specified name.VolumeDriver
was moved fromconfig
toHostConfig
to make the configuration portable.GET /images/(name)/json
now returns information about an image'sRepoTags
andRepoDigests
.- The
config
option now accepts the fieldStopSignal
, which specifies the signal to use to kill a container. GET /containers/(id)/stats
will return networking information respectively for each interface.- The
HostConfig
option now includes theDnsOptions
field to configure the container's DNS options. POST /build
now optionally takes a serialized map of build-time variables.GET /events
now includes atimenano
field, in addition to the existingtime
field.GET /events
now supports filtering by image and container labels.GET /info
now lists engine version information and return the information ofCPUShares
andCpuset
.GET /containers/json
will returnImageID
of the image used by container.POST /exec/(name)/start
will now return an HTTP 409 when the container is either stopped or paused.GET /containers/(name)/json
now accepts asize
parameter. Setting this parameter to '1' returns container size information in theSizeRw
andSizeRootFs
fields.GET /containers/(name)/json
now returns aNetworkSettings.Networks
field, detailing network settings per network. This field deprecates theNetworkSettings.Gateway
,NetworkSettings.IPAddress
,NetworkSettings.IPPrefixLen
, andNetworkSettings.MacAddress
fields, which are still returned for backward-compatibility, but will be removed in a future version.GET /exec/(id)/json
now returns aNetworkSettings.Networks
field, detailing networksettings per network. This field deprecates theNetworkSettings.Gateway
,NetworkSettings.IPAddress
,NetworkSettings.IPPrefixLen
, andNetworkSettings.MacAddress
fields, which are still returned for backward-compatibility, but will be removed in a future version.- The
HostConfig
option now includes theOomScoreAdj
field for adjusting the badness heuristic. This heuristic selects which processes the OOM killer kills under out-of-memory conditions.
v1.20 API changes
Docker Remote API v1.20 documentation
GET /containers/(id)/archive
get an archive of filesystem content from a container.PUT /containers/(id)/archive
upload an archive of content to be extracted to an existing directory inside a container's filesystem.POST /containers/(id)/copy
is deprecated in favor of the abovearchive
endpoint which can be used to download files and directories from a container.- The
hostConfig
option now accepts the fieldGroupAdd
, which specifies a list of additional groups that the container process will run as.
v1.19 API changes
Docker Remote API v1.19 documentation
- When the daemon detects a version mismatch with the client, usually when the client is newer than the daemon, an HTTP 400 is now returned instead of a 404.
GET /containers/(id)/stats
now acceptsstream
bool to get only one set of stats and disconnect.GET /containers/(id)/logs
now accepts asince
timestamp parameter.GET /info
The fieldsDebug
,IPv4Forwarding
,MemoryLimit
, andSwapLimit
are now returned as boolean instead of as an int. In addition, the end point now returns the new boolean fieldsCpuCfsPeriod
,CpuCfsQuota
, andOomKillDisable
.- The
hostConfig
option now accepts the fieldsCpuPeriod
andCpuQuota
POST /build
acceptscpuperiod
andcpuquota
options
v1.18 API changes
Docker Remote API v1.18 documentation
GET /version
now returnsOs
,Arch
andKernelVersion
.POST /containers/create
andPOST /containers/(id)/start
allow you to set ulimit settings for use in the container.GET /info
now returnsSystemTime
,HttpProxy
,HttpsProxy
andNoProxy
.GET /images/json
added aRepoDigests
field to include image digest information.POST /build
can now set resource constraints for all containers created for the build.CgroupParent
can be passed in the host config to setup container cgroups under a specific cgroup.POST /build
closing the HTTP request cancels the buildPOST /containers/(id)/exec
includesWarnings
field to response.