docs/api/v1.24.md

   1 ---
   2 title: "Engine API v1.24"
   3 description: "API Documentation for Docker"
   4 keywords: "API, Docker, rcli, REST, documentation"
   5 redirect_from:
   6 - /engine/reference/api/docker_remote_api_v1.24/
   7 - /reference/api/docker_remote_api_v1.24/
   8 ---
   9
  10 <!-- This file is maintained within the docker/docker Github
  11      repository at https://github.com/docker/docker/. Make all
  12      pull requests against that repo. If you see this file in
  13      another repository, consider it read-only there, as it will
  14      periodically be overwritten by the definitive file. Pull
  15      requests which include edits to this file in other repositories
  16      will be rejected.
  17 -->
  18
  19 ## 1. Brief introduction
  20
  21  - The daemon listens on `unix:///var/run/docker.sock` but you can
  22    [Bind Docker to another host/port or a Unix socket](../reference/commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
  23  - The API tends to be REST. However, for some complex commands, like `attach`
  24    or `pull`, the HTTP connection is hijacked to transport `stdout`,
  25    `stdin` and `stderr`.
  26
  27 ## 2. Errors
  28
  29 The Engine 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:
  30
  31     {
  32         "message": "page not found"
  33     }
  34
  35 The status codes that are returned for each endpoint are specified in the endpoint documentation below.
  36
  37 ## 3. Endpoints
  38
  39 ### 3.1 Containers
  40
  41 #### List containers
  42
  43 `GET /containers/json`
  44
  45 List containers
  46
  47 **Example request**:
  48
  49     GET /v1.24/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
  50
  51 **Example response**:
  52
  53     HTTP/1.1 200 OK
  54     Content-Type: application/json
  55
  56     [
  57          {
  58                  "Id": "8dfafdbc3a40",
  59                  "Names":["/boring_feynman"],
  60                  "Image": "ubuntu:latest",
  61                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
  62                  "Command": "echo 1",
  63                  "Created": 1367854155,
  64                  "State": "exited",
  65                  "Status": "Exit 0",
  66                  "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
  67                  "Labels": {
  68                          "com.example.vendor": "Acme",
  69                          "com.example.license": "GPL",
  70                          "com.example.version": "1.0"
  71                  },
  72                  "SizeRw": 12288,
  73                  "SizeRootFs": 0,
  74                  "HostConfig": {
  75                          "NetworkMode": "default"
  76                  },
  77                  "NetworkSettings": {
  78                          "Networks": {
  79                                  "bridge": {
  80                                           "IPAMConfig": null,
  81                                           "Links": null,
  82                                           "Aliases": null,
  83                                           "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
  84                                           "EndpointID": "2cdc4edb1ded3631c81f57966563e5c8525b81121bb3706a9a9a3ae102711f3f",
  85                                           "Gateway": "172.17.0.1",
  86                                           "IPAddress": "172.17.0.2",
  87                                           "IPPrefixLen": 16,
  88                                           "IPv6Gateway": "",
  89                                           "GlobalIPv6Address": "",
  90                                           "GlobalIPv6PrefixLen": 0,
  91                                           "MacAddress": "02:42:ac:11:00:02"
  92                                   }
  93                          }
  94                  },
  95                  "Mounts": [
  96                          {
  97                                   "Name": "fac362...80535",
  98                                   "Source": "/data",
  99                                   "Destination": "/data",
 100                                   "Driver": "local",
 101                                   "Mode": "ro,Z",
 102                                   "RW": false,
 103                                   "Propagation": ""
 104                          }
 105                  ]
 106          },
 107          {
 108                  "Id": "9cd87474be90",
 109                  "Names":["/coolName"],
 110                  "Image": "ubuntu:latest",
 111                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
 112                  "Command": "echo 222222",
 113                  "Created": 1367854155,
 114                  "State": "exited",
 115                  "Status": "Exit 0",
 116                  "Ports": [],
 117                  "Labels": {},
 118                  "SizeRw": 12288,
 119                  "SizeRootFs": 0,
 120                  "HostConfig": {
 121                          "NetworkMode": "default"
 122                  },
 123                  "NetworkSettings": {
 124                          "Networks": {
 125                                  "bridge": {
 126                                           "IPAMConfig": null,
 127                                           "Links": null,
 128                                           "Aliases": null,
 129                                           "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
 130                                           "EndpointID": "88eaed7b37b38c2a3f0c4bc796494fdf51b270c2d22656412a2ca5d559a64d7a",
 131                                           "Gateway": "172.17.0.1",
 132                                           "IPAddress": "172.17.0.8",
 133                                           "IPPrefixLen": 16,
 134                                           "IPv6Gateway": "",
 135                                           "GlobalIPv6Address": "",
 136                                           "GlobalIPv6PrefixLen": 0,
 137                                           "MacAddress": "02:42:ac:11:00:08"
 138                                   }
 139                          }
 140                  },
 141                  "Mounts": []
 142          },
 143          {
 144                  "Id": "3176a2479c92",
 145                  "Names":["/sleepy_dog"],
 146                  "Image": "ubuntu:latest",
 147                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
 148                  "Command": "echo 3333333333333333",
 149                  "Created": 1367854154,
 150                  "State": "exited",
 151                  "Status": "Exit 0",
 152                  "Ports":[],
 153                  "Labels": {},
 154                  "SizeRw":12288,
 155                  "SizeRootFs":0,
 156                  "HostConfig": {
 157                          "NetworkMode": "default"
 158                  },
 159                  "NetworkSettings": {
 160                          "Networks": {
 161                                  "bridge": {
 162                                           "IPAMConfig": null,
 163                                           "Links": null,
 164                                           "Aliases": null,
 165                                           "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
 166                                           "EndpointID": "8b27c041c30326d59cd6e6f510d4f8d1d570a228466f956edf7815508f78e30d",
 167                                           "Gateway": "172.17.0.1",
 168                                           "IPAddress": "172.17.0.6",
 169                                           "IPPrefixLen": 16,
 170                                           "IPv6Gateway": "",
 171                                           "GlobalIPv6Address": "",
 172                                           "GlobalIPv6PrefixLen": 0,
 173                                           "MacAddress": "02:42:ac:11:00:06"
 174                                   }
 175                          }
 176                  },
 177                  "Mounts": []
 178          },
 179          {
 180                  "Id": "4cb07b47f9fb",
 181                  "Names":["/running_cat"],
 182                  "Image": "ubuntu:latest",
 183                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
 184                  "Command": "echo 444444444444444444444444444444444",
 185                  "Created": 1367854152,
 186                  "State": "exited",
 187                  "Status": "Exit 0",
 188                  "Ports": [],
 189                  "Labels": {},
 190                  "SizeRw": 12288,
 191                  "SizeRootFs": 0,
 192                  "HostConfig": {
 193                          "NetworkMode": "default"
 194                  },
 195                  "NetworkSettings": {
 196                          "Networks": {
 197                                  "bridge": {
 198                                           "IPAMConfig": null,
 199                                           "Links": null,
 200                                           "Aliases": null,
 201                                           "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
 202                                           "EndpointID": "d91c7b2f0644403d7ef3095985ea0e2370325cd2332ff3a3225c4247328e66e9",
 203                                           "Gateway": "172.17.0.1",
 204                                           "IPAddress": "172.17.0.5",
 205                                           "IPPrefixLen": 16,
 206                                           "IPv6Gateway": "",
 207                                           "GlobalIPv6Address": "",
 208                                           "GlobalIPv6PrefixLen": 0,
 209                                           "MacAddress": "02:42:ac:11:00:05"
 210                                   }
 211                          }
 212                  },
 213                  "Mounts": []
 214          }
 215     ]
 216
 217 **Query parameters**:
 218
 219 -   **all** – 1/True/true or 0/False/false, Show all containers.
 220         Only running containers are shown by default (i.e., this defaults to false)
 221 -   **limit** – Show `limit` last created
 222         containers, include non-running ones.
 223 -   **since** – Show only containers created since Id, include
 224         non-running ones.
 225 -   **before** – Show only containers created before Id, include
 226         non-running ones.
 227 -   **size** – 1/True/true or 0/False/false, Show the containers
 228         sizes
 229 -   **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:
 230   -   `exited=<int>`; -- containers with exit code of  `<int>` ;
 231   -   `status=`(`created`|`restarting`|`running`|`paused`|`exited`|`dead`)
 232   -   `label=key` or `label="key=value"` of a container label
 233   -   `isolation=`(`default`|`process`|`hyperv`)   (Windows daemon only)
 234   -   `ancestor`=(`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`)
 235   -   `before`=(`<container id>` or `<container name>`)
 236   -   `since`=(`<container id>` or `<container name>`)
 237   -   `volume`=(`<volume name>` or `<mount point destination>`)
 238   -   `network`=(`<network id>` or `<network name>`)
 239
 240 **Status codes**:
 241
 242 -   **200** – no error
 243 -   **400** – bad parameter
 244 -   **500** – server error
 245
 246 #### Create a container
 247
 248 `POST /containers/create`
 249
 250 Create a container
 251
 252 **Example request**:
 253
 254     POST /v1.24/containers/create HTTP/1.1
 255     Content-Type: application/json
 256
 257     {
 258            "Hostname": "",
 259            "Domainname": "",
 260            "User": "",
 261            "AttachStdin": false,
 262            "AttachStdout": true,
 263            "AttachStderr": true,
 264            "Tty": false,
 265            "OpenStdin": false,
 266            "StdinOnce": false,
 267            "Env": [
 268                    "FOO=bar",
 269                    "BAZ=quux"
 270            ],
 271            "Cmd": [
 272                    "date"
 273            ],
 274            "Entrypoint": "",
 275            "Image": "ubuntu",
 276            "Labels": {
 277                    "com.example.vendor": "Acme",
 278                    "com.example.license": "GPL",
 279                    "com.example.version": "1.0"
 280            },
 281            "Volumes": {
 282              "/volumes/data": {}
 283            },
 284            "Healthcheck":{
 285               "Test": ["CMD-SHELL", "curl localhost:3000"],
 286               "Interval": 1000000000,
 287               "Timeout": 10000000000,
 288               "Retries": 10,
 289               "StartPeriod": 60000000000
 290            },
 291            "WorkingDir": "",
 292            "NetworkDisabled": false,
 293            "MacAddress": "12:34:56:78:9a:bc",
 294            "ExposedPorts": {
 295                    "22/tcp": {}
 296            },
 297            "StopSignal": "SIGTERM",
 298            "HostConfig": {
 299              "Binds": ["/tmp:/tmp"],
 300              "Tmpfs": { "/run": "rw,noexec,nosuid,size=65536k" },
 301              "Links": ["redis3:redis"],
 302              "Memory": 0,
 303              "MemorySwap": 0,
 304              "MemoryReservation": 0,
 305              "KernelMemory": 0,
 306              "CpuPercent": 80,
 307              "CpuShares": 512,
 308              "CpuPeriod": 100000,
 309              "CpuQuota": 50000,
 310              "CpusetCpus": "0,1",
 311              "CpusetMems": "0,1",
 312              "IOMaximumBandwidth": 0,
 313              "IOMaximumIOps": 0,
 314              "BlkioWeight": 300,
 315              "BlkioWeightDevice": [{}],
 316              "BlkioDeviceReadBps": [{}],
 317              "BlkioDeviceReadIOps": [{}],
 318              "BlkioDeviceWriteBps": [{}],
 319              "BlkioDeviceWriteIOps": [{}],
 320              "MemorySwappiness": 60,
 321              "OomKillDisable": false,
 322              "OomScoreAdj": 500,
 323              "PidMode": "",
 324              "PidsLimit": -1,
 325              "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
 326              "PublishAllPorts": false,
 327              "Privileged": false,
 328              "ReadonlyRootfs": false,
 329              "Dns": ["8.8.8.8"],
 330              "DnsOptions": [""],
 331              "DnsSearch": [""],
 332              "ExtraHosts": null,
 333              "VolumesFrom": ["parent", "other:ro"],
 334              "CapAdd": ["NET_ADMIN"],
 335              "CapDrop": ["MKNOD"],
 336              "GroupAdd": ["newgroup"],
 337              "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
 338              "NetworkMode": "bridge",
 339              "Devices": [],
 340              "Sysctls": { "net.ipv4.ip_forward": "1" },
 341              "Ulimits": [{}],
 342              "LogConfig": { "Type": "json-file", "Config": {} },
 343              "SecurityOpt": [],
 344              "StorageOpt": {},
 345              "CgroupParent": "",
 346              "VolumeDriver": "",
 347              "ShmSize": 67108864
 348           },
 349           "NetworkingConfig": {
 350               "EndpointsConfig": {
 351                   "isolated_nw" : {
 352                       "IPAMConfig": {
 353                           "IPv4Address":"172.20.30.33",
 354                           "IPv6Address":"2001:db8:abcd::3033",
 355                           "LinkLocalIPs":["169.254.34.68", "fe80::3468"]
 356                       },
 357                       "Links":["container_1", "container_2"],
 358                       "Aliases":["server_x", "server_y"]
 359                   }
 360               }
 361           }
 362       }
 363
 364 **Example response**:
 365
 366       HTTP/1.1 201 Created
 367       Content-Type: application/json
 368
 369       {
 370            "Id":"e90e34656806",
 371            "Warnings":[]
 372       }
 373
 374 **JSON parameters**:
 375
 376 -   **Hostname** - A string value containing the hostname to use for the
 377       container. This must be a valid RFC 1123 hostname.
 378 -   **Domainname** - A string value containing the domain name to use
 379       for the container.
 380 -   **User** - A string value specifying the user inside the container.
 381 -   **AttachStdin** - Boolean value, attaches to `stdin`.
 382 -   **AttachStdout** - Boolean value, attaches to `stdout`.
 383 -   **AttachStderr** - Boolean value, attaches to `stderr`.
 384 -   **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed.
 385 -   **OpenStdin** - Boolean value, opens `stdin`,
 386 -   **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
 387 -   **Env** - A list of environment variables in the form of `["VAR=value", ...]`
 388 -   **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }`
 389 -   **Cmd** - Command to run specified as a string or an array of strings.
 390 -   **Entrypoint** - Set the entry point for the container as a string or an array
 391       of strings.
 392 -   **Image** - A string specifying the image name to use for the container.
 393 -   **Volumes** - An object mapping mount point paths (strings) inside the
 394       container to empty objects.
 395 -   **Healthcheck** - A test to perform to check that the container is healthy.
 396     -     **Test** - The test to perform. Possible values are:
 397               + `{}` inherit healthcheck from image or parent image
 398               + `{"NONE"}` disable healthcheck
 399               + `{"CMD", args...}` exec arguments directly
 400               + `{"CMD-SHELL", command}` run command with system's default shell
 401     -     **Interval** - The time to wait between checks in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit.
 402     -     **Timeout** - The time to wait before considering the check to have hung. It should be 0 or at least 1000000 (1 ms). 0 means inherit.
 403     -     **Retries** - The number of consecutive failures needed to consider a container as unhealthy. 0 means inherit.
 404     -     **StartPeriod** - The time to wait for container initialization before starting health-retries countdown in nanoseconds. It should be 0 or at least 1000000 (1 ms). 0 means inherit.
 405 -   **WorkingDir** - A string specifying the working directory for commands to
 406       run in.
 407 -   **NetworkDisabled** - Boolean value, when true disables networking for the
 408       container
 409 -   **ExposedPorts** - An object mapping ports to an empty object in the form of:
 410       `"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
 411 -   **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default.
 412 -   **HostConfig**
 413     -   **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
 414            + `host-src:container-dest` to bind-mount a host path into the
 415              container. Both `host-src`, and `container-dest` must be an
 416              _absolute_ path.
 417            + `host-src:container-dest:ro` to make the bind-mount read-only
 418              inside the container. Both `host-src`, and `container-dest` must be
 419              an _absolute_ path.
 420            + `volume-name:container-dest` to bind-mount a volume managed by a
 421              volume driver into the container. `container-dest` must be an
 422              _absolute_ path.
 423            + `volume-name:container-dest:ro` to mount the volume read-only
 424              inside the container.  `container-dest` must be an _absolute_ path.
 425     -   **Tmpfs** – A map of container directories which should be replaced by tmpfs mounts, and their corresponding
 426           mount options. A JSON object in the form `{ "/run": "rw,noexec,nosuid,size=65536k" }`.
 427     -   **Links** - A list of links for the container. Each link entry should be
 428           in the form of `container_name:alias`.
 429     -   **Memory** - Memory limit in bytes.
 430     -   **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap.
 431           You must use this with `memory` and make the swap value larger than `memory`.
 432     -   **MemoryReservation** - Memory soft limit in bytes.
 433     -   **KernelMemory** - Kernel memory limit in bytes.
 434     -   **CpuPercent** - An integer value containing the usable percentage of the available CPUs. (Windows daemon only)
 435     -   **CpuShares** - An integer value containing the container's CPU Shares
 436           (ie. the relative weight vs other containers).
 437     -   **CpuPeriod** - The length of a CPU period in microseconds.
 438     -   **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period.
 439     -   **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.
 440     -   **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
 441     -   **IOMaximumBandwidth** - Maximum IO absolute rate in terms of IOps.
 442     -   **IOMaximumIOps** - Maximum IO absolute rate in terms of bytes per second.
 443     -   **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000.
 444     -   **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of:        `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]`
 445     -   **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of:       `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example:
 446         `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"`
 447     -   **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of:       `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example:
 448         `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"`
 449     -   **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example:
 450         `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]`
 451     -   **BlkioDeviceWriteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example:
 452         `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]`
 453     -   **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
 454     -   **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not.
 455     -   **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences.
 456     -   **PidMode** - Set the PID (Process) Namespace mode for the container;
 457           `"container:<name|id>"`: joins another container's PID namespace
 458           `"host"`: use the host's PID namespace inside the container
 459     -   **PidsLimit** - Tune a container's pids limit. Set -1 for unlimited.
 460     -   **PortBindings** - A map of exposed container ports and the host port they
 461           should map to. A JSON object in the form
 462           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
 463           Take note that `port` is specified as a string and not an integer value.
 464     -   **PublishAllPorts** - Allocates a random host port for all of a container's
 465           exposed ports. Specified as a boolean value.
 466     -   **Privileged** - Gives the container full access to the host. Specified as
 467           a boolean value.
 468     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
 469           Specified as a boolean value.
 470     -   **Dns** - A list of DNS servers for the container to use.
 471     -   **DnsOptions** - A list of DNS options
 472     -   **DnsSearch** - A list of DNS search domains
 473     -   **ExtraHosts** - A list of hostnames/IP mappings to add to the
 474         container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`.
 475     -   **VolumesFrom** - A list of volumes to inherit from another container.
 476           Specified in the form `<container name>[:<ro|rw>]`
 477     -   **CapAdd** - A list of kernel capabilities to add to the container.
 478     -   **Capdrop** - A list of kernel capabilities to drop from the container.
 479     -   **GroupAdd** - A list of additional groups that the container process will run as
 480     -   **RestartPolicy** – The behavior to apply when the container exits.  The
 481             value is an object with a `Name` property of either `"always"` to
 482             always restart, `"unless-stopped"` to restart always except when
 483             user has manually stopped the container or `"on-failure"` to restart only when the container
 484             exit code is non-zero.  If `on-failure` is used, `MaximumRetryCount`
 485             controls the number of times to retry before giving up.
 486             The default is not to restart. (optional)
 487             An ever increasing delay (double the previous delay, starting at 100mS)
 488             is added before each restart to prevent flooding the server.
 489     -   **UsernsMode**  - Sets the usernamespace mode for the container when usernamespace remapping option is enabled.
 490            supported values are: `host`.
 491     -   **NetworkMode** - Sets the networking mode for the container. Supported
 492           standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken
 493           as a custom network's name to which this container should connect to.
 494     -   **Devices** - A list of devices to add to the container specified as a JSON object in the
 495       form
 496           `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
 497     -   **Ulimits** - A list of ulimits to set in the container, specified as
 498           `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
 499           `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }`
 500     -   **Sysctls** - A list of kernel parameters (sysctls) to set in the container, specified as
 501           `{ <name>: <Value> }`, for example:
 502           `{ "net.ipv4.ip_forward": "1" }`
 503     -   **SecurityOpt**: A list of string values to customize labels for MLS
 504         systems, such as SELinux.
 505     -   **StorageOpt**: Storage driver options per container. Options can be passed in the form
 506         `{"size":"120G"}`
 507     -   **LogConfig** - Log configuration for the container, specified as a JSON object in the form
 508           `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
 509           Available types: `json-file`, `syslog`, `journald`, `gelf`, `fluentd`, `awslogs`, `splunk`, `etwlogs`, `none`.
 510           `json-file` logging driver.
 511     -   **CgroupParent** - Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.
 512     -   **VolumeDriver** - Driver that this container users to mount volumes.
 513     -   **ShmSize** - Size of `/dev/shm` in bytes. The size must be greater than 0.  If omitted the system uses 64MB.
 514
 515 **Query parameters**:
 516
 517 -   **name** – Assign the specified name to the container. Must
 518     match `/?[a-zA-Z0-9_-]+`.
 519
 520 **Status codes**:
 521
 522 -   **201** – no error
 523 -   **400** – bad parameter
 524 -   **404** – no such container
 525 -   **406** – impossible to attach (container not running)
 526 -   **409** – conflict
 527 -   **500** – server error
 528
 529 #### Inspect a container
 530
 531 `GET /containers/(id or name)/json`
 532
 533 Return low-level information on the container `id`
 534
 535 **Example request**:
 536
 537       GET /v1.24/containers/4fa6e0f0c678/json HTTP/1.1
 538
 539 **Example response**:
 540
 541     HTTP/1.1 200 OK
 542     Content-Type: application/json
 543
 544         {
 545                 "AppArmorProfile": "",
 546                 "Args": [
 547                         "-c",
 548                         "exit 9"
 549                 ],
 550                 "Config": {
 551                         "AttachStderr": true,
 552                         "AttachStdin": false,
 553                         "AttachStdout": true,
 554                         "Cmd": [
 555                                 "/bin/sh",
 556                                 "-c",
 557                                 "exit 9"
 558                         ],
 559                         "Domainname": "",
 560                         "Entrypoint": null,
 561                         "Env": [
 562                                 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
 563                         ],
 564                         "ExposedPorts": null,
 565                         "Hostname": "ba033ac44011",
 566                         "Image": "ubuntu",
 567                         "Labels": {
 568                                 "com.example.vendor": "Acme",
 569                                 "com.example.license": "GPL",
 570                                 "com.example.version": "1.0"
 571                         },
 572                         "MacAddress": "",
 573                         "NetworkDisabled": false,
 574                         "OnBuild": null,
 575                         "OpenStdin": false,
 576                         "StdinOnce": false,
 577                         "Tty": false,
 578                         "User": "",
 579                         "Volumes": {
 580                                 "/volumes/data": {}
 581                         },
 582                         "WorkingDir": "",
 583                         "StopSignal": "SIGTERM"
 584                 },
 585                 "Created": "2015-01-06T15:47:31.485331387Z",
 586                 "Driver": "devicemapper",
 587                 "ExecIDs": null,
 588                 "HostConfig": {
 589                         "Binds": null,
 590                         "IOMaximumBandwidth": 0,
 591                         "IOMaximumIOps": 0,
 592                         "BlkioWeight": 0,
 593                         "BlkioWeightDevice": [{}],
 594                         "BlkioDeviceReadBps": [{}],
 595                         "BlkioDeviceWriteBps": [{}],
 596                         "BlkioDeviceReadIOps": [{}],
 597                         "BlkioDeviceWriteIOps": [{}],
 598                         "CapAdd": null,
 599                         "CapDrop": null,
 600                         "ContainerIDFile": "",
 601                         "CpusetCpus": "",
 602                         "CpusetMems": "",
 603                         "CpuPercent": 80,
 604                         "CpuShares": 0,
 605                         "CpuPeriod": 100000,
 606                         "Devices": [],
 607                         "Dns": null,
 608                         "DnsOptions": null,
 609                         "DnsSearch": null,
 610                         "ExtraHosts": null,
 611                         "IpcMode": "",
 612                         "Links": null,
 613                         "LxcConf": [],
 614                         "Memory": 0,
 615                         "MemorySwap": 0,
 616                         "MemoryReservation": 0,
 617                         "KernelMemory": 0,
 618                         "OomKillDisable": false,
 619                         "OomScoreAdj": 500,
 620                         "NetworkMode": "bridge",
 621                         "PidMode": "",
 622                         "PortBindings": {},
 623                         "Privileged": false,
 624                         "ReadonlyRootfs": false,
 625                         "PublishAllPorts": false,
 626                         "RestartPolicy": {
 627                                 "MaximumRetryCount": 2,
 628                                 "Name": "on-failure"
 629                         },
 630                         "LogConfig": {
 631                                 "Config": null,
 632                                 "Type": "json-file"
 633                         },
 634                         "SecurityOpt": null,
 635                         "Sysctls": {
 636                                 "net.ipv4.ip_forward": "1"
 637                         },
 638                         "StorageOpt": null,
 639                         "VolumesFrom": null,
 640                         "Ulimits": [{}],
 641                         "VolumeDriver": "",
 642                         "ShmSize": 67108864
 643                 },
 644                 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
 645                 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
 646                 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
 647                 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
 648                 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
 649                 "MountLabel": "",
 650                 "Name": "/boring_euclid",
 651                 "NetworkSettings": {
 652                         "Bridge": "",
 653                         "SandboxID": "",
 654                         "HairpinMode": false,
 655                         "LinkLocalIPv6Address": "",
 656                         "LinkLocalIPv6PrefixLen": 0,
 657                         "Ports": null,
 658                         "SandboxKey": "",
 659                         "SecondaryIPAddresses": null,
 660                         "SecondaryIPv6Addresses": null,
 661                         "EndpointID": "",
 662                         "Gateway": "",
 663                         "GlobalIPv6Address": "",
 664                         "GlobalIPv6PrefixLen": 0,
 665                         "IPAddress": "",
 666                         "IPPrefixLen": 0,
 667                         "IPv6Gateway": "",
 668                         "MacAddress": "",
 669                         "Networks": {
 670                                 "bridge": {
 671                                         "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
 672                                         "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
 673                                         "Gateway": "172.17.0.1",
 674                                         "IPAddress": "172.17.0.2",
 675                                         "IPPrefixLen": 16,
 676                                         "IPv6Gateway": "",
 677                                         "GlobalIPv6Address": "",
 678                                         "GlobalIPv6PrefixLen": 0,
 679                                         "MacAddress": "02:42:ac:12:00:02"
 680                                 }
 681                         }
 682                 },
 683                 "Path": "/bin/sh",
 684                 "ProcessLabel": "",
 685                 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
 686                 "RestartCount": 1,
 687                 "State": {
 688                         "Error": "",
 689                         "ExitCode": 9,
 690                         "FinishedAt": "2015-01-06T15:47:32.080254511Z",
 691                         "OOMKilled": false,
 692                         "Dead": false,
 693                         "Paused": false,
 694                         "Pid": 0,
 695                         "Restarting": false,
 696                         "Running": true,
 697                         "StartedAt": "2015-01-06T15:47:32.072697474Z",
 698                         "Status": "running"
 699                 },
 700                 "Mounts": [
 701                         {
 702                                 "Name": "fac362...80535",
 703                                 "Source": "/data",
 704                                 "Destination": "/data",
 705                                 "Driver": "local",
 706                                 "Mode": "ro,Z",
 707                                 "RW": false,
 708                                 "Propagation": ""
 709                         }
 710                 ]
 711         }
 712
 713 **Example request, with size information**:
 714
 715     GET /v1.24/containers/4fa6e0f0c678/json?size=1 HTTP/1.1
 716
 717 **Example response, with size information**:
 718
 719     HTTP/1.1 200 OK
 720     Content-Type: application/json
 721
 722     {
 723     ....
 724     "SizeRw": 0,
 725     "SizeRootFs": 972,
 726     ....
 727     }
 728
 729 **Query parameters**:
 730
 731 -   **size** – 1/True/true or 0/False/false, return container size information. Default is `false`.
 732
 733 **Status codes**:
 734
 735 -   **200** – no error
 736 -   **404** – no such container
 737 -   **500** – server error
 738
 739 #### List processes running inside a container
 740
 741 `GET /containers/(id or name)/top`
 742
 743 List processes running inside the container `id`. On Unix systems this
 744 is done by running the `ps` command. This endpoint is not
 745 supported on Windows.
 746
 747 **Example request**:
 748
 749     GET /v1.24/containers/4fa6e0f0c678/top HTTP/1.1
 750
 751 **Example response**:
 752
 753     HTTP/1.1 200 OK
 754     Content-Type: application/json
 755
 756     {
 757        "Titles" : [
 758          "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD"
 759        ],
 760        "Processes" : [
 761          [
 762            "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash"
 763          ],
 764          [
 765            "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10"
 766          ]
 767        ]
 768     }
 769
 770 **Example request**:
 771
 772     GET /v1.24/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1
 773
 774 **Example response**:
 775
 776     HTTP/1.1 200 OK
 777     Content-Type: application/json
 778
 779     {
 780       "Titles" : [
 781         "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
 782       ]
 783       "Processes" : [
 784         [
 785           "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
 786         ],
 787         [
 788           "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
 789         ]
 790       ],
 791     }
 792
 793 **Query parameters**:
 794
 795 -   **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef`
 796
 797 **Status codes**:
 798
 799 -   **200** – no error
 800 -   **404** – no such container
 801 -   **500** – server error
 802
 803 #### Get container logs
 804
 805 `GET /containers/(id or name)/logs`
 806
 807 Get `stdout` and `stderr` logs from the container ``id``
 808
 809 > **Note**:
 810 > This endpoint works only for containers with the `json-file` or `journald` logging drivers.
 811
 812 **Example request**:
 813
 814      GET /v1.24/containers/4fa6e0f0c678/logs?stderr=1&stdout=1&timestamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1
 815
 816 **Example response**:
 817
 818      HTTP/1.1 101 UPGRADED
 819      Content-Type: application/vnd.docker.raw-stream
 820      Connection: Upgrade
 821      Upgrade: tcp
 822
 823      {% raw %}
 824      {{ STREAM }}
 825      {% endraw %}
 826
 827 **Query parameters**:
 828
 829 -   **details** - 1/True/true or 0/False/flase, Show extra details provided to logs. Default `false`.
 830 -   **follow** – 1/True/true or 0/False/false, return stream. Default `false`.
 831 -   **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`.
 832 -   **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`.
 833 -   **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp
 834     will only output log-entries since that timestamp. Default: 0 (unfiltered)
 835 -   **timestamps** – 1/True/true or 0/False/false, print timestamps for
 836         every log line. Default `false`.
 837 -   **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all.
 838
 839 **Status codes**:
 840
 841 -   **101** – no error, hints proxy about hijacking
 842 -   **200** – no error, no upgrade header found
 843 -   **404** – no such container
 844 -   **500** – server error
 845
 846 #### Inspect changes on a container's filesystem
 847
 848 `GET /containers/(id or name)/changes`
 849
 850 Inspect changes on container `id`'s filesystem
 851
 852 **Example request**:
 853
 854     GET /v1.24/containers/4fa6e0f0c678/changes HTTP/1.1
 855
 856 **Example response**:
 857
 858     HTTP/1.1 200 OK
 859     Content-Type: application/json
 860
 861     [
 862          {
 863                  "Path": "/dev",
 864                  "Kind": 0
 865          },
 866          {
 867                  "Path": "/dev/kmsg",
 868                  "Kind": 1
 869          },
 870          {
 871                  "Path": "/test",
 872                  "Kind": 1
 873          }
 874     ]
 875
 876 Values for `Kind`:
 877
 878 - `0`: Modify
 879 - `1`: Add
 880 - `2`: Delete
 881
 882 **Status codes**:
 883
 884 -   **200** – no error
 885 -   **404** – no such container
 886 -   **500** – server error
 887
 888 #### Export a container
 889
 890 `GET /containers/(id or name)/export`
 891
 892 Export the contents of container `id`
 893
 894 **Example request**:
 895
 896     GET /v1.24/containers/4fa6e0f0c678/export HTTP/1.1
 897
 898 **Example response**:
 899
 900     HTTP/1.1 200 OK
 901     Content-Type: application/octet-stream
 902
 903     {% raw %}
 904     {{ TAR STREAM }}
 905     {% endraw %}
 906
 907 **Status codes**:
 908
 909 -   **200** – no error
 910 -   **404** – no such container
 911 -   **500** – server error
 912
 913 #### Get container stats based on resource usage
 914
 915 `GET /containers/(id or name)/stats`
 916
 917 This endpoint returns a live stream of a container's resource usage statistics.
 918
 919 **Example request**:
 920
 921     GET /v1.24/containers/redis1/stats HTTP/1.1
 922
 923 **Example response**:
 924
 925       HTTP/1.1 200 OK
 926       Content-Type: application/json
 927
 928       {
 929          "read" : "2015-01-08T22:57:31.547920715Z",
 930          "pids_stats": {
 931             "current": 3
 932          },
 933          "networks": {
 934                  "eth0": {
 935                      "rx_bytes": 5338,
 936                      "rx_dropped": 0,
 937                      "rx_errors": 0,
 938                      "rx_packets": 36,
 939                      "tx_bytes": 648,
 940                      "tx_dropped": 0,
 941                      "tx_errors": 0,
 942                      "tx_packets": 8
 943                  },
 944                  "eth5": {
 945                      "rx_bytes": 4641,
 946                      "rx_dropped": 0,
 947                      "rx_errors": 0,
 948                      "rx_packets": 26,
 949                      "tx_bytes": 690,
 950                      "tx_dropped": 0,
 951                      "tx_errors": 0,
 952                      "tx_packets": 9
 953                  }
 954          },
 955          "memory_stats" : {
 956             "stats" : {
 957                "total_pgmajfault" : 0,
 958                "cache" : 0,
 959                "mapped_file" : 0,
 960                "total_inactive_file" : 0,
 961                "pgpgout" : 414,
 962                "rss" : 6537216,
 963                "total_mapped_file" : 0,
 964                "writeback" : 0,
 965                "unevictable" : 0,
 966                "pgpgin" : 477,
 967                "total_unevictable" : 0,
 968                "pgmajfault" : 0,
 969                "total_rss" : 6537216,
 970                "total_rss_huge" : 6291456,
 971                "total_writeback" : 0,
 972                "total_inactive_anon" : 0,
 973                "rss_huge" : 6291456,
 974                "hierarchical_memory_limit" : 67108864,
 975                "total_pgfault" : 964,
 976                "total_active_file" : 0,
 977                "active_anon" : 6537216,
 978                "total_active_anon" : 6537216,
 979                "total_pgpgout" : 414,
 980                "total_cache" : 0,
 981                "inactive_anon" : 0,
 982                "active_file" : 0,
 983                "pgfault" : 964,
 984                "inactive_file" : 0,
 985                "total_pgpgin" : 477
 986             },
 987             "max_usage" : 6651904,
 988             "usage" : 6537216,
 989             "failcnt" : 0,
 990             "limit" : 67108864
 991          },
 992          "blkio_stats" : {},
 993          "cpu_stats" : {
 994             "cpu_usage" : {
 995                "percpu_usage" : [
 996                   8646879,
 997                   24472255,
 998                   36438778,
 999                   30657443
1000                ],
1001                "usage_in_usermode" : 50000000,
1002                "total_usage" : 100215355,
1003                "usage_in_kernelmode" : 30000000
1004             },
1005             "system_cpu_usage" : 739306590000000,
1006             "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
1007          },
1008          "precpu_stats" : {
1009             "cpu_usage" : {
1010                "percpu_usage" : [
1011                   8646879,
1012                   24350896,
1013                   36438778,
1014                   30657443
1015                ],
1016                "usage_in_usermode" : 50000000,
1017                "total_usage" : 100093996,
1018                "usage_in_kernelmode" : 30000000
1019             },
1020             "system_cpu_usage" : 9492140000000,
1021             "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
1022          }
1023       }
1024
1025 The `precpu_stats` is the cpu statistic of last read, which is used for calculating the cpu usage percent. It is not the exact copy of the `cpu_stats` field.
1026
1027 **Query parameters**:
1028
1029 -   **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`.
1030
1031 **Status codes**:
1032
1033 -   **200** – no error
1034 -   **404** – no such container
1035 -   **500** – server error
1036
1037 #### Resize a container TTY
1038
1039 `POST /containers/(id or name)/resize`
1040
1041 Resize the TTY for container with  `id`. The unit is number of characters. You must restart the container for the resize to take effect.
1042
1043 **Example request**:
1044
1045       POST /v1.24/containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1
1046
1047 **Example response**:
1048
1049       HTTP/1.1 200 OK
1050       Content-Length: 0
1051       Content-Type: text/plain; charset=utf-8
1052
1053 **Query parameters**:
1054
1055 -   **h** – height of `tty` session
1056 -   **w** – width
1057
1058 **Status codes**:
1059
1060 -   **200** – no error
1061 -   **404** – No such container
1062 -   **500** – Cannot resize container
1063
1064 #### Start a container
1065
1066 `POST /containers/(id or name)/start`
1067
1068 Start the container `id`
1069
1070 **Example request**:
1071
1072     POST /v1.24/containers/e90e34656806/start HTTP/1.1
1073
1074 **Example response**:
1075
1076     HTTP/1.1 204 No Content
1077
1078 **Query parameters**:
1079
1080 -   **detachKeys** – Override the key sequence for detaching a
1081         container. Format is a single character `[a-Z]` or `ctrl-<value>`
1082         where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
1083
1084 **Status codes**:
1085
1086 -   **204** – no error
1087 -   **304** – container already started
1088 -   **404** – no such container
1089 -   **500** – server error
1090
1091 #### Stop a container
1092
1093 `POST /containers/(id or name)/stop`
1094
1095 Stop the container `id`
1096
1097 **Example request**:
1098
1099     POST /v1.24/containers/e90e34656806/stop?t=5 HTTP/1.1
1100
1101 **Example response**:
1102
1103     HTTP/1.1 204 No Content
1104
1105 **Query parameters**:
1106
1107 -   **t** – number of seconds to wait before killing the container
1108
1109 **Status codes**:
1110
1111 -   **204** – no error
1112 -   **304** – container already stopped
1113 -   **404** – no such container
1114 -   **500** – server error
1115
1116 #### Restart a container
1117
1118 `POST /containers/(id or name)/restart`
1119
1120 Restart the container `id`
1121
1122 **Example request**:
1123
1124     POST /v1.24/containers/e90e34656806/restart?t=5 HTTP/1.1
1125
1126 **Example response**:
1127
1128     HTTP/1.1 204 No Content
1129
1130 **Query parameters**:
1131
1132 -   **t** – number of seconds to wait before killing the container
1133
1134 **Status codes**:
1135
1136 -   **204** – no error
1137 -   **404** – no such container
1138 -   **500** – server error
1139
1140 #### Kill a container
1141
1142 `POST /containers/(id or name)/kill`
1143
1144 Kill the container `id`
1145
1146 **Example request**:
1147
1148     POST /v1.24/containers/e90e34656806/kill HTTP/1.1
1149
1150 **Example response**:
1151
1152     HTTP/1.1 204 No Content
1153
1154 **Query parameters**:
1155
1156 -   **signal** - Signal to send to the container: integer or string like `SIGINT`.
1157         When not set, `SIGKILL` is assumed and the call waits for the container to exit.
1158
1159 **Status codes**:
1160
1161 -   **204** – no error
1162 -   **404** – no such container
1163 -   **500** – server error
1164
1165 #### Update a container
1166
1167 `POST /containers/(id or name)/update`
1168
1169 Update configuration of one or more containers.
1170
1171 **Example request**:
1172
1173        POST /v1.24/containers/e90e34656806/update HTTP/1.1
1174        Content-Type: application/json
1175
1176        {
1177          "BlkioWeight": 300,
1178          "CpuShares": 512,
1179          "CpuPeriod": 100000,
1180          "CpuQuota": 50000,
1181          "CpusetCpus": "0,1",
1182          "CpusetMems": "0",
1183          "Memory": 314572800,
1184          "MemorySwap": 514288000,
1185          "MemoryReservation": 209715200,
1186          "KernelMemory": 52428800,
1187          "RestartPolicy": {
1188            "MaximumRetryCount": 4,
1189            "Name": "on-failure"
1190          }
1191        }
1192
1193 **Example response**:
1194
1195        HTTP/1.1 200 OK
1196        Content-Type: application/json
1197
1198        {
1199            "Warnings": []
1200        }
1201
1202 **Status codes**:
1203
1204 -   **200** – no error
1205 -   **400** – bad parameter
1206 -   **404** – no such container
1207 -   **500** – server error
1208
1209 #### Rename a container
1210
1211 `POST /containers/(id or name)/rename`
1212
1213 Rename the container `id` to a `new_name`
1214
1215 **Example request**:
1216
1217     POST /v1.24/containers/e90e34656806/rename?name=new_name HTTP/1.1
1218
1219 **Example response**:
1220
1221     HTTP/1.1 204 No Content
1222
1223 **Query parameters**:
1224
1225 -   **name** – new name for the container
1226
1227 **Status codes**:
1228
1229 -   **204** – no error
1230 -   **404** – no such container
1231 -   **409** - conflict name already assigned
1232 -   **500** – server error
1233
1234 #### Pause a container
1235
1236 `POST /containers/(id or name)/pause`
1237
1238 Pause the container `id`
1239
1240 **Example request**:
1241
1242     POST /v1.24/containers/e90e34656806/pause HTTP/1.1
1243
1244 **Example response**:
1245
1246     HTTP/1.1 204 No Content
1247
1248 **Status codes**:
1249
1250 -   **204** – no error
1251 -   **404** – no such container
1252 -   **500** – server error
1253
1254 #### Unpause a container
1255
1256 `POST /containers/(id or name)/unpause`
1257
1258 Unpause the container `id`
1259
1260 **Example request**:
1261
1262     POST /v1.24/containers/e90e34656806/unpause HTTP/1.1
1263
1264 **Example response**:
1265
1266     HTTP/1.1 204 No Content
1267
1268 **Status codes**:
1269
1270 -   **204** – no error
1271 -   **404** – no such container
1272 -   **500** – server error
1273
1274 #### Attach to a container
1275
1276 `POST /containers/(id or name)/attach`
1277
1278 Attach to the container `id`
1279
1280 **Example request**:
1281
1282     POST /v1.24/containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
1283
1284 **Example response**:
1285
1286     HTTP/1.1 101 UPGRADED
1287     Content-Type: application/vnd.docker.raw-stream
1288     Connection: Upgrade
1289     Upgrade: tcp
1290
1291     {% raw %}
1292     {{ STREAM }}
1293     {% endraw %}
1294
1295 **Query parameters**:
1296
1297 -   **detachKeys** – Override the key sequence for detaching a
1298         container. Format is a single character `[a-Z]` or `ctrl-<value>`
1299         where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
1300 -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
1301 -   **stream** – 1/True/true or 0/False/false, return stream.
1302         Default `false`.
1303 -   **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
1304         to `stdin`. Default `false`.
1305 -   **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
1306         `stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
1307 -   **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
1308         `stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
1309
1310 **Status codes**:
1311
1312 -   **101** – no error, hints proxy about hijacking
1313 -   **200** – no error, no upgrade header found
1314 -   **400** – bad parameter
1315 -   **404** – no such container
1316 -   **409** - container is paused
1317 -   **500** – server error
1318
1319 **Stream details**:
1320
1321 When using the TTY setting is enabled in
1322 [`POST /containers/create`
1323 ](#create-a-container),
1324 the stream is the raw data from the process PTY and client's `stdin`.
1325 When the TTY is disabled, then the stream is multiplexed to separate
1326 `stdout` and `stderr`.
1327
1328 The format is a **Header** and a **Payload** (frame).
1329
1330 **HEADER**
1331
1332 The header contains the information which the stream writes (`stdout` or
1333 `stderr`). It also contains the size of the associated frame encoded in the
1334 last four bytes (`uint32`).
1335
1336 It is encoded on the first eight bytes like this:
1337
1338     header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
1339
1340 `STREAM_TYPE` can be:
1341
1342 -   0: `stdin` (is written on `stdout`)
1343 -   1: `stdout`
1344 -   2: `stderr`
1345
1346 `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of
1347 the `uint32` size encoded as big endian.
1348
1349 **PAYLOAD**
1350
1351 The payload is the raw stream.
1352
1353 **IMPLEMENTATION**
1354
1355 The simplest way to implement the Attach protocol is the following:
1356
1357     1.  Read eight bytes.
1358     2.  Choose `stdout` or `stderr` depending on the first byte.
1359     3.  Extract the frame size from the last four bytes.
1360     4.  Read the extracted size and output it on the correct output.
1361     5.  Goto 1.
1362
1363 #### Attach to a container (websocket)
1364
1365 `GET /containers/(id or name)/attach/ws`
1366
1367 Attach to the container `id` via websocket
1368
1369 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455)
1370
1371 **Example request**
1372
1373     GET /v1.24/containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1
1374
1375 **Example response**
1376
1377     {% raw %}
1378     {{ STREAM }}
1379     {% endraw %}
1380
1381 **Query parameters**:
1382
1383 -   **detachKeys** – Override the key sequence for detaching a
1384         container. Format is a single character `[a-Z]` or `ctrl-<value>`
1385         where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
1386 -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
1387 -   **stream** – 1/True/true or 0/False/false, return stream.
1388         Default `false`.
1389 -   **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
1390         to `stdin`. Default `false`.
1391 -   **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
1392         `stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
1393 -   **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
1394         `stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
1395
1396 **Status codes**:
1397
1398 -   **200** – no error
1399 -   **400** – bad parameter
1400 -   **404** – no such container
1401 -   **500** – server error
1402
1403 #### Wait a container
1404
1405 `POST /containers/(id or name)/wait`
1406
1407 Block until container `id` stops, then returns the exit code
1408
1409 **Example request**:
1410
1411     POST /v1.24/containers/16253994b7c4/wait HTTP/1.1
1412
1413 **Example response**:
1414
1415     HTTP/1.1 200 OK
1416     Content-Type: application/json
1417
1418     {"StatusCode": 0}
1419
1420 **Status codes**:
1421
1422 -   **200** – no error
1423 -   **404** – no such container
1424 -   **500** – server error
1425
1426 #### Remove a container
1427
1428 `DELETE /containers/(id or name)`
1429
1430 Remove the container `id` from the filesystem
1431
1432 **Example request**:
1433
1434     DELETE /v1.24/containers/16253994b7c4?v=1 HTTP/1.1
1435
1436 **Example response**:
1437
1438     HTTP/1.1 204 No Content
1439
1440 **Query parameters**:
1441
1442 -   **v** – 1/True/true or 0/False/false, Remove the volumes
1443         associated to the container. Default `false`.
1444 -   **force** - 1/True/true or 0/False/false, Kill then remove the container.
1445         Default `false`.
1446 -   **link** - 1/True/true or 0/False/false, Remove the specified
1447         link associated to the container. Default `false`.
1448
1449 **Status codes**:
1450
1451 -   **204** – no error
1452 -   **400** – bad parameter
1453 -   **404** – no such container
1454 -   **409** – conflict
1455 -   **500** – server error
1456
1457 #### Retrieving information about files and folders in a container
1458
1459 `HEAD /containers/(id or name)/archive`
1460
1461 See the description of the `X-Docker-Container-Path-Stat` header in the
1462 following section.
1463
1464 #### Get an archive of a filesystem resource in a container
1465
1466 `GET /containers/(id or name)/archive`
1467
1468 Get a tar archive of a resource in the filesystem of container `id`.
1469
1470 **Query parameters**:
1471
1472 - **path** - resource in the container's filesystem to archive. Required.
1473
1474     If not an absolute path, it is relative to the container's root directory.
1475     The resource specified by **path** must exist. To assert that the resource
1476     is expected to be a directory, **path** should end in `/` or  `/.`
1477     (assuming a path separator of `/`). If **path** ends in `/.` then this
1478     indicates that only the contents of the **path** directory should be
1479     copied. A symlink is always resolved to its target.
1480
1481     > **Note**: It is not possible to copy certain system files such as resources
1482     > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
1483     > container.
1484
1485 **Example request**:
1486
1487     GET /v1.24/containers/8cce319429b2/archive?path=/root HTTP/1.1
1488
1489 **Example response**:
1490
1491     HTTP/1.1 200 OK
1492     Content-Type: application/x-tar
1493     X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0=
1494
1495     {% raw %}
1496     {{ TAR STREAM }}
1497     {% endraw %}
1498
1499 On success, a response header `X-Docker-Container-Path-Stat` will be set to a
1500 base64-encoded JSON object containing some filesystem header information about
1501 the archived resource. The above example value would decode to the following
1502 JSON object (whitespace added for readability):
1503
1504 ```json
1505 {
1506     "name": "root",
1507     "size": 4096,
1508     "mode": 2147484096,
1509     "mtime": "2014-02-27T20:51:23Z",
1510     "linkTarget": ""
1511 }
1512 ```
1513
1514 A `HEAD` request can also be made to this endpoint if only this information is
1515 desired.
1516
1517 **Status codes**:
1518
1519 - **200** - success, returns archive of copied resource
1520 - **400** - client error, bad parameter, details in JSON response body, one of:
1521     - must specify path parameter (**path** cannot be empty)
1522     - not a directory (**path** was asserted to be a directory but exists as a
1523       file)
1524 - **404** - client error, resource not found, one of:
1525     – no such container (container `id` does not exist)
1526     - no such file or directory (**path** does not exist)
1527 - **500** - server error
1528
1529 #### Extract an archive of files or folders to a directory in a container
1530
1531 `PUT /containers/(id or name)/archive`
1532
1533 Upload a tar archive to be extracted to a path in the filesystem of container
1534 `id`.
1535
1536 **Query parameters**:
1537
1538 - **path** - path to a directory in the container
1539     to extract the archive's contents into. Required.
1540
1541     If not an absolute path, it is relative to the container's root directory.
1542     The **path** resource must exist.
1543 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error
1544     if unpacking the given content would cause an existing directory to be
1545     replaced with a non-directory and vice versa.
1546
1547 **Example request**:
1548
1549     PUT /v1.24/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1
1550     Content-Type: application/x-tar
1551
1552     {% raw %}
1553     {{ TAR STREAM }}
1554     {% endraw %}
1555
1556 **Example response**:
1557
1558     HTTP/1.1 200 OK
1559
1560 **Status codes**:
1561
1562 - **200** – the content was extracted successfully
1563 - **400** - client error, bad parameter, details in JSON response body, one of:
1564     - must specify path parameter (**path** cannot be empty)
1565     - not a directory (**path** should be a directory but exists as a file)
1566     - unable to overwrite existing directory with non-directory
1567       (if **noOverwriteDirNonDir**)
1568     - unable to overwrite existing non-directory with directory
1569       (if **noOverwriteDirNonDir**)
1570 - **403** - client error, permission denied, the volume
1571     or container rootfs is marked as read-only.
1572 - **404** - client error, resource not found, one of:
1573     – no such container (container `id` does not exist)
1574     - no such file or directory (**path** resource does not exist)
1575 - **500** – server error
1576
1577 ### 3.2 Images
1578
1579 #### List Images
1580
1581 `GET /images/json`
1582
1583 **Example request**:
1584
1585     GET /v1.24/images/json?all=0 HTTP/1.1
1586
1587 **Example response**:
1588
1589     HTTP/1.1 200 OK
1590     Content-Type: application/json
1591
1592     [
1593       {
1594          "RepoTags": [
1595            "ubuntu:12.04",
1596            "ubuntu:precise",
1597            "ubuntu:latest"
1598          ],
1599          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
1600          "Created": 1365714795,
1601          "Size": 131506275,
1602          "VirtualSize": 131506275,
1603          "Labels": {}
1604       },
1605       {
1606          "RepoTags": [
1607            "ubuntu:12.10",
1608            "ubuntu:quantal"
1609          ],
1610          "ParentId": "27cf784147099545",
1611          "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
1612          "Created": 1364102658,
1613          "Size": 24653,
1614          "VirtualSize": 180116135,
1615          "Labels": {
1616             "com.example.version": "v1"
1617          }
1618       }
1619     ]
1620
1621 **Example request, with digest information**:
1622
1623     GET /v1.24/images/json?digests=1 HTTP/1.1
1624
1625 **Example response, with digest information**:
1626
1627     HTTP/1.1 200 OK
1628     Content-Type: application/json
1629
1630     [
1631       {
1632         "Created": 1420064636,
1633         "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125",
1634         "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2",
1635         "RepoDigests": [
1636           "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
1637         ],
1638         "RepoTags": [
1639           "localhost:5000/test/busybox:latest",
1640           "playdate:latest"
1641         ],
1642         "Size": 0,
1643         "VirtualSize": 2429728,
1644         "Labels": {}
1645       }
1646     ]
1647
1648 The response shows a single image `Id` associated with two repositories
1649 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use
1650 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or
1651 `playdate:latest` to reference the image.
1652
1653 You can also use `RepoDigests` values to reference an image. In this response,
1654 the array has only one reference and that is to the
1655 `localhost:5000/test/busybox` repository; the `playdate` repository has no
1656 digest. You can reference this digest using the value:
1657 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...`
1658
1659 See the `docker run` and `docker build` commands for examples of digest and tag
1660 references on the command line.
1661
1662 **Query parameters**:
1663
1664 -   **all** – 1/True/true or 0/False/false, default false
1665 -   **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
1666   -   `dangling=true`
1667   -   `label=key` or `label="key=value"` of an image label
1668   -   `before`=(`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`)
1669   -   `since`=(`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`)
1670 -   **filter** - only return images with the specified name
1671
1672 #### Build image from a Dockerfile
1673
1674 `POST /build`
1675
1676 Build an image from a Dockerfile
1677
1678 **Example request**:
1679
1680     POST /v1.24/build HTTP/1.1
1681     Content-Type: application/x-tar
1682
1683     {% raw %}
1684     {{ TAR STREAM }}
1685     {% endraw %}
1686
1687 **Example response**:
1688
1689     HTTP/1.1 200 OK
1690     Content-Type: application/json
1691
1692     {"stream": "Step 1/5..."}
1693     {"stream": "..."}
1694     {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}
1695
1696 The input stream must be a `tar` archive compressed with one of the
1697 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`.
1698
1699 The archive must include a build instructions file, typically called
1700 `Dockerfile` at the archive's root. The `dockerfile` parameter may be
1701 used to specify a different build instructions file. To do this, its value must be
1702 the path to the alternate build instructions file to use.
1703
1704 The archive may include any number of other files,
1705 which are accessible in the build context (See the [*ADD build
1706 command*](../reference/builder.md#add)).
1707
1708 The Docker daemon performs a preliminary validation of the `Dockerfile` before
1709 starting the build, and returns an error if the syntax is incorrect. After that,
1710 each instruction is run one-by-one until the ID of the new image is output.
1711
1712 The build is canceled if the client drops the connection by quitting
1713 or being killed.
1714
1715 **Query parameters**:
1716
1717 -   **dockerfile** - Path within the build context to the `Dockerfile`. This is
1718         ignored if `remote` is specified and points to an external `Dockerfile`.
1719 -   **t** – A name and optional tag to apply to the image in the `name:tag` format.
1720         If you omit the `tag` the default `latest` value is assumed.
1721         You can provide one or more `t` parameters.
1722 -   **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
1723         URI points to a single text file, the file's contents are placed into
1724         a file called `Dockerfile` and the image is built from that file. If
1725         the URI points to a tarball, the file is downloaded by the daemon and
1726         the contents therein used as the context for the build. If the URI
1727         points to a tarball and the `dockerfile` parameter is also specified,
1728         there must be a file with the corresponding path inside the tarball.
1729 -   **q** – Suppress verbose build output.
1730 -   **nocache** – Do not use the cache when building the image.
1731 -   **pull** - Attempt to pull the image even if an older image exists locally.
1732 -   **rm** - Remove intermediate containers after a successful build (default behavior).
1733 -   **forcerm** - Always remove intermediate containers (includes `rm`).
1734 -   **memory** - Set memory limit for build.
1735 -   **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap.
1736 -   **cpushares** - CPU shares (relative weight).
1737 -   **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).
1738 -   **cpuperiod** - The length of a CPU period in microseconds.
1739 -   **cpuquota** - Microseconds of CPU time that the container can get in a CPU period.
1740 -   **buildargs** – JSON map of string pairs for build-time variables. Users pass
1741         these values at build-time. Docker uses the `buildargs` as the environment
1742         context for command(s) run via the Dockerfile's `RUN` instruction or for
1743         variable expansion in other Dockerfile instructions. This is not meant for
1744         passing secret values. [Read more about the buildargs instruction](../reference/builder.md#arg)
1745 -   **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0.  If omitted the system uses 64MB.
1746 -   **labels** – JSON map of string pairs for labels to set on the image.
1747
1748 **Request Headers**:
1749
1750 -   **Content-type** – Set to `"application/x-tar"`.
1751 -   **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
1752         object with the following structure:
1753
1754             {
1755                 "docker.example.com": {
1756                     "username": "janedoe",
1757                     "password": "hunter2"
1758                 },
1759                 "https://index.docker.io/v1/": {
1760                     "username": "mobydock",
1761                     "password": "conta1n3rize14"
1762                 }
1763             }
1764
1765     This object maps the hostname of a registry to an object containing the
1766     "username" and "password" for that registry. Multiple registries may
1767     be specified as the build may be based on an image requiring
1768     authentication to pull from any arbitrary registry. Only the registry
1769     domain name (and port if not the default "443") are required. However
1770     (for legacy reasons) the "official" Docker, Inc. hosted registry must
1771     be specified with both a "https://" prefix and a "/v1/" suffix even
1772     though Docker will prefer to use the v2 registry API.
1773
1774 **Status codes**:
1775
1776 -   **200** – no error
1777 -   **500** – server error
1778
1779 #### Create an image
1780
1781 `POST /images/create`
1782
1783 Create an image either by pulling it from the registry or by importing it
1784
1785 **Example request**:
1786
1787     POST /v1.24/images/create?fromImage=busybox&tag=latest HTTP/1.1
1788
1789 **Example response**:
1790
1791     HTTP/1.1 200 OK
1792     Content-Type: application/json
1793
1794     {"status": "Pulling..."}
1795     {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
1796     {"error": "Invalid..."}
1797     ...
1798
1799 When using this endpoint to pull an image from the registry, the
1800 `X-Registry-Auth` header can be used to include
1801 a base64-encoded AuthConfig object.
1802
1803 **Query parameters**:
1804
1805 -   **fromImage** – Name of the image to pull. The name may include a tag or
1806         digest. This parameter may only be used when pulling an image.
1807         The pull is cancelled if the HTTP connection is closed.
1808 -   **fromSrc** – Source to import.  The value may be a URL from which the image
1809         can be retrieved or `-` to read the image from the request body.
1810         This parameter may only be used when importing an image.
1811 -   **repo** – Repository name given to an image when it is imported.
1812         The repo may include a tag. This parameter may only be used when importing
1813         an image.
1814 -   **tag** – Tag or digest. If empty when pulling an image, this causes all tags
1815         for the given image to be pulled.
1816
1817 **Request Headers**:
1818
1819 -   **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
1820     - Credential based login:
1821
1822         ```
1823     {
1824             "username": "jdoe",
1825             "password": "secret",
1826             "email": "jdoe@acme.com"
1827     }
1828         ```
1829
1830     - Token based login:
1831
1832         ```
1833     {
1834             "identitytoken": "9cbaf023786cd7..."
1835     }
1836         ```
1837
1838 **Status codes**:
1839
1840 -   **200** – no error
1841 -   **404** - repository does not exist or no read access
1842 -   **500** – server error
1843
1844
1845
1846 #### Inspect an image
1847
1848 `GET /images/(name)/json`
1849
1850 Return low-level information on the image `name`
1851
1852 **Example request**:
1853
1854     GET /v1.24/images/example/json HTTP/1.1
1855
1856 **Example response**:
1857
1858     HTTP/1.1 200 OK
1859     Content-Type: application/json
1860
1861     {
1862        "Id" : "sha256:85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c",
1863        "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a",
1864        "Comment" : "",
1865        "Os" : "linux",
1866        "Architecture" : "amd64",
1867        "Parent" : "sha256:91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
1868        "ContainerConfig" : {
1869           "Tty" : false,
1870           "Hostname" : "e611e15f9c9d",
1871           "Volumes" : null,
1872           "Domainname" : "",
1873           "AttachStdout" : false,
1874           "PublishService" : "",
1875           "AttachStdin" : false,
1876           "OpenStdin" : false,
1877           "StdinOnce" : false,
1878           "NetworkDisabled" : false,
1879           "OnBuild" : [],
1880           "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
1881           "User" : "",
1882           "WorkingDir" : "",
1883           "Entrypoint" : null,
1884           "MacAddress" : "",
1885           "AttachStderr" : false,
1886           "Labels" : {
1887              "com.example.license" : "GPL",
1888              "com.example.version" : "1.0",
1889              "com.example.vendor" : "Acme"
1890           },
1891           "Env" : [
1892              "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
1893           ],
1894           "ExposedPorts" : null,
1895           "Cmd" : [
1896              "/bin/sh",
1897              "-c",
1898              "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0"
1899           ]
1900        },
1901        "DockerVersion" : "1.9.0-dev",
1902        "VirtualSize" : 188359297,
1903        "Size" : 0,
1904        "Author" : "",
1905        "Created" : "2015-09-10T08:30:53.26995814Z",
1906        "GraphDriver" : {
1907           "Name" : "aufs",
1908           "Data" : null
1909        },
1910        "RepoDigests" : [
1911           "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
1912        ],
1913        "RepoTags" : [
1914           "example:1.0",
1915           "example:latest",
1916           "example:stable"
1917        ],
1918        "Config" : {
1919           "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
1920           "NetworkDisabled" : false,
1921           "OnBuild" : [],
1922           "StdinOnce" : false,
1923           "PublishService" : "",
1924           "AttachStdin" : false,
1925           "OpenStdin" : false,
1926           "Domainname" : "",
1927           "AttachStdout" : false,
1928           "Tty" : false,
1929           "Hostname" : "e611e15f9c9d",
1930           "Volumes" : null,
1931           "Cmd" : [
1932              "/bin/bash"
1933           ],
1934           "ExposedPorts" : null,
1935           "Env" : [
1936              "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
1937           ],
1938           "Labels" : {
1939              "com.example.vendor" : "Acme",
1940              "com.example.version" : "1.0",
1941              "com.example.license" : "GPL"
1942           },
1943           "Entrypoint" : null,
1944           "MacAddress" : "",
1945           "AttachStderr" : false,
1946           "WorkingDir" : "",
1947           "User" : ""
1948        },
1949        "RootFS": {
1950            "Type": "layers",
1951            "Layers": [
1952                "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
1953                "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
1954            ]
1955        }
1956     }
1957
1958 **Status codes**:
1959
1960 -   **200** – no error
1961 -   **404** – no such image
1962 -   **500** – server error
1963
1964 #### Get the history of an image
1965
1966 `GET /images/(name)/history`
1967
1968 Return the history of the image `name`
1969
1970 **Example request**:
1971
1972     GET /v1.24/images/ubuntu/history HTTP/1.1
1973
1974 **Example response**:
1975
1976     HTTP/1.1 200 OK
1977     Content-Type: application/json
1978
1979     [
1980         {
1981             "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
1982             "Created": 1398108230,
1983             "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
1984             "Tags": [
1985                 "ubuntu:lucid",
1986                 "ubuntu:10.04"
1987             ],
1988             "Size": 182964289,
1989             "Comment": ""
1990         },
1991         {
1992             "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
1993             "Created": 1398108222,
1994             "CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
1995             "Tags": null,
1996             "Size": 0,
1997             "Comment": ""
1998         },
1999         {
2000             "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
2001             "Created": 1371157430,
2002             "CreatedBy": "",
2003             "Tags": [
2004                 "scratch12:latest",
2005                 "scratch:latest"
2006             ],
2007             "Size": 0,
2008             "Comment": "Imported from -"
2009         }
2010     ]
2011
2012 **Status codes**:
2013
2014 -   **200** – no error
2015 -   **404** – no such image
2016 -   **500** – server error
2017
2018 #### Push an image on the registry
2019
2020 `POST /images/(name)/push`
2021
2022 Push the image `name` on the registry
2023
2024 **Example request**:
2025
2026     POST /v1.24/images/test/push HTTP/1.1
2027
2028 **Example response**:
2029
2030     HTTP/1.1 200 OK
2031     Content-Type: application/json
2032
2033     {"status": "Pushing..."}
2034     {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
2035     {"error": "Invalid..."}
2036     ...
2037
2038 If you wish to push an image on to a private registry, that image must already have a tag
2039 into a repository which references that registry `hostname` and `port`.  This repository name should
2040 then be used in the URL. This duplicates the command line's flow.
2041
2042 The push is cancelled if the HTTP connection is closed.
2043
2044 **Example request**:
2045
2046     POST /v1.24/images/registry.acme.com:5000/test/push HTTP/1.1
2047
2048
2049 **Query parameters**:
2050
2051 -   **tag** – The tag to associate with the image on the registry. This is optional.
2052
2053 **Request Headers**:
2054
2055 -   **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
2056     - Credential based login:
2057
2058         ```
2059     {
2060             "username": "jdoe",
2061             "password": "secret",
2062             "email": "jdoe@acme.com",
2063     }
2064         ```
2065
2066     - Identity token based login:
2067
2068         ```
2069     {
2070             "identitytoken": "9cbaf023786cd7..."
2071     }
2072         ```
2073
2074 **Status codes**:
2075
2076 -   **200** – no error
2077 -   **404** – no such image
2078 -   **500** – server error
2079
2080 #### Tag an image into a repository
2081
2082 `POST /images/(name)/tag`
2083
2084 Tag the image `name` into a repository
2085
2086 **Example request**:
2087
2088     POST /v1.24/images/test/tag?repo=myrepo&tag=v42 HTTP/1.1
2089
2090 **Example response**:
2091
2092     HTTP/1.1 201 Created
2093
2094 **Query parameters**:
2095
2096 -   **repo** – The repository to tag in
2097 -   **tag** - The new tag name
2098
2099 **Status codes**:
2100
2101 -   **201** – no error
2102 -   **400** – bad parameter
2103 -   **404** – no such image
2104 -   **409** – conflict
2105 -   **500** – server error
2106
2107 #### Remove an image
2108
2109 `DELETE /images/(name)`
2110
2111 Remove the image `name` from the filesystem
2112
2113 **Example request**:
2114
2115     DELETE /v1.24/images/test HTTP/1.1
2116
2117 **Example response**:
2118
2119     HTTP/1.1 200 OK
2120     Content-type: application/json
2121
2122     [
2123      {"Untagged": "3e2f21a89f"},
2124      {"Deleted": "3e2f21a89f"},
2125      {"Deleted": "53b4f83ac9"}
2126     ]
2127
2128 **Query parameters**:
2129
2130 -   **force** – 1/True/true or 0/False/false, default false
2131 -   **noprune** – 1/True/true or 0/False/false, default false
2132
2133 **Status codes**:
2134
2135 -   **200** – no error
2136 -   **404** – no such image
2137 -   **409** – conflict
2138 -   **500** – server error
2139
2140 #### Search images
2141
2142 `GET /images/search`
2143
2144 Search for an image on [Docker Hub](https://hub.docker.com).
2145
2146 > **Note**:
2147 > The response keys have changed from API v1.6 to reflect the JSON
2148 > sent by the registry server to the docker daemon's request.
2149
2150 **Example request**:
2151
2152     GET /v1.24/images/search?term=sshd HTTP/1.1
2153
2154 **Example response**:
2155
2156     HTTP/1.1 200 OK
2157     Content-Type: application/json
2158
2159     [
2160             {
2161                 "description": "",
2162                 "is_official": false,
2163                 "is_automated": false,
2164                 "name": "wma55/u1210sshd",
2165                 "star_count": 0
2166             },
2167             {
2168                 "description": "",
2169                 "is_official": false,
2170                 "is_automated": false,
2171                 "name": "jdswinbank/sshd",
2172                 "star_count": 0
2173             },
2174             {
2175                 "description": "",
2176                 "is_official": false,
2177                 "is_automated": false,
2178                 "name": "vgauthier/sshd",
2179                 "star_count": 0
2180             }
2181     ...
2182     ]
2183
2184 **Query parameters**:
2185
2186 -   **term** – term to search
2187 -   **limit** – maximum returned search results
2188 -   **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
2189   -   `stars=<number>`
2190   -   `is-automated=(true|false)`
2191   -   `is-official=(true|false)`
2192
2193 **Status codes**:
2194
2195 -   **200** – no error
2196 -   **500** – server error
2197
2198 ### 3.3 Misc
2199
2200 #### Check auth configuration
2201
2202 `POST /auth`
2203
2204 Validate credentials for a registry and get identity token,
2205 if available, for accessing the registry without password.
2206
2207 **Example request**:
2208
2209     POST /v1.24/auth HTTP/1.1
2210     Content-Type: application/json
2211
2212     {
2213          "username": "hannibal",
2214          "password": "xxxx",
2215          "serveraddress": "https://index.docker.io/v1/"
2216     }
2217
2218 **Example response**:
2219
2220     HTTP/1.1 200 OK
2221
2222     {
2223          "Status": "Login Succeeded",
2224          "IdentityToken": "9cbaf023786cd7..."
2225     }
2226
2227 **Status codes**:
2228
2229 -   **200** – no error
2230 -   **204** – no error
2231 -   **500** – server error
2232
2233 #### Display system-wide information
2234
2235 `GET /info`
2236
2237 Display system-wide information
2238
2239 **Example request**:
2240
2241     GET /v1.24/info HTTP/1.1
2242
2243 **Example response**:
2244
2245     HTTP/1.1 200 OK
2246     Content-Type: application/json
2247
2248     {
2249         "Architecture": "x86_64",
2250         "ClusterStore": "etcd://localhost:2379",
2251         "CgroupDriver": "cgroupfs",
2252         "Containers": 11,
2253         "ContainersRunning": 7,
2254         "ContainersStopped": 3,
2255         "ContainersPaused": 1,
2256         "CpuCfsPeriod": true,
2257         "CpuCfsQuota": true,
2258         "Debug": false,
2259         "DockerRootDir": "/var/lib/docker",
2260         "Driver": "btrfs",
2261         "DriverStatus": [[""]],
2262         "ExperimentalBuild": false,
2263         "HttpProxy": "http://test:test@localhost:8080",
2264         "HttpsProxy": "https://test:test@localhost:8080",
2265         "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
2266         "IPv4Forwarding": true,
2267         "Images": 16,
2268         "IndexServerAddress": "https://index.docker.io/v1/",
2269         "InitPath": "/usr/bin/docker",
2270         "InitSha1": "",
2271         "KernelMemory": true,
2272         "KernelVersion": "3.12.0-1-amd64",
2273         "Labels": [
2274             "storage=ssd"
2275         ],
2276         "MemTotal": 2099236864,
2277         "MemoryLimit": true,
2278         "NCPU": 1,
2279         "NEventsListener": 0,
2280         "NFd": 11,
2281         "NGoroutines": 21,
2282         "Name": "prod-server-42",
2283         "NoProxy": "9.81.1.160",
2284         "OomKillDisable": true,
2285         "OSType": "linux",
2286         "OperatingSystem": "Boot2Docker",
2287         "Plugins": {
2288             "Volume": [
2289                 "local"
2290             ],
2291             "Network": [
2292                 "null",
2293                 "host",
2294                 "bridge"
2295             ]
2296         },
2297         "RegistryConfig": {
2298             "IndexConfigs": {
2299                 "docker.io": {
2300                     "Mirrors": null,
2301                     "Name": "docker.io",
2302                     "Official": true,
2303                     "Secure": true
2304                 }
2305             },
2306             "InsecureRegistryCIDRs": [
2307                 "127.0.0.0/8"
2308             ]
2309         },
2310         "SecurityOptions": [
2311             "apparmor",
2312             "seccomp",
2313             "selinux"
2314         ],
2315         "ServerVersion": "1.9.0",
2316         "SwapLimit": false,
2317         "SystemStatus": [["State", "Healthy"]],
2318         "SystemTime": "2015-03-10T11:11:23.730591467-07:00"
2319     }
2320
2321 **Status codes**:
2322
2323 -   **200** – no error
2324 -   **500** – server error
2325
2326 #### Show the docker version information
2327
2328 `GET /version`
2329
2330 Show the docker version information
2331
2332 **Example request**:
2333
2334     GET /v1.24/version HTTP/1.1
2335
2336 **Example response**:
2337
2338     HTTP/1.1 200 OK
2339     Content-Type: application/json
2340
2341     {
2342          "Version": "1.12.0",
2343          "Os": "linux",
2344          "KernelVersion": "3.19.0-23-generic",
2345          "GoVersion": "go1.6.3",
2346          "GitCommit": "deadbee",
2347          "Arch": "amd64",
2348          "ApiVersion": "1.24",
2349          "BuildTime": "2016-06-14T07:09:13.444803460+00:00",
2350          "Experimental": true
2351     }
2352
2353 **Status codes**:
2354
2355 -   **200** – no error
2356 -   **500** – server error
2357
2358 #### Ping the docker server
2359
2360 `GET /_ping`
2361
2362 Ping the docker server
2363
2364 **Example request**:
2365
2366     GET /v1.24/_ping HTTP/1.1
2367
2368 **Example response**:
2369
2370     HTTP/1.1 200 OK
2371     Content-Type: text/plain
2372
2373     OK
2374
2375 **Status codes**:
2376
2377 -   **200** - no error
2378 -   **500** - server error
2379
2380 #### Create a new image from a container's changes
2381
2382 `POST /commit`
2383
2384 Create a new image from a container's changes
2385
2386 **Example request**:
2387
2388     POST /v1.24/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
2389     Content-Type: application/json
2390
2391     {
2392          "Hostname": "",
2393          "Domainname": "",
2394          "User": "",
2395          "AttachStdin": false,
2396          "AttachStdout": true,
2397          "AttachStderr": true,
2398          "Tty": false,
2399          "OpenStdin": false,
2400          "StdinOnce": false,
2401          "Env": null,
2402          "Cmd": [
2403                  "date"
2404          ],
2405          "Mounts": [
2406            {
2407              "Source": "/data",
2408              "Destination": "/data",
2409              "Mode": "ro,Z",
2410              "RW": false
2411            }
2412          ],
2413          "Labels": {
2414                  "key1": "value1",
2415                  "key2": "value2"
2416           },
2417          "WorkingDir": "",
2418          "NetworkDisabled": false,
2419          "ExposedPorts": {
2420                  "22/tcp": {}
2421          }
2422     }
2423
2424 **Example response**:
2425
2426     HTTP/1.1 201 Created
2427     Content-Type: application/json
2428
2429     {"Id": "596069db4bf5"}
2430
2431 **JSON parameters**:
2432
2433 -  **config** - the container's configuration
2434
2435 **Query parameters**:
2436
2437 -   **container** – source container
2438 -   **repo** – repository
2439 -   **tag** – tag
2440 -   **comment** – commit message
2441 -   **author** – author (e.g., "John Hannibal Smith
2442     <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
2443 -   **pause** – 1/True/true or 0/False/false, whether to pause the container before committing
2444 -   **changes** – Dockerfile instructions to apply while committing
2445
2446 **Status codes**:
2447
2448 -   **201** – no error
2449 -   **404** – no such container
2450 -   **500** – server error
2451
2452 #### Monitor Docker's events
2453
2454 `GET /events`
2455
2456 Get container events from docker, in real time via streaming.
2457
2458 Docker containers report the following events:
2459
2460     attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update
2461
2462 Docker images report the following events:
2463
2464     delete, import, load, pull, push, save, tag, untag
2465
2466 Docker volumes report the following events:
2467
2468     create, mount, unmount, destroy
2469
2470 Docker networks report the following events:
2471
2472     create, connect, disconnect, destroy
2473
2474 Docker daemon report the following event:
2475
2476     reload
2477
2478 **Example request**:
2479
2480     GET /v1.24/events?since=1374067924
2481
2482 **Example response**:
2483
2484     HTTP/1.1 200 OK
2485     Content-Type: application/json
2486     Server: Docker/1.12.0 (linux)
2487     Date: Fri, 29 Apr 2016 15:18:06 GMT
2488     Transfer-Encoding: chunked
2489
2490     {
2491       "status": "pull",
2492       "id": "alpine:latest",
2493       "Type": "image",
2494       "Action": "pull",
2495       "Actor": {
2496         "ID": "alpine:latest",
2497         "Attributes": {
2498           "name": "alpine"
2499         }
2500       },
2501       "time": 1461943101,
2502       "timeNano": 1461943101301854122
2503     }
2504     {
2505       "status": "create",
2506       "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2507       "from": "alpine",
2508       "Type": "container",
2509       "Action": "create",
2510       "Actor": {
2511         "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2512         "Attributes": {
2513           "com.example.some-label": "some-label-value",
2514           "image": "alpine",
2515           "name": "my-container"
2516         }
2517       },
2518       "time": 1461943101,
2519       "timeNano": 1461943101381709551
2520     }
2521     {
2522       "status": "attach",
2523       "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2524       "from": "alpine",
2525       "Type": "container",
2526       "Action": "attach",
2527       "Actor": {
2528         "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2529         "Attributes": {
2530           "com.example.some-label": "some-label-value",
2531           "image": "alpine",
2532           "name": "my-container"
2533         }
2534       },
2535       "time": 1461943101,
2536       "timeNano": 1461943101383858412
2537     }
2538     {
2539       "Type": "network",
2540       "Action": "connect",
2541       "Actor": {
2542         "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474",
2543         "Attributes": {
2544           "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2545           "name": "bridge",
2546           "type": "bridge"
2547         }
2548       },
2549       "time": 1461943101,
2550       "timeNano": 1461943101394865557
2551     }
2552     {
2553       "status": "start",
2554       "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2555       "from": "alpine",
2556       "Type": "container",
2557       "Action": "start",
2558       "Actor": {
2559         "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2560         "Attributes": {
2561           "com.example.some-label": "some-label-value",
2562           "image": "alpine",
2563           "name": "my-container"
2564         }
2565       },
2566       "time": 1461943101,
2567       "timeNano": 1461943101607533796
2568     }
2569     {
2570       "status": "resize",
2571       "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2572       "from": "alpine",
2573       "Type": "container",
2574       "Action": "resize",
2575       "Actor": {
2576         "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2577         "Attributes": {
2578           "com.example.some-label": "some-label-value",
2579           "height": "46",
2580           "image": "alpine",
2581           "name": "my-container",
2582           "width": "204"
2583         }
2584       },
2585       "time": 1461943101,
2586       "timeNano": 1461943101610269268
2587     }
2588     {
2589       "status": "die",
2590       "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2591       "from": "alpine",
2592       "Type": "container",
2593       "Action": "die",
2594       "Actor": {
2595         "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2596         "Attributes": {
2597           "com.example.some-label": "some-label-value",
2598           "exitCode": "0",
2599           "image": "alpine",
2600           "name": "my-container"
2601         }
2602       },
2603       "time": 1461943105,
2604       "timeNano": 1461943105079144137
2605     }
2606     {
2607       "Type": "network",
2608       "Action": "disconnect",
2609       "Actor": {
2610         "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474",
2611         "Attributes": {
2612           "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2613           "name": "bridge",
2614           "type": "bridge"
2615         }
2616       },
2617       "time": 1461943105,
2618       "timeNano": 1461943105230860245
2619     }
2620     {
2621       "status": "destroy",
2622       "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2623       "from": "alpine",
2624       "Type": "container",
2625       "Action": "destroy",
2626       "Actor": {
2627         "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
2628         "Attributes": {
2629           "com.example.some-label": "some-label-value",
2630           "image": "alpine",
2631           "name": "my-container"
2632         }
2633       },
2634       "time": 1461943105,
2635       "timeNano": 1461943105338056026
2636     }
2637
2638 **Query parameters**:
2639
2640 -   **since** – Timestamp. Show all events created since timestamp and then stream
2641 -   **until** – Timestamp. Show events created until given timestamp and stop streaming
2642 -   **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters:
2643   -   `container=<string>`; -- container to filter
2644   -   `event=<string>`; -- event to filter
2645   -   `image=<string>`; -- image to filter
2646   -   `label=<string>`; -- image and container label to filter
2647   -   `type=<string>`; -- either `container` or `image` or `volume` or `network` or `daemon`
2648   -   `volume=<string>`; -- volume to filter
2649   -   `network=<string>`; -- network to filter
2650   -   `daemon=<string>`; -- daemon name or id to filter
2651
2652 **Status codes**:
2653
2654 -   **200** – no error
2655 -   **400** - bad parameter
2656 -   **500** – server error
2657
2658 #### Get a tarball containing all images in a repository
2659
2660 `GET /images/(name)/get`
2661
2662 Get a tarball containing all images and metadata for the repository specified
2663 by `name`.
2664
2665 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
2666 (and its parents) are returned. If `name` is an image ID, similarly only that
2667 image (and its parents) are returned, but with the exclusion of the
2668 'repositories' file in the tarball, as there were no image names referenced.
2669
2670 See the [image tarball format](#image-tarball-format) for more details.
2671
2672 **Example request**
2673
2674     GET /v1.24/images/ubuntu/get
2675
2676 **Example response**:
2677
2678     HTTP/1.1 200 OK
2679     Content-Type: application/x-tar
2680
2681     Binary data stream
2682
2683 **Status codes**:
2684
2685 -   **200** – no error
2686 -   **500** – server error
2687
2688 #### Get a tarball containing all images
2689
2690 `GET /images/get`
2691
2692 Get a tarball containing all images and metadata for one or more repositories.
2693
2694 For each value of the `names` parameter: if it is a specific name and tag (e.g.
2695 `ubuntu:latest`), then only that image (and its parents) are returned; if it is
2696 an image ID, similarly only that image (and its parents) are returned and there
2697 would be no names referenced in the 'repositories' file for this image ID.
2698
2699 See the [image tarball format](#image-tarball-format) for more details.
2700
2701 **Example request**
2702
2703     GET /v1.24/images/get?names=myname%2Fmyapp%3Alatest&names=busybox
2704
2705 **Example response**:
2706
2707     HTTP/1.1 200 OK
2708     Content-Type: application/x-tar
2709
2710     Binary data stream
2711
2712 **Status codes**:
2713
2714 -   **200** – no error
2715 -   **500** – server error
2716
2717 #### Load a tarball with a set of images and tags into docker
2718
2719 `POST /images/load`
2720
2721 Load a set of images and tags into a Docker repository.
2722 See the [image tarball format](#image-tarball-format) for more details.
2723
2724 **Example request**
2725
2726     POST /v1.24/images/load
2727     Content-Type: application/x-tar
2728
2729     Tarball in body
2730
2731 **Example response**:
2732
2733     HTTP/1.1 200 OK
2734     Content-Type: application/json
2735     Transfer-Encoding: chunked
2736
2737     {"status":"Loading layer","progressDetail":{"current":32768,"total":1292800},"progress":"[=                                                 ] 32.77 kB/1.293 MB","id":"8ac8bfaff55a"}
2738     {"status":"Loading layer","progressDetail":{"current":65536,"total":1292800},"progress":"[==                                                ] 65.54 kB/1.293 MB","id":"8ac8bfaff55a"}
2739     {"status":"Loading layer","progressDetail":{"current":98304,"total":1292800},"progress":"[===                                               ]  98.3 kB/1.293 MB","id":"8ac8bfaff55a"}
2740     {"status":"Loading layer","progressDetail":{"current":131072,"total":1292800},"progress":"[=====                                             ] 131.1 kB/1.293 MB","id":"8ac8bfaff55a"}
2741     ...
2742     {"stream":"Loaded image: busybox:latest\n"}
2743
2744 **Example response**:
2745
2746 If the "quiet" query parameter is set to `true` / `1` (`?quiet=1`), progress
2747 details are suppressed, and only a confirmation message is returned once the
2748 action completes.
2749
2750     HTTP/1.1 200 OK
2751     Content-Type: application/json
2752     Transfer-Encoding: chunked
2753
2754     {"stream":"Loaded image: busybox:latest\n"}
2755
2756 **Query parameters**:
2757
2758 -   **quiet** – Boolean value, suppress progress details during load. Defaults
2759       to `0` / `false` if omitted.
2760
2761 **Status codes**:
2762
2763 -   **200** – no error
2764 -   **500** – server error
2765
2766 #### Image tarball format
2767
2768 An image tarball contains one directory per image layer (named using its long ID),
2769 each containing these files:
2770
2771 - `VERSION`: currently `1.0` - the file format version
2772 - `json`: detailed layer information, similar to `docker inspect layer_id`
2773 - `layer.tar`: A tarfile containing the filesystem changes in this layer
2774
2775 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories
2776 for storing attribute changes and deletions.
2777
2778 If the tarball defines a repository, the tarball should also include a `repositories` file at
2779 the root that contains a list of repository and tag names mapped to layer IDs.
2780
2781 ```
2782 {"hello-world":
2783     {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
2784 }
2785 ```
2786
2787 #### Exec Create
2788
2789 `POST /containers/(id or name)/exec`
2790
2791 Sets up an exec instance in a running container `id`
2792
2793 **Example request**:
2794
2795     POST /v1.24/containers/e90e34656806/exec HTTP/1.1
2796     Content-Type: application/json
2797
2798     {
2799       "AttachStdin": true,
2800       "AttachStdout": true,
2801       "AttachStderr": true,
2802       "Cmd": ["sh"],
2803       "DetachKeys": "ctrl-p,ctrl-q",
2804       "Privileged": true,
2805       "Tty": true,
2806       "User": "123:456"
2807     }
2808
2809 **Example response**:
2810
2811     HTTP/1.1 201 Created
2812     Content-Type: application/json
2813
2814     {
2815          "Id": "f90e34656806",
2816          "Warnings":[]
2817     }
2818
2819 **JSON parameters**:
2820
2821 -   **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
2822 -   **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
2823 -   **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command.
2824 -   **DetachKeys** – Override the key sequence for detaching a
2825         container. Format is a single character `[a-Z]` or `ctrl-<value>`
2826         where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
2827 -   **Tty** - Boolean value to allocate a pseudo-TTY.
2828 -   **Cmd** - Command to run specified as a string or an array of strings.
2829 -   **Privileged** - Boolean value, runs the exec process with extended privileges.
2830 -   **User** - A string value specifying the user, and optionally, group to run
2831         the exec process inside the container. Format is one of: `"user"`,
2832         `"user:group"`, `"uid"`, or `"uid:gid"`.
2833
2834 **Status codes**:
2835
2836 -   **201** – no error
2837 -   **404** – no such container
2838 -   **409** - container is paused
2839 -   **500** - server error
2840
2841 #### Exec Start
2842
2843 `POST /exec/(id)/start`
2844
2845 Starts a previously set up `exec` instance `id`. If `detach` is true, this API
2846 returns after starting the `exec` command. Otherwise, this API sets up an
2847 interactive session with the `exec` command.
2848
2849 **Example request**:
2850
2851     POST /v1.24/exec/e90e34656806/start HTTP/1.1
2852     Content-Type: application/json
2853
2854     {
2855      "Detach": false,
2856      "Tty": false
2857     }
2858
2859 **Example response**:
2860
2861     HTTP/1.1 200 OK
2862     Content-Type: application/vnd.docker.raw-stream
2863
2864     {% raw %}
2865     {{ STREAM }}
2866     {% endraw %}
2867
2868 **JSON parameters**:
2869
2870 -   **Detach** - Detach from the `exec` command.
2871 -   **Tty** - Boolean value to allocate a pseudo-TTY.
2872
2873 **Status codes**:
2874
2875 -   **200** – no error
2876 -   **404** – no such exec instance
2877 -   **409** - container is paused
2878
2879 **Stream details**:
2880
2881 Similar to the stream behavior of `POST /containers/(id or name)/attach` API
2882
2883 #### Exec Resize
2884
2885 `POST /exec/(id)/resize`
2886
2887 Resizes the `tty` session used by the `exec` command `id`.  The unit is number of characters.
2888 This API is valid only if `tty` was specified as part of creating and starting the `exec` command.
2889
2890 **Example request**:
2891
2892     POST /v1.24/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1
2893     Content-Type: text/plain
2894
2895 **Example response**:
2896
2897     HTTP/1.1 201 Created
2898     Content-Type: text/plain
2899
2900 **Query parameters**:
2901
2902 -   **h** – height of `tty` session
2903 -   **w** – width
2904
2905 **Status codes**:
2906
2907 -   **201** – no error
2908 -   **404** – no such exec instance
2909
2910 #### Exec Inspect
2911
2912 `GET /exec/(id)/json`
2913
2914 Return low-level information about the `exec` command `id`.
2915
2916 **Example request**:
2917
2918     GET /v1.24/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1
2919
2920 **Example response**:
2921
2922     HTTP/1.1 200 OK
2923     Content-Type: application/json
2924
2925     {
2926       "CanRemove": false,
2927       "ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
2928       "DetachKeys": "",
2929       "ExitCode": 2,
2930       "ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
2931       "OpenStderr": true,
2932       "OpenStdin": true,
2933       "OpenStdout": true,
2934       "ProcessConfig": {
2935         "arguments": [
2936           "-c",
2937           "exit 2"
2938         ],
2939         "entrypoint": "sh",
2940         "privileged": false,
2941         "tty": true,
2942         "user": "1000"
2943       },
2944       "Running": false
2945     }
2946
2947 **Status codes**:
2948
2949 -   **200** – no error
2950 -   **404** – no such exec instance
2951 -   **500** - server error
2952
2953 ### 3.4 Volumes
2954
2955 #### List volumes
2956
2957 `GET /volumes`
2958
2959 **Example request**:
2960
2961     GET /v1.24/volumes HTTP/1.1
2962
2963 **Example response**:
2964
2965     HTTP/1.1 200 OK
2966     Content-Type: application/json
2967
2968     {
2969       "Volumes": [
2970         {
2971           "Name": "tardis",
2972           "Driver": "local",
2973           "Mountpoint": "/var/lib/docker/volumes/tardis",
2974           "Labels": null,
2975           "Scope": "local"
2976         }
2977       ],
2978       "Warnings": []
2979     }
2980
2981 **Query parameters**:
2982
2983 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:
2984   -   `name=<volume-name>` Matches all or part of a volume name.
2985   -   `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are "dangling" (not in use by a container). When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
2986   -   `driver=<volume-driver-name>` Matches all or part of a volume driver name.
2987
2988 **Status codes**:
2989
2990 -   **200** - no error
2991 -   **500** - server error
2992
2993 #### Create a volume
2994
2995 `POST /volumes/create`
2996
2997 Create a volume
2998
2999 **Example request**:
3000
3001     POST /v1.24/volumes/create HTTP/1.1
3002     Content-Type: application/json
3003
3004     {
3005       "Name": "tardis",
3006       "Labels": {
3007         "com.example.some-label": "some-value",
3008         "com.example.some-other-label": "some-other-value"
3009       },
3010       "Driver": "custom"
3011     }
3012
3013 **Example response**:
3014
3015     HTTP/1.1 201 Created
3016     Content-Type: application/json
3017
3018     {
3019       "Name": "tardis",
3020       "Driver": "custom",
3021       "Mountpoint": "/var/lib/docker/volumes/tardis",
3022       "Status": {
3023         "hello": "world"
3024       },
3025       "Labels": {
3026         "com.example.some-label": "some-value",
3027         "com.example.some-other-label": "some-other-value"
3028       },
3029       "Scope": "local"
3030     }
3031
3032 **Status codes**:
3033
3034 - **201** - no error
3035 - **500**  - server error
3036
3037 **JSON parameters**:
3038
3039 - **Name** - The new volume's name. If not specified, Docker generates a name.
3040 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name.
3041 - **DriverOpts** - A mapping of driver options and values. These options are
3042     passed directly to the driver and are driver specific.
3043 - **Labels** - Labels to set on the volume, specified as a map: `{"key":"value","key2":"value2"}`
3044
3045 **JSON fields in response**:
3046
3047 Refer to the [inspect a volume](#inspect-a-volume) section or details about the
3048 JSON fields returned in the response.
3049
3050 #### Inspect a volume
3051
3052 `GET /volumes/(name)`
3053
3054 Return low-level information on the volume `name`
3055
3056 **Example request**:
3057
3058     GET /v1.24/volumes/tardis
3059
3060 **Example response**:
3061
3062     HTTP/1.1 200 OK
3063     Content-Type: application/json
3064
3065     {
3066       "Name": "tardis",
3067       "Driver": "custom",
3068       "Mountpoint": "/var/lib/docker/volumes/tardis/_data",
3069       "Status": {
3070         "hello": "world"
3071       },
3072       "Labels": {
3073           "com.example.some-label": "some-value",
3074           "com.example.some-other-label": "some-other-value"
3075       },
3076       "Scope": "local"
3077     }
3078
3079 **Status codes**:
3080
3081 -   **200** - no error
3082 -   **404** - no such volume
3083 -   **500** - server error
3084
3085 **JSON fields in response**:
3086
3087 The following fields can be returned in the API response. Empty fields, or
3088 fields that are not supported by the volume's driver may be omitted in the
3089 response.
3090
3091 - **Name** - Name of the volume.
3092 - **Driver** - Name of the volume driver used by the volume.
3093 - **Mountpoint** - Mount path of the volume on the host.
3094 - **Status** - Low-level details about the volume, provided by the volume driver.
3095     Details are returned as a map with key/value pairs: `{"key":"value","key2":"value2"}`.
3096     The `Status` field is optional, and is omitted if the volume driver does not
3097     support this feature.
3098 - **Labels** - Labels set on the volume, specified as a map: `{"key":"value","key2":"value2"}`.
3099 - **Scope** - Scope describes the level at which the volume exists, can be one of
3100     `global` for cluster-wide or `local` for machine level. The default is `local`.
3101
3102 #### Remove a volume
3103
3104 `DELETE /volumes/(name)`
3105
3106 Instruct the driver to remove the volume (`name`).
3107
3108 **Example request**:
3109
3110     DELETE /v1.24/volumes/tardis HTTP/1.1
3111
3112 **Example response**:
3113
3114     HTTP/1.1 204 No Content
3115
3116 **Status codes**:
3117
3118 -   **204** - no error
3119 -   **404** - no such volume or volume driver
3120 -   **409** - volume is in use and cannot be removed
3121 -   **500** - server error
3122
3123 ### 3.5 Networks
3124
3125 #### List networks
3126
3127 `GET /networks`
3128
3129 **Example request**:
3130
3131     GET /v1.24/networks?filters={"type":{"custom":true}} HTTP/1.1
3132
3133 **Example response**:
3134
3135 ```
3136 HTTP/1.1 200 OK
3137 Content-Type: application/json
3138
3139 [
3140   {
3141     "Name": "bridge",
3142     "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
3143     "Scope": "local",
3144     "Driver": "bridge",
3145     "EnableIPv6": false,
3146     "Internal": false,
3147     "IPAM": {
3148       "Driver": "default",
3149       "Config": [
3150         {
3151           "Subnet": "172.17.0.0/16"
3152         }
3153       ]
3154     },
3155     "Containers": {
3156       "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": {
3157         "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda",
3158         "MacAddress": "02:42:ac:11:00:02",
3159         "IPv4Address": "172.17.0.2/16",
3160         "IPv6Address": ""
3161       }
3162     },
3163     "Options": {
3164       "com.docker.network.bridge.default_bridge": "true",
3165       "com.docker.network.bridge.enable_icc": "true",
3166       "com.docker.network.bridge.enable_ip_masquerade": "true",
3167       "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
3168       "com.docker.network.bridge.name": "docker0",
3169       "com.docker.network.driver.mtu": "1500"
3170     }
3171   },
3172   {
3173     "Name": "none",
3174     "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
3175     "Scope": "local",
3176     "Driver": "null",
3177     "EnableIPv6": false,
3178     "Internal": false,
3179     "IPAM": {
3180       "Driver": "default",
3181       "Config": []
3182     },
3183     "Containers": {},
3184     "Options": {}
3185   },
3186   {
3187     "Name": "host",
3188     "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
3189     "Scope": "local",
3190     "Driver": "host",
3191     "EnableIPv6": false,
3192     "Internal": false,
3193     "IPAM": {
3194       "Driver": "default",
3195       "Config": []
3196     },
3197     "Containers": {},
3198     "Options": {}
3199   }
3200 ]
3201 ```
3202
3203 **Query parameters**:
3204
3205 - **filters** - JSON encoded network list filter. The filter value is one of:
3206   -   `driver=<driver-name>` Matches a network's driver.
3207   -   `id=<network-id>` Matches all or part of a network id.
3208   -   `label=<key>` or `label=<key>=<value>` of a network label.
3209   -   `name=<network-name>` Matches all or part of a network name.
3210   -   `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks.
3211
3212 **Status codes**:
3213
3214 -   **200** - no error
3215 -   **500** - server error
3216
3217 #### Inspect network
3218
3219 `GET /networks/(id or name)`
3220
3221 Return low-level information on the network `id`
3222
3223 **Example request**:
3224
3225     GET /v1.24/networks/7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99 HTTP/1.1
3226
3227 **Example response**:
3228
3229 ```
3230 HTTP/1.1 200 OK
3231 Content-Type: application/json
3232
3233 {
3234   "Name": "net01",
3235   "Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
3236   "Scope": "local",
3237   "Driver": "bridge",
3238   "EnableIPv6": false,
3239   "IPAM": {
3240     "Driver": "default",
3241     "Config": [
3242       {
3243         "Subnet": "172.19.0.0/16",
3244         "Gateway": "172.19.0.1"
3245       }
3246     ],
3247     "Options": {
3248         "foo": "bar"
3249     }
3250   },
3251   "Internal": false,
3252   "Containers": {
3253     "19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
3254       "Name": "test",
3255       "EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
3256       "MacAddress": "02:42:ac:13:00:02",
3257       "IPv4Address": "172.19.0.2/16",
3258       "IPv6Address": ""
3259     }
3260   },
3261   "Options": {
3262     "com.docker.network.bridge.default_bridge": "true",
3263     "com.docker.network.bridge.enable_icc": "true",
3264     "com.docker.network.bridge.enable_ip_masquerade": "true",
3265     "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
3266     "com.docker.network.bridge.name": "docker0",
3267     "com.docker.network.driver.mtu": "1500"
3268   },
3269   "Labels": {
3270     "com.example.some-label": "some-value",
3271     "com.example.some-other-label": "some-other-value"
3272   }
3273 }
3274 ```
3275
3276 **Status codes**:
3277
3278 -   **200** - no error
3279 -   **404** - network not found
3280 -   **500** - server error
3281
3282 #### Create a network
3283
3284 `POST /networks/create`
3285
3286 Create a network
3287
3288 **Example request**:
3289
3290 ```
3291 POST /v1.24/networks/create HTTP/1.1
3292 Content-Type: application/json
3293
3294 {
3295   "Name":"isolated_nw",
3296   "CheckDuplicate":true,
3297   "Driver":"bridge",
3298   "EnableIPv6": true,
3299   "IPAM":{
3300     "Driver": "default",
3301     "Config":[
3302       {
3303         "Subnet":"172.20.0.0/16",
3304         "IPRange":"172.20.10.0/24",
3305         "Gateway":"172.20.10.11"
3306       },
3307       {
3308         "Subnet":"2001:db8:abcd::/64",
3309         "Gateway":"2001:db8:abcd::1011"
3310       }
3311     ],
3312     "Options": {
3313       "foo": "bar"
3314     }
3315   },
3316   "Internal":true,
3317   "Options": {
3318     "com.docker.network.bridge.default_bridge": "true",
3319     "com.docker.network.bridge.enable_icc": "true",
3320     "com.docker.network.bridge.enable_ip_masquerade": "true",
3321     "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
3322     "com.docker.network.bridge.name": "docker0",
3323     "com.docker.network.driver.mtu": "1500"
3324   },
3325   "Labels": {
3326     "com.example.some-label": "some-value",
3327     "com.example.some-other-label": "some-other-value"
3328   }
3329 }
3330 ```
3331
3332 **Example response**:
3333
3334 ```
3335 HTTP/1.1 201 Created
3336 Content-Type: application/json
3337
3338 {
3339   "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
3340   "Warning": ""
3341 }
3342 ```
3343
3344 **Status codes**:
3345
3346 - **201** - no error
3347 - **403** - operation not supported for pre-defined networks
3348 - **404** - plugin not found
3349 - **500** - server error
3350
3351 **JSON parameters**:
3352
3353 - **Name** - The new network's name. this is a mandatory field
3354 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
3355     Since Network is primarily keyed based on a random ID and not on the name,
3356     and network name is strictly a user-friendly alias to the network
3357     which is uniquely identified using ID, there is no guaranteed way to check for duplicates.
3358     This parameter CheckDuplicate is there to provide a best effort checking of any networks
3359     which has the same name but it is not guaranteed to catch all name collisions.
3360 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
3361 - **Internal** - Restrict external access to the network
3362 - **IPAM** - Optional custom IP scheme for the network
3363   - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver
3364   - **Config** - List of IPAM configuration options, specified as a map:
3365       `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}`
3366   - **Options** - Driver-specific options, specified as a map: `{"option":"value" [,"option2":"value2"]}`
3367 - **EnableIPv6** - Enable IPv6 on the network
3368 - **Options** - Network specific options to be used by the drivers
3369 - **Labels** - Labels to set on the network, specified as a map: `{"key":"value" [,"key2":"value2"]}`
3370
3371 #### Connect a container to a network
3372
3373 `POST /networks/(id or name)/connect`
3374
3375 Connect a container to a network
3376
3377 **Example request**:
3378
3379 ```
3380 POST /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
3381 Content-Type: application/json
3382
3383 {
3384   "Container":"3613f73ba0e4",
3385   "EndpointConfig": {
3386     "IPAMConfig": {
3387         "IPv4Address":"172.24.56.89",
3388         "IPv6Address":"2001:db8::5689"
3389     }
3390   }
3391 }
3392 ```
3393
3394 **Example response**:
3395
3396     HTTP/1.1 200 OK
3397
3398 **Status codes**:
3399
3400 - **200** - no error
3401 - **403** - operation not supported for swarm scoped networks
3402 - **404** - network or container is not found
3403 - **500** - Internal Server Error
3404
3405 **JSON parameters**:
3406
3407 - **container** - container-id/name to be connected to the network
3408
3409 #### Disconnect a container from a network
3410
3411 `POST /networks/(id or name)/disconnect`
3412
3413 Disconnect a container from a network
3414
3415 **Example request**:
3416
3417 ```
3418 POST /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
3419 Content-Type: application/json
3420
3421 {
3422   "Container":"3613f73ba0e4",
3423   "Force":false
3424 }
3425 ```
3426
3427 **Example response**:
3428
3429     HTTP/1.1 200 OK
3430
3431 **Status codes**:
3432
3433 - **200** - no error
3434 - **403** - operation not supported for swarm scoped networks
3435 - **404** - network or container not found
3436 - **500** - Internal Server Error
3437
3438 **JSON parameters**:
3439
3440 - **Container** - container-id/name to be disconnected from a network
3441 - **Force** - Force the container to disconnect from a network
3442
3443 #### Remove a network
3444
3445 `DELETE /networks/(id or name)`
3446
3447 Instruct the driver to remove the network (`id`).
3448
3449 **Example request**:
3450
3451     DELETE /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1
3452
3453 **Example response**:
3454
3455     HTTP/1.1 204 No Content
3456
3457 **Status codes**:
3458
3459 -   **204** - no error
3460 -   **403** - operation not supported for pre-defined networks
3461 -   **404** - no such network
3462 -   **500** - server error
3463
3464 ### 3.6 Plugins (experimental)
3465
3466 #### List plugins
3467
3468 `GET /plugins`
3469
3470 Returns information about installed plugins.
3471
3472 **Example request**:
3473
3474     GET /v1.24/plugins HTTP/1.1
3475
3476 **Example response**:
3477
3478 ```
3479 HTTP/1.1 200 OK
3480 Content-Type: application/json
3481
3482 [
3483   {
3484     "Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
3485     "Name": "tiborvass/no-remove",
3486     "Tag": "latest",
3487     "Active": true,
3488     "Config": {
3489       "Mounts": [
3490         {
3491           "Name": "",
3492           "Description": "",
3493           "Settable": null,
3494           "Source": "/data",
3495           "Destination": "/data",
3496           "Type": "bind",
3497           "Options": [
3498             "shared",
3499             "rbind"
3500           ]
3501         },
3502         {
3503           "Name": "",
3504           "Description": "",
3505           "Settable": null,
3506           "Source": null,
3507           "Destination": "/foobar",
3508           "Type": "tmpfs",
3509           "Options": null
3510         }
3511       ],
3512       "Env": [
3513         "DEBUG=1"
3514       ],
3515       "Args": null,
3516       "Devices": null
3517     },
3518     "Manifest": {
3519       "ManifestVersion": "v0",
3520       "Description": "A test plugin for Docker",
3521       "Documentation": "https://docs.docker.com/engine/extend/plugins/",
3522       "Interface": {
3523         "Types": [
3524           "docker.volumedriver/1.0"
3525         ],
3526         "Socket": "plugins.sock"
3527       },
3528       "Entrypoint": [
3529         "plugin-no-remove",
3530         "/data"
3531       ],
3532       "Workdir": "",
3533       "User": {
3534       },
3535       "Network": {
3536         "Type": "host"
3537       },
3538       "Capabilities": null,
3539       "Mounts": [
3540         {
3541           "Name": "",
3542           "Description": "",
3543           "Settable": null,
3544           "Source": "/data",
3545           "Destination": "/data",
3546           "Type": "bind",
3547           "Options": [
3548             "shared",
3549             "rbind"
3550           ]
3551         },
3552         {
3553           "Name": "",
3554           "Description": "",
3555           "Settable": null,
3556           "Source": null,
3557           "Destination": "/foobar",
3558           "Type": "tmpfs",
3559           "Options": null
3560         }
3561       ],
3562       "Devices": [
3563         {
3564           "Name": "device",
3565           "Description": "a host device to mount",
3566           "Settable": null,
3567           "Path": "/dev/cpu_dma_latency"
3568         }
3569       ],
3570       "Env": [
3571         {
3572           "Name": "DEBUG",
3573           "Description": "If set, prints debug messages",
3574           "Settable": null,
3575           "Value": "1"
3576         }
3577       ],
3578       "Args": {
3579         "Name": "args",
3580         "Description": "command line arguments",
3581         "Settable": null,
3582         "Value": [
3583
3584         ]
3585       }
3586     }
3587   }
3588 ]
3589 ```
3590
3591 **Status codes**:
3592
3593 -   **200** - no error
3594 -   **500** - server error
3595
3596 #### Install a plugin
3597
3598 `POST /plugins/pull?name=<plugin name>`
3599
3600 Pulls and installs a plugin. After the plugin is installed, it can be enabled
3601 using the [`POST /plugins/(plugin name)/enable` endpoint](#enable-a-plugin).
3602
3603 **Example request**:
3604
3605 ```
3606 POST /v1.24/plugins/pull?name=tiborvass/no-remove:latest HTTP/1.1
3607 ```
3608
3609 The `:latest` tag is optional, and is used as default if omitted. When using
3610 this endpoint to pull a plugin from the registry, the `X-Registry-Auth` header
3611 can be used to include a base64-encoded AuthConfig object. Refer to the [create
3612 an image](#create-an-image) section for more details.
3613
3614 **Example response**:
3615
3616 ```
3617 HTTP/1.1 200 OK
3618 Content-Type: application/json
3619 Content-Length: 175
3620
3621 [
3622   {
3623     "Name": "network",
3624     "Description": "",
3625     "Value": [
3626       "host"
3627     ]
3628   },
3629   {
3630     "Name": "mount",
3631     "Description": "",
3632     "Value": [
3633       "/data"
3634     ]
3635   },
3636   {
3637     "Name": "device",
3638     "Description": "",
3639     "Value": [
3640       "/dev/cpu_dma_latency"
3641     ]
3642   }
3643 ]
3644 ```
3645
3646 **Query parameters**:
3647
3648 - **name** -  Name of the plugin to pull. The name may include a tag or digest.
3649     This parameter is required.
3650
3651 **Status codes**:
3652
3653 -   **200** - no error
3654 -   **500** - error parsing reference / not a valid repository/tag: repository
3655       name must have at least one component
3656 -   **500** - plugin already exists
3657
3658 #### Inspect a plugin
3659
3660 `GET /plugins/(plugin name)`
3661
3662 Returns detailed information about an installed plugin.
3663
3664 **Example request**:
3665
3666 ```
3667 GET /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1
3668 ```
3669
3670 The `:latest` tag is optional, and is used as default if omitted.
3671
3672
3673 **Example response**:
3674
3675 ```
3676 HTTP/1.1 200 OK
3677 Content-Type: application/json
3678
3679 {
3680   "Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
3681   "Name": "tiborvass/no-remove",
3682   "Tag": "latest",
3683   "Active": false,
3684   "Config": {
3685     "Mounts": [
3686       {
3687         "Name": "",
3688         "Description": "",
3689         "Settable": null,
3690         "Source": "/data",
3691         "Destination": "/data",
3692         "Type": "bind",
3693         "Options": [
3694           "shared",
3695           "rbind"
3696         ]
3697       },
3698       {
3699         "Name": "",
3700         "Description": "",
3701         "Settable": null,
3702         "Source": null,
3703         "Destination": "/foobar",
3704         "Type": "tmpfs",
3705         "Options": null
3706       }
3707     ],
3708     "Env": [
3709       "DEBUG=1"
3710     ],
3711     "Args": null,
3712     "Devices": null
3713   },
3714   "Manifest": {
3715     "ManifestVersion": "v0",
3716     "Description": "A test plugin for Docker",
3717     "Documentation": "https://docs.docker.com/engine/extend/plugins/",
3718     "Interface": {
3719       "Types": [
3720         "docker.volumedriver/1.0"
3721       ],
3722       "Socket": "plugins.sock"
3723     },
3724     "Entrypoint": [
3725       "plugin-no-remove",
3726       "/data"
3727     ],
3728     "Workdir": "",
3729     "User": {
3730     },
3731     "Network": {
3732       "Type": "host"
3733     },
3734     "Capabilities": null,
3735     "Mounts": [
3736       {
3737         "Name": "",
3738         "Description": "",
3739         "Settable": null,
3740         "Source": "/data",
3741         "Destination": "/data",
3742         "Type": "bind",
3743         "Options": [
3744           "shared",
3745           "rbind"
3746         ]
3747       },
3748       {
3749         "Name": "",
3750         "Description": "",
3751         "Settable": null,
3752         "Source": null,
3753         "Destination": "/foobar",
3754         "Type": "tmpfs",
3755         "Options": null
3756       }
3757     ],
3758     "Devices": [
3759       {
3760         "Name": "device",
3761         "Description": "a host device to mount",
3762         "Settable": null,
3763         "Path": "/dev/cpu_dma_latency"
3764       }
3765     ],
3766     "Env": [
3767       {
3768         "Name": "DEBUG",
3769         "Description": "If set, prints debug messages",
3770         "Settable": null,
3771         "Value": "1"
3772       }
3773     ],
3774     "Args": {
3775       "Name": "args",
3776       "Description": "command line arguments",
3777       "Settable": null,
3778       "Value": [
3779
3780       ]
3781     }
3782   }
3783 }
3784 ```
3785
3786 **Status codes**:
3787
3788 -   **200** - no error
3789 -   **404** - plugin not installed
3790
3791 #### Enable a plugin
3792
3793 `POST /plugins/(plugin name)/enable`
3794
3795 Enables a plugin
3796
3797 **Example request**:
3798
3799 ```
3800 POST /v1.24/plugins/tiborvass/no-remove:latest/enable HTTP/1.1
3801 ```
3802
3803 The `:latest` tag is optional, and is used as default if omitted.
3804
3805
3806 **Example response**:
3807
3808 ```
3809 HTTP/1.1 200 OK
3810 Content-Length: 0
3811 Content-Type: text/plain; charset=utf-8
3812 ```
3813
3814 **Status codes**:
3815
3816 -   **200** - no error
3817 -   **404** - plugin not installed
3818 -   **500** - plugin is already enabled
3819
3820 #### Disable a plugin
3821
3822 `POST /plugins/(plugin name)/disable`
3823
3824 Disables a plugin
3825
3826 **Example request**:
3827
3828 ```
3829 POST /v1.24/plugins/tiborvass/no-remove:latest/disable HTTP/1.1
3830 ```
3831
3832 The `:latest` tag is optional, and is used as default if omitted.
3833
3834
3835 **Example response**:
3836
3837 ```
3838 HTTP/1.1 200 OK
3839 Content-Length: 0
3840 Content-Type: text/plain; charset=utf-8
3841 ```
3842
3843 **Status codes**:
3844
3845 -   **200** - no error
3846 -   **404** - plugin not installed
3847 -   **500** - plugin is already disabled
3848
3849 #### Remove a plugin
3850
3851 `DELETE /plugins/(plugin name)`
3852
3853 Removes a plugin
3854
3855 **Example request**:
3856
3857 ```
3858 DELETE /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1
3859 ```
3860
3861 The `:latest` tag is optional, and is used as default if omitted.
3862
3863 **Example response**:
3864
3865 ```
3866 HTTP/1.1 200 OK
3867 Content-Length: 0
3868 Content-Type: text/plain; charset=utf-8
3869 ```
3870
3871 **Status codes**:
3872
3873 -   **200** - no error
3874 -   **404** - plugin not installed
3875 -   **500** - plugin is active
3876
3877 <!-- TODO Document "docker plugin push" endpoint once we have "plugin build"
3878
3879 #### Push a plugin
3880
3881 `POST /v1.24/plugins/tiborvass/(plugin name)/push HTTP/1.1`
3882
3883 Pushes a plugin to the registry.
3884
3885 **Example request**:
3886
3887 ```
3888 POST /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1
3889 ```
3890
3891 The `:latest` tag is optional, and is used as default if omitted. When using
3892 this endpoint to push a plugin to the registry, the `X-Registry-Auth` header
3893 can be used to include a base64-encoded AuthConfig object. Refer to the [create
3894 an image](#create-an-image) section for more details.
3895
3896 **Example response**:
3897
3898 **Status codes**:
3899
3900 -   **200** - no error
3901 -   **404** - plugin not installed
3902
3903 -->
3904
3905 ### 3.7 Nodes
3906
3907 **Note**: Node operations require the engine to be part of a swarm.
3908
3909 #### List nodes
3910
3911
3912 `GET /nodes`
3913
3914 List nodes
3915
3916 **Example request**:
3917
3918     GET /v1.24/nodes HTTP/1.1
3919
3920 **Example response**:
3921
3922     HTTP/1.1 200 OK
3923     Content-Type: application/json
3924
3925     [
3926       {
3927         "ID": "24ifsmvkjbyhk",
3928         "Version": {
3929           "Index": 8
3930         },
3931         "CreatedAt": "2016-06-07T20:31:11.853781916Z",
3932         "UpdatedAt": "2016-06-07T20:31:11.999868824Z",
3933         "Spec": {
3934           "Name": "my-node",
3935           "Role": "manager",
3936           "Availability": "active"
3937           "Labels": {
3938               "foo": "bar"
3939           }
3940         },
3941         "Description": {
3942           "Hostname": "bf3067039e47",
3943           "Platform": {
3944             "Architecture": "x86_64",
3945             "OS": "linux"
3946           },
3947           "Resources": {
3948             "NanoCPUs": 4000000000,
3949             "MemoryBytes": 8272408576
3950           },
3951           "Engine": {
3952             "EngineVersion": "1.12.0",
3953             "Labels": {
3954                 "foo": "bar",
3955             }
3956             "Plugins": [
3957               {
3958                 "Type": "Volume",
3959                 "Name": "local"
3960               },
3961               {
3962                 "Type": "Network",
3963                 "Name": "bridge"
3964               }
3965               {
3966                 "Type": "Network",
3967                 "Name": "null"
3968               }
3969               {
3970                 "Type": "Network",
3971                 "Name": "overlay"
3972               }
3973             ]
3974           }
3975         },
3976         "Status": {
3977           "State": "ready"
3978         },
3979         "ManagerStatus": {
3980           "Leader": true,
3981           "Reachability": "reachable",
3982           "Addr": "172.17.0.2:2377""
3983         }
3984       }
3985     ]
3986
3987 **Query parameters**:
3988
3989 - **filters** – a JSON encoded value of the filters (a `map[string][]string`) to process on the
3990   nodes list. Available filters:
3991   - `id=<node id>`
3992   - `label=<engine label>`
3993   - `membership=`(`accepted`|`pending`)`
3994   - `name=<node name>`
3995   - `role=`(`manager`|`worker`)`
3996
3997 **Status codes**:
3998
3999 -   **200** – no error
4000 -   **406** - node is not part of a swarm
4001 -   **500** – server error
4002
4003 #### Inspect a node
4004
4005
4006 `GET /nodes/(id or name)`
4007
4008 Return low-level information on the node `id`
4009
4010 **Example request**:
4011
4012       GET /v1.24/nodes/24ifsmvkjbyhk HTTP/1.1
4013
4014 **Example response**:
4015
4016     HTTP/1.1 200 OK
4017     Content-Type: application/json
4018
4019     {
4020       "ID": "24ifsmvkjbyhk",
4021       "Version": {
4022         "Index": 8
4023       },
4024       "CreatedAt": "2016-06-07T20:31:11.853781916Z",
4025       "UpdatedAt": "2016-06-07T20:31:11.999868824Z",
4026       "Spec": {
4027         "Name": "my-node",
4028         "Role": "manager",
4029         "Availability": "active"
4030         "Labels": {
4031             "foo": "bar"
4032         }
4033       },
4034       "Description": {
4035         "Hostname": "bf3067039e47",
4036         "Platform": {
4037           "Architecture": "x86_64",
4038           "OS": "linux"
4039         },
4040         "Resources": {
4041           "NanoCPUs": 4000000000,
4042           "MemoryBytes": 8272408576
4043         },
4044         "Engine": {
4045           "EngineVersion": "1.12.0",
4046           "Labels": {
4047               "foo": "bar",
4048           }
4049           "Plugins": [
4050             {
4051               "Type": "Volume",
4052               "Name": "local"
4053             },
4054             {
4055               "Type": "Network",
4056               "Name": "bridge"
4057             }
4058             {
4059               "Type": "Network",
4060               "Name": "null"
4061             }
4062             {
4063               "Type": "Network",
4064               "Name": "overlay"
4065             }
4066           ]
4067         }
4068       },
4069       "Status": {
4070         "State": "ready"
4071       },
4072       "ManagerStatus": {
4073         "Leader": true,
4074         "Reachability": "reachable",
4075         "Addr": "172.17.0.2:2377""
4076       }
4077     }
4078
4079 **Status codes**:
4080
4081 -   **200** – no error
4082 -   **404** – no such node
4083 -   **406** – node is not part of a swarm
4084 -   **500** – server error
4085
4086 #### Remove a node
4087
4088
4089 `DELETE /nodes/(id or name)`
4090
4091 Remove a node from the swarm.
4092
4093 **Example request**:
4094
4095     DELETE /v1.24/nodes/24ifsmvkjbyhk HTTP/1.1
4096
4097 **Example response**:
4098
4099     HTTP/1.1 200 OK
4100     Content-Length: 0
4101     Content-Type: text/plain; charset=utf-8
4102
4103 **Query parameters**:
4104
4105 -   **force** - 1/True/true or 0/False/false, Force remove a node from the swarm.
4106         Default `false`.
4107
4108 **Status codes**:
4109
4110 -   **200** – no error
4111 -   **404** – no such node
4112 -   **406** – node is not part of a swarm
4113 -   **500** – server error
4114
4115 #### Update a node
4116
4117
4118 `POST /nodes/(id)/update`
4119
4120 Update a node.
4121
4122 The payload of the `POST` request is the new `NodeSpec` and
4123 overrides the current `NodeSpec` for the specified node.
4124
4125 If `Availability` or `Role` are omitted, this returns an
4126 error. Any other field omitted resets the current value to either
4127 an empty value or the default cluster-wide value.
4128
4129 **Example Request**
4130
4131     POST /v1.24/nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1
4132     Content-Type: application/json
4133
4134     {
4135       "Availability": "active",
4136       "Name": "node-name",
4137       "Role": "manager",
4138       "Labels": {
4139         "foo": "bar"
4140       }
4141     }
4142
4143 **Example response**:
4144
4145     HTTP/1.1 200 OK
4146     Content-Length: 0
4147     Content-Type: text/plain; charset=utf-8
4148
4149 **Query parameters**:
4150
4151 - **version** – The version number of the node object being updated. This is
4152   required to avoid conflicting writes.
4153
4154 JSON Parameters:
4155
4156 - **Annotations** – Optional medata to associate with the node.
4157     - **Name** – User-defined name for the node.
4158     - **Labels** – A map of labels to associate with the node (e.g.,
4159       `{"key":"value", "key2":"value2"}`).
4160 - **Role** - Role of the node (worker|manager).
4161 - **Availability** - Availability of the node (active|pause|drain).
4162
4163
4164 **Status codes**:
4165
4166 -   **200** – no error
4167 -   **404** – no such node
4168 -   **406** – node is not part of a swarm
4169 -   **500** – server error
4170
4171 ### 3.8 Swarm
4172
4173 #### Inspect swarm
4174
4175
4176 `GET /swarm`
4177
4178 Inspect swarm
4179
4180 **Example response**:
4181
4182     HTTP/1.1 200 OK
4183     Content-Type: application/json
4184
4185     {
4186       "CreatedAt" : "2016-08-15T16:00:20.349727406Z",
4187       "Spec" : {
4188         "Dispatcher" : {
4189           "HeartbeatPeriod" : 5000000000
4190         },
4191         "Orchestration" : {
4192          "TaskHistoryRetentionLimit" : 10
4193         },
4194         "CAConfig" : {
4195           "NodeCertExpiry" : 7776000000000000
4196         },
4197         "Raft" : {
4198           "LogEntriesForSlowFollowers" : 500,
4199           "HeartbeatTick" : 1,
4200           "SnapshotInterval" : 10000,
4201           "ElectionTick" : 3
4202         },
4203         "TaskDefaults" : {},
4204         "Name" : "default"
4205       },
4206      "JoinTokens" : {
4207         "Worker" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-6qmn92w6bu3jdvnglku58u11a",
4208         "Manager" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-8llk83c4wm9lwioey2s316r9l"
4209      },
4210      "ID" : "70ilmkj2f6sp2137c753w2nmt",
4211      "UpdatedAt" : "2016-08-15T16:32:09.623207604Z",
4212      "Version" : {
4213        "Index" : 51
4214     }
4215   }
4216
4217 **Status codes**:
4218
4219 -   **200** - no error
4220 -   **406** – node is not part of a swarm
4221 -   **500** - sever error
4222
4223 #### Initialize a new swarm
4224
4225
4226 `POST /swarm/init`
4227
4228 Initialize a new swarm. The body of the HTTP response includes the node ID.
4229
4230 **Example request**:
4231
4232     POST /v1.24/swarm/init HTTP/1.1
4233     Content-Type: application/json
4234
4235     {
4236       "ListenAddr": "0.0.0.0:2377",
4237       "AdvertiseAddr": "192.168.1.1:2377",
4238       "ForceNewCluster": false,
4239       "Spec": {
4240         "Orchestration": {},
4241         "Raft": {},
4242         "Dispatcher": {},
4243         "CAConfig": {}
4244       }
4245     }
4246
4247 **Example response**:
4248
4249     HTTP/1.1 200 OK
4250     Content-Length: 28
4251     Content-Type: application/json
4252     Date: Thu, 01 Sep 2016 21:49:13 GMT
4253     Server: Docker/1.12.0 (linux)
4254
4255     "7v2t30z9blmxuhnyo6s4cpenp"
4256
4257 **Status codes**:
4258
4259 -   **200** – no error
4260 -   **400** – bad parameter
4261 -   **406** – node is already part of a swarm
4262 -   **500** - server error
4263
4264 JSON Parameters:
4265
4266 - **ListenAddr** – Listen address used for inter-manager communication, as well as determining
4267   the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an
4268   address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port
4269   number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is
4270   used.
4271 - **AdvertiseAddr** – Externally reachable address advertised to other nodes. This can either be
4272   an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port
4273   number, like `eth0:4567`. If the port number is omitted, the port number from the listen
4274   address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when
4275   possible.
4276 - **ForceNewCluster** – Force creation of a new swarm.
4277 - **Spec** – Configuration settings for the new swarm.
4278     - **Orchestration** – Configuration settings for the orchestration aspects of the swarm.
4279         - **TaskHistoryRetentionLimit** – Maximum number of tasks history stored.
4280     - **Raft** – Raft related configuration.
4281         - **SnapshotInterval** – Number of logs entries between snapshot.
4282         - **KeepOldSnapshots** – Number of snapshots to keep beyond the current snapshot.
4283         - **LogEntriesForSlowFollowers** – Number of log entries to keep around to sync up slow
4284           followers after a snapshot is created.
4285         - **HeartbeatTick** – Amount of ticks (in seconds) between each heartbeat.
4286         - **ElectionTick** – Amount of ticks (in seconds) needed without a leader to trigger a new
4287           election.
4288     - **Dispatcher** – Configuration settings for the task dispatcher.
4289         - **HeartbeatPeriod** – The delay for an agent to send a heartbeat to the dispatcher.
4290     - **CAConfig** – Certificate authority configuration.
4291         - **NodeCertExpiry** – Automatic expiry for nodes certificates.
4292         - **ExternalCA** - Configuration for forwarding signing requests to an external
4293           certificate authority.
4294             - **Protocol** - Protocol for communication with the external CA
4295               (currently only "cfssl" is supported).
4296             - **URL** - URL where certificate signing requests should be sent.
4297             - **Options** - An object with key/value pairs that are interpreted
4298               as protocol-specific options for the external CA driver.
4299
4300 #### Join an existing swarm
4301
4302 `POST /swarm/join`
4303
4304 Join an existing swarm
4305
4306 **Example request**:
4307
4308     POST /v1.24/swarm/join HTTP/1.1
4309     Content-Type: application/json
4310
4311     {
4312       "ListenAddr": "0.0.0.0:2377",
4313       "AdvertiseAddr": "192.168.1.1:2377",
4314       "RemoteAddrs": ["node1:2377"],
4315       "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
4316     }
4317
4318 **Example response**:
4319
4320     HTTP/1.1 200 OK
4321     Content-Length: 0
4322     Content-Type: text/plain; charset=utf-8
4323
4324 **Status codes**:
4325
4326 -   **200** – no error
4327 -   **400** – bad parameter
4328 -   **406** – node is already part of a swarm
4329 -   **500** - server error
4330
4331 JSON Parameters:
4332
4333 - **ListenAddr** – Listen address used for inter-manager communication if the node gets promoted to
4334   manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).
4335 - **AdvertiseAddr** – Externally reachable address advertised to other nodes. This can either be
4336   an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port
4337   number, like `eth0:4567`. If the port number is omitted, the port number from the listen
4338   address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when
4339   possible.
4340 - **RemoteAddr** – Address of any manager node already participating in the swarm.
4341 - **JoinToken** – Secret token for joining this swarm.
4342
4343 #### Leave a swarm
4344
4345
4346 `POST /swarm/leave`
4347
4348 Leave a swarm
4349
4350 **Example request**:
4351
4352     POST /v1.24/swarm/leave HTTP/1.1
4353
4354 **Example response**:
4355
4356     HTTP/1.1 200 OK
4357     Content-Length: 0
4358     Content-Type: text/plain; charset=utf-8
4359
4360 **Query parameters**:
4361
4362 - **force** - Boolean (0/1, false/true). Force leave swarm, even if this is the last manager or that it will break the cluster.
4363
4364 **Status codes**:
4365
4366 -  **200** – no error
4367 -  **406** – node is not part of a swarm
4368 -  **500** - server error
4369
4370 #### Update a swarm
4371
4372
4373 `POST /swarm/update`
4374
4375 Update a swarm
4376
4377 **Example request**:
4378
4379     POST /v1.24/swarm/update HTTP/1.1
4380
4381     {
4382       "Name": "default",
4383       "Orchestration": {
4384         "TaskHistoryRetentionLimit": 10
4385       },
4386       "Raft": {
4387         "SnapshotInterval": 10000,
4388         "LogEntriesForSlowFollowers": 500,
4389         "HeartbeatTick": 1,
4390         "ElectionTick": 3
4391       },
4392       "Dispatcher": {
4393         "HeartbeatPeriod": 5000000000
4394       },
4395       "CAConfig": {
4396         "NodeCertExpiry": 7776000000000000
4397       },
4398       "JoinTokens": {
4399         "Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
4400         "Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
4401       }
4402     }
4403
4404
4405 **Example response**:
4406
4407     HTTP/1.1 200 OK
4408     Content-Length: 0
4409     Content-Type: text/plain; charset=utf-8
4410
4411 **Query parameters**:
4412
4413 - **version** – The version number of the swarm object being updated. This is
4414   required to avoid conflicting writes.
4415 - **rotateWorkerToken** - Set to `true` (or `1`) to rotate the worker join token.
4416 - **rotateManagerToken** - Set to `true` (or `1`) to rotate the manager join token.
4417
4418 **Status codes**:
4419
4420 -   **200** – no error
4421 -   **400** – bad parameter
4422 -   **406** – node is not part of a swarm
4423 -   **500** - server error
4424
4425 JSON Parameters:
4426
4427 - **Orchestration** – Configuration settings for the orchestration aspects of the swarm.
4428     - **TaskHistoryRetentionLimit** – Maximum number of tasks history stored.
4429 - **Raft** – Raft related configuration.
4430     - **SnapshotInterval** – Number of logs entries between snapshot.
4431     - **KeepOldSnapshots** – Number of snapshots to keep beyond the current snapshot.
4432     - **LogEntriesForSlowFollowers** – Number of log entries to keep around to sync up slow
4433       followers after a snapshot is created.
4434     - **HeartbeatTick** – Amount of ticks (in seconds) between each heartbeat.
4435     - **ElectionTick** – Amount of ticks (in seconds) needed without a leader to trigger a new
4436       election.
4437 - **Dispatcher** – Configuration settings for the task dispatcher.
4438     - **HeartbeatPeriod** – The delay for an agent to send a heartbeat to the dispatcher.
4439 - **CAConfig** – CA configuration.
4440     - **NodeCertExpiry** – Automatic expiry for nodes certificates.
4441     - **ExternalCA** - Configuration for forwarding signing requests to an external
4442       certificate authority.
4443         - **Protocol** - Protocol for communication with the external CA
4444           (currently only "cfssl" is supported).
4445         - **URL** - URL where certificate signing requests should be sent.
4446         - **Options** - An object with key/value pairs that are interpreted
4447           as protocol-specific options for the external CA driver.
4448 - **JoinTokens** - Tokens that can be used by other nodes to join the swarm.
4449     - **Worker** - Token to use for joining as a worker.
4450     - **Manager** - Token to use for joining as a manager.
4451
4452 ### 3.9 Services
4453
4454 **Note**: Service operations require to first be part of a swarm.
4455
4456 #### List services
4457
4458
4459 `GET /services`
4460
4461 List services
4462
4463 **Example request**:
4464
4465     GET /v1.24/services HTTP/1.1
4466
4467 **Example response**:
4468
4469     HTTP/1.1 200 OK
4470     Content-Type: application/json
4471
4472     [
4473       {
4474         "ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
4475         "Version": {
4476           "Index": 19
4477         },
4478         "CreatedAt": "2016-06-07T21:05:51.880065305Z",
4479         "UpdatedAt": "2016-06-07T21:07:29.962229872Z",
4480         "Spec": {
4481           "Name": "hopeful_cori",
4482           "TaskTemplate": {
4483             "ContainerSpec": {
4484               "Image": "redis"
4485             },
4486             "Resources": {
4487               "Limits": {},
4488               "Reservations": {}
4489             },
4490             "RestartPolicy": {
4491               "Condition": "any",
4492               "MaxAttempts": 0
4493             },
4494             "Placement": {
4495               "Constraints": [
4496                 "node.role == worker"
4497               ]
4498             }
4499           },
4500           "Mode": {
4501             "Replicated": {
4502               "Replicas": 1
4503             }
4504           },
4505           "UpdateConfig": {
4506             "Parallelism": 1,
4507             "FailureAction": "pause"
4508           },
4509           "EndpointSpec": {
4510             "Mode": "vip",
4511             "Ports": [
4512               {
4513                 "Protocol": "tcp",
4514                 "TargetPort": 6379,
4515                 "PublishedPort": 30001
4516               }
4517             ]
4518           }
4519         },
4520         "Endpoint": {
4521           "Spec": {
4522             "Mode": "vip",
4523             "Ports": [
4524               {
4525                 "Protocol": "tcp",
4526                 "TargetPort": 6379,
4527                 "PublishedPort": 30001
4528               }
4529             ]
4530           },
4531           "Ports": [
4532             {
4533               "Protocol": "tcp",
4534               "TargetPort": 6379,
4535               "PublishedPort": 30001
4536             }
4537           ],
4538           "VirtualIPs": [
4539             {
4540               "NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
4541               "Addr": "10.255.0.2/16"
4542             },
4543             {
4544               "NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
4545               "Addr": "10.255.0.3/16"
4546             }
4547           ]
4548         }
4549       }
4550     ]
4551
4552 **Query parameters**:
4553
4554 - **filters** – a JSON encoded value of the filters (a `map[string][]string`) to process on the
4555   services list. Available filters:
4556   - `id=<service id>`
4557   - `label=<service label>`
4558   - `name=<service name>`
4559
4560 **Status codes**:
4561
4562 -   **200** – no error
4563 -   **406** – node is not part of a swarm
4564 -   **500** – server error
4565
4566 #### Create a service
4567
4568 `POST /services/create`
4569
4570 Create a service. When using this endpoint to create a service using a private
4571 repository from the registry, the `X-Registry-Auth` header must be used to
4572 include a base64-encoded AuthConfig object. Refer to the [create an
4573 image](#create-an-image) section for more details.
4574
4575 **Example request**:
4576
4577     POST /v1.24/services/create HTTP/1.1
4578     Content-Type: application/json
4579
4580     {
4581       "Name": "web",
4582       "TaskTemplate": {
4583         "ContainerSpec": {
4584           "Image": "nginx:alpine",
4585           "Mounts": [
4586             {
4587               "ReadOnly": true,
4588               "Source": "web-data",
4589               "Target": "/usr/share/nginx/html",
4590               "Type": "volume",
4591               "VolumeOptions": {
4592                 "DriverConfig": {
4593                 },
4594                 "Labels": {
4595                   "com.example.something": "something-value"
4596                 }
4597               }
4598             }
4599           ],
4600           "User": "33"
4601         },
4602         "Networks": [
4603             {
4604               "Target": "overlay1"
4605             }
4606         ],
4607         "LogDriver": {
4608           "Name": "json-file",
4609           "Options": {
4610             "max-file": "3",
4611             "max-size": "10M"
4612           }
4613         },
4614         "Placement": {
4615           "Constraints": [
4616             "node.role == worker"
4617           ]
4618         },
4619         "Resources": {
4620           "Limits": {
4621             "MemoryBytes": 104857600
4622           },
4623           "Reservations": {
4624           }
4625         },
4626         "RestartPolicy": {
4627           "Condition": "on-failure",
4628           "Delay": 10000000000,
4629           "MaxAttempts": 10
4630         }
4631       },
4632       "Mode": {
4633         "Replicated": {
4634           "Replicas": 4
4635         }
4636       },
4637       "UpdateConfig": {
4638         "Delay": 30000000000,
4639         "Parallelism": 2,
4640         "FailureAction": "pause"
4641       },
4642       "EndpointSpec": {
4643         "Ports": [
4644           {
4645             "Protocol": "tcp",
4646             "PublishedPort": 8080,
4647             "TargetPort": 80
4648           }
4649         ]
4650       },
4651       "Labels": {
4652         "foo": "bar"
4653       }
4654     }
4655
4656 **Example response**:
4657
4658     HTTP/1.1 201 Created
4659     Content-Type: application/json
4660
4661     {
4662       "ID":"ak7w3gjqoa3kuz8xcpnyy0pvl"
4663     }
4664
4665 **Status codes**:
4666
4667 -   **201** – no error
4668 -   **403** - network is not eligible for services
4669 -   **406** – node is not part of a swarm
4670 -   **409** – name conflicts with an existing object
4671 -   **500** - server error
4672
4673 **JSON Parameters**:
4674
4675 - **Name** – User-defined name for the service.
4676 - **Labels** – A map of labels to associate with the service (e.g., `{"key":"value", "key2":"value2"}`).
4677 - **TaskTemplate** – Specification of the tasks to start as part of the new service.
4678     - **ContainerSpec** - Container settings for containers started as part of this task.
4679         - **Image** – A string specifying the image name to use for the container.
4680         - **Command** – The command to be run in the image.
4681         - **Args** – Arguments to the command.
4682         - **Env** – A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`.
4683         - **Dir** – A string specifying the working directory for commands to run in.
4684         - **User** – A string value specifying the user inside the container.
4685         - **Labels** – A map of labels to associate with the service (e.g.,
4686           `{"key":"value", "key2":"value2"}`).
4687         - **Mounts** – Specification for mounts to be added to containers
4688           created as part of the service.
4689             - **Target** – Container path.
4690             - **Source** – Mount source (e.g. a volume name, a host path).
4691             - **Type** – The mount type (`bind`, or `volume`).
4692             - **ReadOnly** – A boolean indicating whether the mount should be read-only.
4693             - **BindOptions** - Optional configuration for the `bind` type.
4694               - **Propagation** – A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`.
4695             - **VolumeOptions** – Optional configuration for the `volume` type.
4696                 - **NoCopy** – A boolean indicating if volume should be
4697                   populated with the data from the target. (Default false)
4698                 - **Labels** – User-defined name and labels for the volume.
4699                 - **DriverConfig** – Map of driver-specific options.
4700                   - **Name** - Name of the driver to use to create the volume.
4701                   - **Options** - key/value map of driver specific options.
4702         - **StopGracePeriod** – Amount of time to wait for the container to terminate before
4703           forcefully killing it.
4704     - **LogDriver** - Log configuration for containers created as part of the
4705       service.
4706         - **Name** - Name of the logging driver to use (`json-file`, `syslog`,
4707           `journald`, `gelf`, `fluentd`, `awslogs`, `splunk`, `etwlogs`, `none`).
4708         - **Options** - Driver-specific options.
4709     - **Resources** – Resource requirements which apply to each individual container created as part
4710       of the service.
4711         - **Limits** – Define resources limits.
4712             - **NanoCPUs** – CPU limit in units of 10<sup>-9</sup> CPU shares.
4713             - **MemoryBytes** – Memory limit in Bytes.
4714         - **Reservation** – Define resources reservation.
4715             - **NanoCPUs** – CPU reservation in units of 10<sup>-9</sup> CPU shares.
4716             - **MemoryBytes** – Memory reservation in Bytes.
4717     - **RestartPolicy** – Specification for the restart policy which applies to containers created
4718       as part of this service.
4719         - **Condition** – Condition for restart (`none`, `on-failure`, or `any`).
4720         - **Delay** – Delay between restart attempts.
4721         - **MaxAttempts** – Maximum attempts to restart a given container before giving up (default value
4722           is 0, which is ignored).
4723         - **Window** – Windows is the time window used to evaluate the restart policy (default value is
4724           0, which is unbounded).
4725     - **Placement** – Restrictions on where a service can run.
4726         - **Constraints** – An array of constraints, e.g. `[ "node.role == manager" ]`.
4727 - **Mode** – Scheduling mode for the service (`replicated` or `global`, defaults to `replicated`).
4728 - **UpdateConfig** – Specification for the update strategy of the service.
4729     - **Parallelism** – Maximum number of tasks to be updated in one iteration (0 means unlimited
4730       parallelism).
4731     - **Delay** – Amount of time between updates.
4732     - **FailureAction** - Action to take if an updated task fails to run, or stops running during the
4733       update. Values are `continue` and `pause`.
4734 - **Networks** – Array of network names or IDs to attach the service to.
4735 - **EndpointSpec** – Properties that can be configured to access and load balance a service.
4736     - **Mode** – The mode of resolution to use for internal load balancing
4737       between tasks (`vip` or `dnsrr`). Defaults to `vip` if not provided.
4738     - **Ports** – List of exposed ports that this service is accessible on from
4739       the outside, in the form of:
4740       `{"Protocol": <"tcp"|"udp">, "PublishedPort": <port>, "TargetPort": <port>}`.
4741       Ports can only be provided if `vip` resolution mode is used.
4742
4743 **Request Headers**:
4744
4745 - **Content-type** – Set to `"application/json"`.
4746 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either
4747   login information, or a token. Refer to the [create an image](#create-an-image)
4748   section for more details.
4749
4750
4751 #### Remove a service
4752
4753
4754 `DELETE /services/(id or name)`
4755
4756 Stop and remove the service `id`
4757
4758 **Example request**:
4759
4760     DELETE /v1.24/services/16253994b7c4 HTTP/1.1
4761
4762 **Example response**:
4763
4764     HTTP/1.1 200 OK
4765     Content-Length: 0
4766     Content-Type: text/plain; charset=utf-8
4767
4768 **Status codes**:
4769
4770 -   **200** – no error
4771 -   **404** – no such service
4772 -   **406** - node is not part of a swarm
4773 -   **500** – server error
4774
4775 #### Inspect one or more services
4776
4777
4778 `GET /services/(id or name)`
4779
4780 Return information on the service `id`.
4781
4782 **Example request**:
4783
4784     GET /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha HTTP/1.1
4785
4786 **Example response**:
4787
4788     {
4789       "ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
4790       "Version": {
4791         "Index": 95
4792       },
4793       "CreatedAt": "2016-06-07T21:10:20.269723157Z",
4794       "UpdatedAt": "2016-06-07T21:10:20.276301259Z",
4795       "Spec": {
4796         "Name": "redis",
4797         "TaskTemplate": {
4798           "ContainerSpec": {
4799             "Image": "redis"
4800           },
4801           "Resources": {
4802             "Limits": {},
4803             "Reservations": {}
4804           },
4805           "RestartPolicy": {
4806             "Condition": "any",
4807             "MaxAttempts": 0
4808           },
4809           "Placement": {}
4810         },
4811         "Mode": {
4812           "Replicated": {
4813             "Replicas": 1
4814           }
4815         },
4816         "UpdateConfig": {
4817           "Parallelism": 1,
4818           "FailureAction": "pause"
4819         },
4820         "EndpointSpec": {
4821           "Mode": "vip",
4822           "Ports": [
4823             {
4824               "Protocol": "tcp",
4825               "TargetPort": 6379,
4826               "PublishedPort": 30001
4827             }
4828           ]
4829         }
4830       },
4831       "Endpoint": {
4832         "Spec": {
4833           "Mode": "vip",
4834           "Ports": [
4835             {
4836               "Protocol": "tcp",
4837               "TargetPort": 6379,
4838               "PublishedPort": 30001
4839             }
4840           ]
4841         },
4842         "Ports": [
4843           {
4844             "Protocol": "tcp",
4845             "TargetPort": 6379,
4846             "PublishedPort": 30001
4847           }
4848         ],
4849         "VirtualIPs": [
4850           {
4851             "NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
4852             "Addr": "10.255.0.4/16"
4853           }
4854         ]
4855       }
4856     }
4857
4858 **Status codes**:
4859
4860 -   **200** – no error
4861 -   **404** – no such service
4862 -   **406** - node is not part of a swarm
4863 -   **500** – server error
4864
4865 #### Update a service
4866
4867 `POST /services/(id)/update`
4868
4869 Update a service. When using this endpoint to create a service using a
4870 private repository from the registry, the `X-Registry-Auth` header can be used
4871 to update the authentication information for that is stored for the service.
4872 The header contains a base64-encoded AuthConfig object. Refer to the [create an
4873 image](#create-an-image) section for more details.
4874
4875 **Example request**:
4876
4877     POST /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha/update?version=23 HTTP/1.1
4878     Content-Type: application/json
4879
4880     {
4881       "Name": "top",
4882       "TaskTemplate": {
4883         "ContainerSpec": {
4884           "Image": "busybox",
4885           "Args": [
4886             "top"
4887           ]
4888         },
4889         "Resources": {
4890           "Limits": {},
4891           "Reservations": {}
4892         },
4893         "RestartPolicy": {
4894           "Condition": "any",
4895           "MaxAttempts": 0
4896         },
4897         "Placement": {}
4898       },
4899       "Mode": {
4900         "Replicated": {
4901           "Replicas": 1
4902         }
4903       },
4904       "UpdateConfig": {
4905         "Parallelism": 1
4906       },
4907       "EndpointSpec": {
4908         "Mode": "vip"
4909       }
4910     }
4911
4912 **Example response**:
4913
4914     HTTP/1.1 200 OK
4915     Content-Length: 0
4916     Content-Type: text/plain; charset=utf-8
4917
4918 **JSON Parameters**:
4919
4920 - **Name** – User-defined name for the service. Note that renaming services is not supported.
4921 - **Labels** – A map of labels to associate with the service (e.g., `{"key":"value", "key2":"value2"}`).
4922 - **TaskTemplate** – Specification of the tasks to start as part of the new service.
4923     - **ContainerSpec** - Container settings for containers started as part of this task.
4924         - **Image** – A string specifying the image name to use for the container.
4925         - **Command** – The command to be run in the image.
4926         - **Args** – Arguments to the command.
4927         - **Env** – A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`.
4928         - **Dir** – A string specifying the working directory for commands to run in.
4929         - **User** – A string value specifying the user inside the container.
4930         - **Labels** – A map of labels to associate with the service (e.g.,
4931           `{"key":"value", "key2":"value2"}`).
4932         - **Mounts** – Specification for mounts to be added to containers created as part of the new
4933           service.
4934             - **Target** – Container path.
4935             - **Source** – Mount source (e.g. a volume name, a host path).
4936             - **Type** – The mount type (`bind`, or `volume`).
4937             - **ReadOnly** – A boolean indicating whether the mount should be read-only.
4938             - **BindOptions** - Optional configuration for the `bind` type
4939               - **Propagation** – A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`.
4940             - **VolumeOptions** – Optional configuration for the `volume` type.
4941                 - **NoCopy** – A boolean indicating if volume should be
4942                   populated with the data from the target. (Default false)
4943                 - **Labels** – User-defined name and labels for the volume.
4944                 - **DriverConfig** – Map of driver-specific options.
4945                   - **Name** - Name of the driver to use to create the volume
4946                   - **Options** - key/value map of driver specific options
4947         - **StopGracePeriod** – Amount of time to wait for the container to terminate before
4948           forcefully killing it.
4949     - **Resources** – Resource requirements which apply to each individual container created as part
4950       of the service.
4951         - **Limits** – Define resources limits.
4952             - **CPU** – CPU limit
4953             - **Memory** – Memory limit
4954         - **Reservation** – Define resources reservation.
4955             - **CPU** – CPU reservation
4956             - **Memory** – Memory reservation
4957     - **RestartPolicy** – Specification for the restart policy which applies to containers created
4958       as part of this service.
4959         - **Condition** – Condition for restart (`none`, `on-failure`, or `any`).
4960         - **Delay** – Delay between restart attempts.
4961         - **MaxAttempts** – Maximum attempts to restart a given container before giving up (default value
4962           is 0, which is ignored).
4963         - **Window** – Windows is the time window used to evaluate the restart policy (default value is
4964           0, which is unbounded).
4965     - **Placement** – Restrictions on where a service can run.
4966         - **Constraints** – An array of constraints, e.g. `[ "node.role == manager" ]`.
4967 - **Mode** – Scheduling mode for the service (`replicated` or `global`, defaults to `replicated`).
4968 - **UpdateConfig** – Specification for the update strategy of the service.
4969     - **Parallelism** – Maximum number of tasks to be updated in one iteration (0 means unlimited
4970       parallelism).
4971     - **Delay** – Amount of time between updates.
4972 - **Networks** – Array of network names or IDs to attach the service to.
4973 - **EndpointSpec** – Properties that can be configured to access and load balance a service.
4974     - **Mode** – The mode of resolution to use for internal load balancing
4975       between tasks (`vip` or `dnsrr`). Defaults to `vip` if not provided.
4976     - **Ports** – List of exposed ports that this service is accessible on from
4977       the outside, in the form of:
4978       `{"Protocol": <"tcp"|"udp">, "PublishedPort": <port>, "TargetPort": <port>}`.
4979       Ports can only be provided if `vip` resolution mode is used.
4980
4981 **Query parameters**:
4982
4983 - **version** – The version number of the service object being updated. This is
4984   required to avoid conflicting writes.
4985
4986 **Request Headers**:
4987
4988 - **Content-type** – Set to `"application/json"`.
4989 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either
4990   login information, or a token. Refer to the [create an image](#create-an-image)
4991   section for more details.
4992
4993 **Status codes**:
4994
4995 -   **200** – no error
4996 -   **404** – no such service
4997 -   **406** - node is not part of a swarm
4998 -   **500** – server error
4999
5000 ### 3.10 Tasks
5001
5002 **Note**: Task operations require the engine to be part of a swarm.
5003
5004 #### List tasks
5005
5006
5007 `GET /tasks`
5008
5009 List tasks
5010
5011 **Example request**:
5012
5013     GET /v1.24/tasks HTTP/1.1
5014
5015 **Example response**:
5016
5017     [
5018       {
5019         "ID": "0kzzo1i0y4jz6027t0k7aezc7",
5020         "Version": {
5021           "Index": 71
5022         },
5023         "CreatedAt": "2016-06-07T21:07:31.171892745Z",
5024         "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
5025         "Spec": {
5026           "ContainerSpec": {
5027             "Image": "redis"
5028           },
5029           "Resources": {
5030             "Limits": {},
5031             "Reservations": {}
5032           },
5033           "RestartPolicy": {
5034             "Condition": "any",
5035             "MaxAttempts": 0
5036           },
5037           "Placement": {}
5038         },
5039         "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
5040         "Slot": 1,
5041         "NodeID": "60gvrl6tm78dmak4yl7srz94v",
5042         "Status": {
5043           "Timestamp": "2016-06-07T21:07:31.290032978Z",
5044           "State": "running",
5045           "Message": "started",
5046           "ContainerStatus": {
5047             "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
5048             "PID": 677
5049           }
5050         },
5051         "DesiredState": "running",
5052         "NetworksAttachments": [
5053           {
5054             "Network": {
5055               "ID": "4qvuz4ko70xaltuqbt8956gd1",
5056               "Version": {
5057                 "Index": 18
5058               },
5059               "CreatedAt": "2016-06-07T20:31:11.912919752Z",
5060               "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
5061               "Spec": {
5062                 "Name": "ingress",
5063                 "Labels": {
5064                   "com.docker.swarm.internal": "true"
5065                 },
5066                 "DriverConfiguration": {},
5067                 "IPAMOptions": {
5068                   "Driver": {},
5069                   "Configs": [
5070                     {
5071                       "Subnet": "10.255.0.0/16",
5072                       "Gateway": "10.255.0.1"
5073                     }
5074                   ]
5075                 }
5076               },
5077               "DriverState": {
5078                 "Name": "overlay",
5079                 "Options": {
5080                   "com.docker.network.driver.overlay.vxlanid_list": "256"
5081                 }
5082               },
5083               "IPAMOptions": {
5084                 "Driver": {
5085                   "Name": "default"
5086                 },
5087                 "Configs": [
5088                   {
5089                     "Subnet": "10.255.0.0/16",
5090                     "Gateway": "10.255.0.1"
5091                   }
5092                 ]
5093               }
5094             },
5095             "Addresses": [
5096               "10.255.0.10/16"
5097             ]
5098           }
5099         ],
5100       },
5101       {
5102         "ID": "1yljwbmlr8er2waf8orvqpwms",
5103         "Version": {
5104           "Index": 30
5105         },
5106         "CreatedAt": "2016-06-07T21:07:30.019104782Z",
5107         "UpdatedAt": "2016-06-07T21:07:30.231958098Z",
5108         "Name": "hopeful_cori",
5109         "Spec": {
5110           "ContainerSpec": {
5111             "Image": "redis"
5112           },
5113           "Resources": {
5114             "Limits": {},
5115             "Reservations": {}
5116           },
5117           "RestartPolicy": {
5118             "Condition": "any",
5119             "MaxAttempts": 0
5120           },
5121           "Placement": {}
5122         },
5123         "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
5124         "Slot": 1,
5125         "NodeID": "60gvrl6tm78dmak4yl7srz94v",
5126         "Status": {
5127           "Timestamp": "2016-06-07T21:07:30.202183143Z",
5128           "State": "shutdown",
5129           "Message": "shutdown",
5130           "ContainerStatus": {
5131             "ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
5132           }
5133         },
5134         "DesiredState": "shutdown",
5135         "NetworksAttachments": [
5136           {
5137             "Network": {
5138               "ID": "4qvuz4ko70xaltuqbt8956gd1",
5139               "Version": {
5140                 "Index": 18
5141               },
5142               "CreatedAt": "2016-06-07T20:31:11.912919752Z",
5143               "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
5144               "Spec": {
5145                 "Name": "ingress",
5146                 "Labels": {
5147                   "com.docker.swarm.internal": "true"
5148                 },
5149                 "DriverConfiguration": {},
5150                 "IPAMOptions": {
5151                   "Driver": {},
5152                   "Configs": [
5153                     {
5154                       "Subnet": "10.255.0.0/16",
5155                       "Gateway": "10.255.0.1"
5156                     }
5157                   ]
5158                 }
5159               },
5160               "DriverState": {
5161                 "Name": "overlay",
5162                 "Options": {
5163                   "com.docker.network.driver.overlay.vxlanid_list": "256"
5164                 }
5165               },
5166               "IPAMOptions": {
5167                 "Driver": {
5168                   "Name": "default"
5169                 },
5170                 "Configs": [
5171                   {
5172                     "Subnet": "10.255.0.0/16",
5173                     "Gateway": "10.255.0.1"
5174                   }
5175                 ]
5176               }
5177             },
5178             "Addresses": [
5179               "10.255.0.5/16"
5180             ]
5181           }
5182         ]
5183       }
5184     ]
5185
5186 **Query parameters**:
5187
5188 - **filters** – a JSON encoded value of the filters (a `map[string][]string`) to process on the
5189   services list. Available filters:
5190   - `id=<task id>`
5191   - `name=<task name>`
5192   - `service=<service name>`
5193   - `node=<node id or name>`
5194   - `label=key` or `label="key=value"`
5195   - `desired-state=(running | shutdown | accepted)`
5196
5197 **Status codes**:
5198
5199 -   **200** – no error
5200 -   **406** - node is not part of a swarm
5201 -   **500** – server error
5202
5203 #### Inspect a task
5204
5205
5206 `GET /tasks/(id)`
5207
5208 Get details on the task `id`
5209
5210 **Example request**:
5211
5212     GET /v1.24/tasks/0kzzo1i0y4jz6027t0k7aezc7 HTTP/1.1
5213
5214 **Example response**:
5215
5216     {
5217       "ID": "0kzzo1i0y4jz6027t0k7aezc7",
5218       "Version": {
5219         "Index": 71
5220       },
5221       "CreatedAt": "2016-06-07T21:07:31.171892745Z",
5222       "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
5223       "Spec": {
5224         "ContainerSpec": {
5225           "Image": "redis"
5226         },
5227         "Resources": {
5228           "Limits": {},
5229           "Reservations": {}
5230         },
5231         "RestartPolicy": {
5232           "Condition": "any",
5233           "MaxAttempts": 0
5234         },
5235         "Placement": {}
5236       },
5237       "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
5238       "Slot": 1,
5239       "NodeID": "60gvrl6tm78dmak4yl7srz94v",
5240       "Status": {
5241         "Timestamp": "2016-06-07T21:07:31.290032978Z",
5242         "State": "running",
5243         "Message": "started",
5244         "ContainerStatus": {
5245           "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
5246           "PID": 677
5247         }
5248       },
5249       "DesiredState": "running",
5250       "NetworksAttachments": [
5251         {
5252           "Network": {
5253             "ID": "4qvuz4ko70xaltuqbt8956gd1",
5254             "Version": {
5255               "Index": 18
5256             },
5257             "CreatedAt": "2016-06-07T20:31:11.912919752Z",
5258             "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
5259             "Spec": {
5260               "Name": "ingress",
5261               "Labels": {
5262                 "com.docker.swarm.internal": "true"
5263               },
5264               "DriverConfiguration": {},
5265               "IPAMOptions": {
5266                 "Driver": {},
5267                 "Configs": [
5268                   {
5269                     "Subnet": "10.255.0.0/16",
5270                     "Gateway": "10.255.0.1"
5271                   }
5272                 ]
5273               }
5274             },
5275             "DriverState": {
5276               "Name": "overlay",
5277               "Options": {
5278                 "com.docker.network.driver.overlay.vxlanid_list": "256"
5279               }
5280             },
5281             "IPAMOptions": {
5282               "Driver": {
5283                 "Name": "default"
5284               },
5285               "Configs": [
5286                 {
5287                   "Subnet": "10.255.0.0/16",
5288                   "Gateway": "10.255.0.1"
5289                 }
5290               ]
5291             }
5292           },
5293           "Addresses": [
5294             "10.255.0.10/16"
5295           ]
5296         }
5297       ]
5298     }
5299
5300 **Status codes**:
5301
5302 -   **200** – no error
5303 -   **404** – unknown task
5304 -   **406** - node is not part of a swarm
5305 -   **500** – server error
5306
5307 ## 4. Going further
5308
5309 ### 4.1 Inside `docker run`
5310
5311 As an example, the `docker run` command line makes the following API calls:
5312
5313 - Create the container
5314
5315 - If the status code is 404, it means the image doesn't exist:
5316     - Try to pull it.
5317     - Then, retry to create the container.
5318
5319 - Start the container.
5320
5321 - If you are not in detached mode:
5322 - Attach to the container, using `logs=1` (to have `stdout` and
5323       `stderr` from the container's start) and `stream=1`
5324
5325 - If in detached mode or only `stdin` is attached, display the container's id.
5326
5327 ### 4.2 Hijacking
5328
5329 In this version of the API, `/attach`, uses hijacking to transport `stdin`,
5330 `stdout`, and `stderr` on the same socket.
5331
5332 To hint potential proxies about connection hijacking, Docker client sends
5333 connection upgrade headers similarly to websocket.
5334
5335     Upgrade: tcp
5336     Connection: Upgrade
5337
5338 When Docker daemon detects the `Upgrade` header, it switches its status code
5339 from **200 OK** to **101 UPGRADED** and resends the same headers.
5340
5341
5342 ### 4.3 CORS Requests
5343
5344 To set cross origin requests to the Engine API please give values to
5345 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all,
5346 default or blank means CORS disabled
5347
5348     $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"