docs/api/v1.21.md

   1 ---
   2 title: "Engine API v1.21"
   3 description: "API Documentation for Docker"
   4 keywords: "API, Docker, rcli, REST, documentation"
   5 redirect_from:
   6 - /engine/reference/api/docker_remote_api_v1.21/
   7 - /reference/api/docker_remote_api_v1.21/
   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  - When the client API version is newer than the daemon's, these calls return an HTTP
  27    `400 Bad Request` error message.
  28
  29 ## 2. Endpoints
  30
  31 ### 2.1 Containers
  32
  33 #### List containers
  34
  35 `GET /containers/json`
  36
  37 List containers
  38
  39 **Example request**:
  40
  41     GET /v1.21/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
  42
  43 **Example response**:
  44
  45     HTTP/1.1 200 OK
  46     Content-Type: application/json
  47
  48     [
  49          {
  50                  "Id": "8dfafdbc3a40",
  51                  "Names":["/boring_feynman"],
  52                  "Image": "ubuntu:latest",
  53                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
  54                  "Command": "echo 1",
  55                  "Created": 1367854155,
  56                  "Status": "Exit 0",
  57                  "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
  58                  "Labels": {
  59                          "com.example.vendor": "Acme",
  60                          "com.example.license": "GPL",
  61                          "com.example.version": "1.0"
  62                  },
  63                  "SizeRw": 12288,
  64                  "SizeRootFs": 0
  65          },
  66          {
  67                  "Id": "9cd87474be90",
  68                  "Names":["/coolName"],
  69                  "Image": "ubuntu:latest",
  70                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
  71                  "Command": "echo 222222",
  72                  "Created": 1367854155,
  73                  "Status": "Exit 0",
  74                  "Ports": [],
  75                  "Labels": {},
  76                  "SizeRw": 12288,
  77                  "SizeRootFs": 0
  78          },
  79          {
  80                  "Id": "3176a2479c92",
  81                  "Names":["/sleepy_dog"],
  82                  "Image": "ubuntu:latest",
  83                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
  84                  "Command": "echo 3333333333333333",
  85                  "Created": 1367854154,
  86                  "Status": "Exit 0",
  87                  "Ports":[],
  88                  "Labels": {},
  89                  "SizeRw":12288,
  90                  "SizeRootFs":0
  91          },
  92          {
  93                  "Id": "4cb07b47f9fb",
  94                  "Names":["/running_cat"],
  95                  "Image": "ubuntu:latest",
  96                  "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
  97                  "Command": "echo 444444444444444444444444444444444",
  98                  "Created": 1367854152,
  99                  "Status": "Exit 0",
 100                  "Ports": [],
 101                  "Labels": {},
 102                  "SizeRw": 12288,
 103                  "SizeRootFs": 0
 104          }
 105     ]
 106
 107 **Query parameters**:
 108
 109 -   **all** – 1/True/true or 0/False/false, Show all containers.
 110         Only running containers are shown by default (i.e., this defaults to false)
 111 -   **limit** – Show `limit` last created
 112         containers, include non-running ones.
 113 -   **since** – Show only containers created since Id, include
 114         non-running ones.
 115 -   **before** – Show only containers created before Id, include
 116         non-running ones.
 117 -   **size** – 1/True/true or 0/False/false, Show the containers
 118         sizes
 119 -   **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:
 120   -   `exited=<int>`; -- containers with exit code of  `<int>` ;
 121   -   `status=`(`created`|`restarting`|`running`|`paused`|`exited`)
 122   -   `label=key` or `label="key=value"` of a container label
 123
 124 **Status codes**:
 125
 126 -   **200** – no error
 127 -   **400** – bad parameter
 128 -   **500** – server error
 129
 130 #### Create a container
 131
 132 `POST /containers/create`
 133
 134 Create a container
 135
 136 **Example request**:
 137
 138     POST /v1.21/containers/create HTTP/1.1
 139     Content-Type: application/json
 140
 141     {
 142            "Hostname": "",
 143            "Domainname": "",
 144            "User": "",
 145            "AttachStdin": false,
 146            "AttachStdout": true,
 147            "AttachStderr": true,
 148            "Tty": false,
 149            "OpenStdin": false,
 150            "StdinOnce": false,
 151            "Env": [
 152                    "FOO=bar",
 153                    "BAZ=quux"
 154            ],
 155            "Cmd": [
 156                    "date"
 157            ],
 158            "Entrypoint": null,
 159            "Image": "ubuntu",
 160            "Labels": {
 161                    "com.example.vendor": "Acme",
 162                    "com.example.license": "GPL",
 163                    "com.example.version": "1.0"
 164            },
 165            "Volumes": {
 166              "/volumes/data": {}
 167            },
 168            "WorkingDir": "",
 169            "NetworkDisabled": false,
 170            "MacAddress": "12:34:56:78:9a:bc",
 171            "ExposedPorts": {
 172                    "22/tcp": {}
 173            },
 174            "StopSignal": "SIGTERM",
 175            "HostConfig": {
 176              "Binds": ["/tmp:/tmp"],
 177              "Links": ["redis3:redis"],
 178              "LxcConf": {"lxc.utsname":"docker"},
 179              "Memory": 0,
 180              "MemorySwap": 0,
 181              "MemoryReservation": 0,
 182              "KernelMemory": 0,
 183              "CpuShares": 512,
 184              "CpuPeriod": 100000,
 185              "CpuQuota": 50000,
 186              "CpusetCpus": "0,1",
 187              "CpusetMems": "0,1",
 188              "BlkioWeight": 300,
 189              "MemorySwappiness": 60,
 190              "OomKillDisable": false,
 191              "PidMode": "",
 192              "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
 193              "PublishAllPorts": false,
 194              "Privileged": false,
 195              "ReadonlyRootfs": false,
 196              "Dns": ["8.8.8.8"],
 197              "DnsOptions": [""],
 198              "DnsSearch": [""],
 199              "ExtraHosts": null,
 200              "VolumesFrom": ["parent", "other:ro"],
 201              "CapAdd": ["NET_ADMIN"],
 202              "CapDrop": ["MKNOD"],
 203              "GroupAdd": ["newgroup"],
 204              "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
 205              "NetworkMode": "bridge",
 206              "Devices": [],
 207              "Ulimits": [{}],
 208              "LogConfig": { "Type": "json-file", "Config": {} },
 209              "SecurityOpt": [],
 210              "CgroupParent": "",
 211              "VolumeDriver": ""
 212           }
 213       }
 214
 215 **Example response**:
 216
 217       HTTP/1.1 201 Created
 218       Content-Type: application/json
 219
 220       {
 221            "Id":"e90e34656806",
 222            "Warnings":[]
 223       }
 224
 225 **JSON parameters**:
 226
 227 -   **Hostname** - A string value containing the hostname to use for the
 228       container.
 229 -   **Domainname** - A string value containing the domain name to use
 230       for the container.
 231 -   **User** - A string value specifying the user inside the container.
 232 -   **AttachStdin** - Boolean value, attaches to `stdin`.
 233 -   **AttachStdout** - Boolean value, attaches to `stdout`.
 234 -   **AttachStderr** - Boolean value, attaches to `stderr`.
 235 -   **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed.
 236 -   **OpenStdin** - Boolean value, opens `stdin`,
 237 -   **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
 238 -   **Env** - A list of environment variables in the form of `["VAR=value", ...]`
 239 -   **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }`
 240 -   **Cmd** - Command to run specified as a string or an array of strings.
 241 -   **Entrypoint** - Set the entry point for the container as a string or an array
 242       of strings.
 243 -   **Image** - A string specifying the image name to use for the container.
 244 -   **Volumes** - An object mapping mount point paths (strings) inside the
 245       container to empty objects.
 246 -   **WorkingDir** - A string specifying the working directory for commands to
 247       run in.
 248 -   **NetworkDisabled** - Boolean value, when true disables networking for the
 249       container
 250 -   **ExposedPorts** - An object mapping ports to an empty object in the form of:
 251       `"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
 252 -   **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default.
 253 -   **HostConfig**
 254     -   **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
 255            + `host-src:container-dest` to bind-mount a host path into the
 256              container. Both `host-src`, and `container-dest` must be an
 257              _absolute_ path.
 258            + `host-src:container-dest:ro` to make the bind-mount read-only
 259              inside the container. Both `host-src`, and `container-dest` must be
 260              an _absolute_ path.
 261            + `volume-name:container-dest` to bind-mount a volume managed by a
 262              volume driver into the container. `container-dest` must be an
 263              _absolute_ path.
 264            + `volume-name:container-dest:ro` to mount the volume read-only
 265              inside the container.  `container-dest` must be an _absolute_ path.
 266     -   **Links** - A list of links for the container. Each link entry should be
 267           in the form of `container_name:alias`.
 268     -   **LxcConf** - LXC specific configurations. These configurations only
 269           work when using the `lxc` execution driver.
 270     -   **Memory** - Memory limit in bytes.
 271     -   **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap.
 272           You must use this with `memory` and make the swap value larger than `memory`.
 273     -   **MemoryReservation** - Memory soft limit in bytes.
 274     -   **KernelMemory** - Kernel memory limit in bytes.
 275     -   **CpuShares** - An integer value containing the container's CPU Shares
 276           (ie. the relative weight vs other containers).
 277     -   **CpuPeriod** - The length of a CPU period in microseconds.
 278     -   **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period.
 279     -   **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.
 280     -   **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
 281     -   **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000.
 282     -   **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
 283     -   **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not.
 284     -   **PidMode** - Set the PID (Process) Namespace mode for the container;
 285           `"container:<name|id>"`: joins another container's PID namespace
 286           `"host"`: use the host's PID namespace inside the container
 287     -   **PortBindings** - A map of exposed container ports and the host port they
 288           should map to. A JSON object in the form
 289           `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
 290           Take note that `port` is specified as a string and not an integer value.
 291     -   **PublishAllPorts** - Allocates a random host port for all of a container's
 292           exposed ports. Specified as a boolean value.
 293     -   **Privileged** - Gives the container full access to the host. Specified as
 294           a boolean value.
 295     -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
 296           Specified as a boolean value.
 297     -   **Dns** - A list of DNS servers for the container to use.
 298     -   **DnsOptions** - A list of DNS options
 299     -   **DnsSearch** - A list of DNS search domains
 300     -   **ExtraHosts** - A list of hostnames/IP mappings to add to the
 301         container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`.
 302     -   **VolumesFrom** - A list of volumes to inherit from another container.
 303           Specified in the form `<container name>[:<ro|rw>]`
 304     -   **CapAdd** - A list of kernel capabilities to add to the container.
 305     -   **Capdrop** - A list of kernel capabilities to drop from the container.
 306     -   **GroupAdd** - A list of additional groups that the container process will run as
 307     -   **RestartPolicy** – The behavior to apply when the container exits.  The
 308             value is an object with a `Name` property of either `"always"` to
 309             always restart, `"unless-stopped"` to restart always except when
 310             user has manually stopped the container or `"on-failure"` to restart only when the container
 311             exit code is non-zero.  If `on-failure` is used, `MaximumRetryCount`
 312             controls the number of times to retry before giving up.
 313             The default is not to restart. (optional)
 314             An ever increasing delay (double the previous delay, starting at 100mS)
 315             is added before each restart to prevent flooding the server.
 316     -   **NetworkMode** - Sets the networking mode for the container. Supported
 317           standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken
 318           as a custom network's name to which this container should connect to.
 319     -   **Devices** - A list of devices to add to the container specified as a JSON object in the
 320       form
 321           `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
 322     -   **Ulimits** - A list of ulimits to set in the container, specified as
 323           `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
 324           `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }`
 325     -   **SecurityOpt**: A list of string values to customize labels for MLS
 326         systems, such as SELinux.
 327     -   **LogConfig** - Log configuration for the container, specified as a JSON object in the form
 328           `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
 329           Available types: `json-file`, `syslog`, `journald`, `gelf`, `awslogs`, `none`.
 330           `json-file` logging driver.
 331     -   **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.
 332     -   **VolumeDriver** - Driver that this container users to mount volumes.
 333
 334 **Query parameters**:
 335
 336 -   **name** – Assign the specified name to the container. Must
 337     match `/?[a-zA-Z0-9_-]+`.
 338
 339 **Status codes**:
 340
 341 -   **201** – no error
 342 -   **400** – bad parameter
 343 -   **404** – no such container
 344 -   **406** – impossible to attach (container not running)
 345 -   **409** – conflict
 346 -   **500** – server error
 347
 348 #### Inspect a container
 349
 350 `GET /containers/(id or name)/json`
 351
 352 Return low-level information on the container `id`
 353
 354 **Example request**:
 355
 356       GET /v1.21/containers/4fa6e0f0c678/json HTTP/1.1
 357
 358 **Example response**:
 359
 360     HTTP/1.1 200 OK
 361     Content-Type: application/json
 362
 363         {
 364                 "AppArmorProfile": "",
 365                 "Args": [
 366                         "-c",
 367                         "exit 9"
 368                 ],
 369                 "Config": {
 370                         "AttachStderr": true,
 371                         "AttachStdin": false,
 372                         "AttachStdout": true,
 373                         "Cmd": [
 374                                 "/bin/sh",
 375                                 "-c",
 376                                 "exit 9"
 377                         ],
 378                         "Domainname": "",
 379                         "Entrypoint": null,
 380                         "Env": [
 381                                 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
 382                         ],
 383                         "ExposedPorts": null,
 384                         "Hostname": "ba033ac44011",
 385                         "Image": "ubuntu",
 386                         "Labels": {
 387                                 "com.example.vendor": "Acme",
 388                                 "com.example.license": "GPL",
 389                                 "com.example.version": "1.0"
 390                         },
 391                         "MacAddress": "",
 392                         "NetworkDisabled": false,
 393                         "OnBuild": null,
 394                         "OpenStdin": false,
 395                         "StdinOnce": false,
 396                         "Tty": false,
 397                         "User": "",
 398                         "Volumes": null,
 399                         "WorkingDir": "",
 400                         "StopSignal": "SIGTERM"
 401                 },
 402                 "Created": "2015-01-06T15:47:31.485331387Z",
 403                 "Driver": "devicemapper",
 404                 "ExecDriver": "native-0.2",
 405                 "ExecIDs": null,
 406                 "HostConfig": {
 407                         "Binds": null,
 408                         "BlkioWeight": 0,
 409                         "CapAdd": null,
 410                         "CapDrop": null,
 411                         "ContainerIDFile": "",
 412                         "CpusetCpus": "",
 413                         "CpusetMems": "",
 414                         "CpuShares": 0,
 415                         "CpuPeriod": 100000,
 416                         "Devices": [],
 417                         "Dns": null,
 418                         "DnsOptions": null,
 419                         "DnsSearch": null,
 420                         "ExtraHosts": null,
 421                         "IpcMode": "",
 422                         "Links": null,
 423                         "LxcConf": [],
 424                         "Memory": 0,
 425                         "MemorySwap": 0,
 426                         "MemoryReservation": 0,
 427                         "KernelMemory": 0,
 428                         "OomKillDisable": false,
 429                         "NetworkMode": "bridge",
 430                         "PidMode": "",
 431                         "PortBindings": {},
 432                         "Privileged": false,
 433                         "ReadonlyRootfs": false,
 434                         "PublishAllPorts": false,
 435                         "RestartPolicy": {
 436                                 "MaximumRetryCount": 2,
 437                                 "Name": "on-failure"
 438                         },
 439                         "LogConfig": {
 440                                 "Config": null,
 441                                 "Type": "json-file"
 442                         },
 443                         "SecurityOpt": null,
 444                         "VolumesFrom": null,
 445                         "Ulimits": [{}],
 446                         "VolumeDriver": ""
 447                 },
 448                 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
 449                 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
 450                 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
 451                 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
 452                 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
 453                 "MountLabel": "",
 454                 "Name": "/boring_euclid",
 455                 "NetworkSettings": {
 456                         "Bridge": "",
 457                         "SandboxID": "",
 458                         "HairpinMode": false,
 459                         "LinkLocalIPv6Address": "",
 460                         "LinkLocalIPv6PrefixLen": 0,
 461                         "Ports": null,
 462                         "SandboxKey": "",
 463                         "SecondaryIPAddresses": null,
 464                         "SecondaryIPv6Addresses": null,
 465                         "EndpointID": "",
 466                         "Gateway": "",
 467                         "GlobalIPv6Address": "",
 468                         "GlobalIPv6PrefixLen": 0,
 469                         "IPAddress": "",
 470                         "IPPrefixLen": 0,
 471                         "IPv6Gateway": "",
 472                         "MacAddress": "",
 473                         "Networks": {
 474                                 "bridge": {
 475                                         "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
 476                                         "Gateway": "172.17.0.1",
 477                                         "IPAddress": "172.17.0.2",
 478                                         "IPPrefixLen": 16,
 479                                         "IPv6Gateway": "",
 480                                         "GlobalIPv6Address": "",
 481                                         "GlobalIPv6PrefixLen": 0,
 482                                         "MacAddress": "02:42:ac:12:00:02"
 483                                 }
 484                         }
 485                 },
 486                 "Path": "/bin/sh",
 487                 "ProcessLabel": "",
 488                 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
 489                 "RestartCount": 1,
 490                 "State": {
 491                         "Error": "",
 492                         "ExitCode": 9,
 493                         "FinishedAt": "2015-01-06T15:47:32.080254511Z",
 494                         "OOMKilled": false,
 495                         "Paused": false,
 496                         "Pid": 0,
 497                         "Restarting": false,
 498                         "Running": true,
 499                         "StartedAt": "2015-01-06T15:47:32.072697474Z",
 500                         "Status": "running"
 501                 },
 502                 "Mounts": [
 503                         {
 504                                 "Source": "/data",
 505                                 "Destination": "/data",
 506                                 "Mode": "ro,Z",
 507                                 "RW": false
 508                         }
 509                 ]
 510         }
 511
 512 **Example request, with size information**:
 513
 514     GET /v1.21/containers/4fa6e0f0c678/json?size=1 HTTP/1.1
 515
 516 **Example response, with size information**:
 517
 518     HTTP/1.1 200 OK
 519     Content-Type: application/json
 520
 521     {
 522     ....
 523     "SizeRw": 0,
 524     "SizeRootFs": 972,
 525     ....
 526     }
 527
 528 **Query parameters**:
 529
 530 -   **size** – 1/True/true or 0/False/false, return container size information. Default is `false`.
 531
 532 **Status codes**:
 533
 534 -   **200** – no error
 535 -   **404** – no such container
 536 -   **500** – server error
 537
 538 #### List processes running inside a container
 539
 540 `GET /containers/(id or name)/top`
 541
 542 List processes running inside the container `id`. On Unix systems this
 543 is done by running the `ps` command. This endpoint is not
 544 supported on Windows.
 545
 546 **Example request**:
 547
 548     GET /v1.21/containers/4fa6e0f0c678/top HTTP/1.1
 549
 550 **Example response**:
 551
 552     HTTP/1.1 200 OK
 553     Content-Type: application/json
 554
 555     {
 556        "Titles" : [
 557          "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD"
 558        ],
 559        "Processes" : [
 560          [
 561            "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash"
 562          ],
 563          [
 564            "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10"
 565          ]
 566        ]
 567     }
 568
 569 **Example request**:
 570
 571     GET /v1.21/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1
 572
 573 **Example response**:
 574
 575     HTTP/1.1 200 OK
 576     Content-Type: application/json
 577
 578     {
 579       "Titles" : [
 580         "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
 581       ]
 582       "Processes" : [
 583         [
 584           "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
 585         ],
 586         [
 587           "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
 588         ]
 589       ],
 590     }
 591
 592 **Query parameters**:
 593
 594 -   **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef`
 595
 596 **Status codes**:
 597
 598 -   **200** – no error
 599 -   **404** – no such container
 600 -   **500** – server error
 601
 602 #### Get container logs
 603
 604 `GET /containers/(id or name)/logs`
 605
 606 Get `stdout` and `stderr` logs from the container ``id``
 607
 608 > **Note**:
 609 > This endpoint works only for containers with the `json-file` or `journald` logging drivers.
 610
 611 **Example request**:
 612
 613      GET /v1.21/containers/4fa6e0f0c678/logs?stderr=1&stdout=1&timestamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1
 614
 615 **Example response**:
 616
 617      HTTP/1.1 101 UPGRADED
 618      Content-Type: application/vnd.docker.raw-stream
 619      Connection: Upgrade
 620      Upgrade: tcp
 621
 622      {% raw %}
 623      {{ STREAM }}
 624      {% endraw %}
 625
 626 **Query parameters**:
 627
 628 -   **follow** – 1/True/true or 0/False/false, return stream. Default `false`.
 629 -   **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`.
 630 -   **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`.
 631 -   **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp
 632     will only output log-entries since that timestamp. Default: 0 (unfiltered)
 633 -   **timestamps** – 1/True/true or 0/False/false, print timestamps for
 634         every log line. Default `false`.
 635 -   **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all.
 636
 637 **Status codes**:
 638
 639 -   **101** – no error, hints proxy about hijacking
 640 -   **200** – no error, no upgrade header found
 641 -   **404** – no such container
 642 -   **500** – server error
 643
 644 #### Inspect changes on a container's filesystem
 645
 646 `GET /containers/(id or name)/changes`
 647
 648 Inspect changes on container `id`'s filesystem
 649
 650 **Example request**:
 651
 652     GET /v1.21/containers/4fa6e0f0c678/changes HTTP/1.1
 653
 654 **Example response**:
 655
 656     HTTP/1.1 200 OK
 657     Content-Type: application/json
 658
 659     [
 660          {
 661                  "Path": "/dev",
 662                  "Kind": 0
 663          },
 664          {
 665                  "Path": "/dev/kmsg",
 666                  "Kind": 1
 667          },
 668          {
 669                  "Path": "/test",
 670                  "Kind": 1
 671          }
 672     ]
 673
 674 Values for `Kind`:
 675
 676 - `0`: Modify
 677 - `1`: Add
 678 - `2`: Delete
 679
 680 **Status codes**:
 681
 682 -   **200** – no error
 683 -   **404** – no such container
 684 -   **500** – server error
 685
 686 #### Export a container
 687
 688 `GET /containers/(id or name)/export`
 689
 690 Export the contents of container `id`
 691
 692 **Example request**:
 693
 694     GET /v1.21/containers/4fa6e0f0c678/export HTTP/1.1
 695
 696 **Example response**:
 697
 698     HTTP/1.1 200 OK
 699     Content-Type: application/octet-stream
 700
 701     {% raw %}
 702     {{ TAR STREAM }}
 703     {% endraw %}
 704
 705 **Status codes**:
 706
 707 -   **200** – no error
 708 -   **404** – no such container
 709 -   **500** – server error
 710
 711 #### Get container stats based on resource usage
 712
 713 `GET /containers/(id or name)/stats`
 714
 715 This endpoint returns a live stream of a container's resource usage statistics.
 716
 717 **Example request**:
 718
 719     GET /v1.21/containers/redis1/stats HTTP/1.1
 720
 721 **Example response**:
 722
 723       HTTP/1.1 200 OK
 724       Content-Type: application/json
 725
 726       {
 727          "read" : "2015-01-08T22:57:31.547920715Z",
 728          "networks": {
 729                  "eth0": {
 730                      "rx_bytes": 5338,
 731                      "rx_dropped": 0,
 732                      "rx_errors": 0,
 733                      "rx_packets": 36,
 734                      "tx_bytes": 648,
 735                      "tx_dropped": 0,
 736                      "tx_errors": 0,
 737                      "tx_packets": 8
 738                  },
 739                  "eth5": {
 740                      "rx_bytes": 4641,
 741                      "rx_dropped": 0,
 742                      "rx_errors": 0,
 743                      "rx_packets": 26,
 744                      "tx_bytes": 690,
 745                      "tx_dropped": 0,
 746                      "tx_errors": 0,
 747                      "tx_packets": 9
 748                  }
 749          },
 750          "memory_stats" : {
 751             "stats" : {
 752                "total_pgmajfault" : 0,
 753                "cache" : 0,
 754                "mapped_file" : 0,
 755                "total_inactive_file" : 0,
 756                "pgpgout" : 414,
 757                "rss" : 6537216,
 758                "total_mapped_file" : 0,
 759                "writeback" : 0,
 760                "unevictable" : 0,
 761                "pgpgin" : 477,
 762                "total_unevictable" : 0,
 763                "pgmajfault" : 0,
 764                "total_rss" : 6537216,
 765                "total_rss_huge" : 6291456,
 766                "total_writeback" : 0,
 767                "total_inactive_anon" : 0,
 768                "rss_huge" : 6291456,
 769                "hierarchical_memory_limit" : 67108864,
 770                "total_pgfault" : 964,
 771                "total_active_file" : 0,
 772                "active_anon" : 6537216,
 773                "total_active_anon" : 6537216,
 774                "total_pgpgout" : 414,
 775                "total_cache" : 0,
 776                "inactive_anon" : 0,
 777                "active_file" : 0,
 778                "pgfault" : 964,
 779                "inactive_file" : 0,
 780                "total_pgpgin" : 477
 781             },
 782             "max_usage" : 6651904,
 783             "usage" : 6537216,
 784             "failcnt" : 0,
 785             "limit" : 67108864
 786          },
 787          "blkio_stats" : {},
 788          "cpu_stats" : {
 789             "cpu_usage" : {
 790                "percpu_usage" : [
 791                   8646879,
 792                   24472255,
 793                   36438778,
 794                   30657443
 795                ],
 796                "usage_in_usermode" : 50000000,
 797                "total_usage" : 100215355,
 798                "usage_in_kernelmode" : 30000000
 799             },
 800             "system_cpu_usage" : 739306590000000,
 801             "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
 802          },
 803          "precpu_stats" : {
 804             "cpu_usage" : {
 805                "percpu_usage" : [
 806                   8646879,
 807                   24350896,
 808                   36438778,
 809                   30657443
 810                ],
 811                "usage_in_usermode" : 50000000,
 812                "total_usage" : 100093996,
 813                "usage_in_kernelmode" : 30000000
 814             },
 815             "system_cpu_usage" : 9492140000000,
 816             "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
 817          }
 818       }
 819
 820 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.
 821
 822 **Query parameters**:
 823
 824 -   **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`.
 825
 826 **Status codes**:
 827
 828 -   **200** – no error
 829 -   **404** – no such container
 830 -   **500** – server error
 831
 832 #### Resize a container TTY
 833
 834 `POST /containers/(id or name)/resize`
 835
 836 Resize the TTY for container with  `id`. The unit is number of characters. You must restart the container for the resize to take effect.
 837
 838 **Example request**:
 839
 840       POST /v1.21/containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1
 841
 842 **Example response**:
 843
 844       HTTP/1.1 200 OK
 845       Content-Length: 0
 846       Content-Type: text/plain; charset=utf-8
 847
 848 **Query parameters**:
 849
 850 -   **h** – height of `tty` session
 851 -   **w** – width
 852
 853 **Status codes**:
 854
 855 -   **200** – no error
 856 -   **404** – No such container
 857 -   **500** – Cannot resize container
 858
 859 #### Start a container
 860
 861 `POST /containers/(id or name)/start`
 862
 863 Start the container `id`
 864
 865 > **Note**:
 866 > For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body.
 867 > See [create a container](#create-a-container) for details.
 868
 869 **Example request**:
 870
 871     POST /v1.21/containers/e90e34656806/start HTTP/1.1
 872
 873 **Example response**:
 874
 875     HTTP/1.1 204 No Content
 876
 877 **Status codes**:
 878
 879 -   **204** – no error
 880 -   **304** – container already started
 881 -   **404** – no such container
 882 -   **500** – server error
 883
 884 #### Stop a container
 885
 886 `POST /containers/(id or name)/stop`
 887
 888 Stop the container `id`
 889
 890 **Example request**:
 891
 892     POST /v1.21/containers/e90e34656806/stop?t=5 HTTP/1.1
 893
 894 **Example response**:
 895
 896     HTTP/1.1 204 No Content
 897
 898 **Query parameters**:
 899
 900 -   **t** – number of seconds to wait before killing the container
 901
 902 **Status codes**:
 903
 904 -   **204** – no error
 905 -   **304** – container already stopped
 906 -   **404** – no such container
 907 -   **500** – server error
 908
 909 #### Restart a container
 910
 911 `POST /containers/(id or name)/restart`
 912
 913 Restart the container `id`
 914
 915 **Example request**:
 916
 917     POST /v1.21/containers/e90e34656806/restart?t=5 HTTP/1.1
 918
 919 **Example response**:
 920
 921     HTTP/1.1 204 No Content
 922
 923 **Query parameters**:
 924
 925 -   **t** – number of seconds to wait before killing the container
 926
 927 **Status codes**:
 928
 929 -   **204** – no error
 930 -   **404** – no such container
 931 -   **500** – server error
 932
 933 #### Kill a container
 934
 935 `POST /containers/(id or name)/kill`
 936
 937 Kill the container `id`
 938
 939 **Example request**:
 940
 941     POST /v1.21/containers/e90e34656806/kill HTTP/1.1
 942
 943 **Example response**:
 944
 945     HTTP/1.1 204 No Content
 946
 947 **Query parameters**:
 948
 949 -   **signal** - Signal to send to the container: integer or string like `SIGINT`.
 950         When not set, `SIGKILL` is assumed and the call waits for the container to exit.
 951
 952 **Status codes**:
 953
 954 -   **204** – no error
 955 -   **404** – no such container
 956 -   **500** – server error
 957
 958 #### Rename a container
 959
 960 `POST /containers/(id or name)/rename`
 961
 962 Rename the container `id` to a `new_name`
 963
 964 **Example request**:
 965
 966     POST /v1.21/containers/e90e34656806/rename?name=new_name HTTP/1.1
 967
 968 **Example response**:
 969
 970     HTTP/1.1 204 No Content
 971
 972 **Query parameters**:
 973
 974 -   **name** – new name for the container
 975
 976 **Status codes**:
 977
 978 -   **204** – no error
 979 -   **404** – no such container
 980 -   **409** - conflict name already assigned
 981 -   **500** – server error
 982
 983 #### Pause a container
 984
 985 `POST /containers/(id or name)/pause`
 986
 987 Pause the container `id`
 988
 989 **Example request**:
 990
 991     POST /v1.21/containers/e90e34656806/pause HTTP/1.1
 992
 993 **Example response**:
 994
 995     HTTP/1.1 204 No Content
 996
 997 **Status codes**:
 998
 999 -   **204** – no error
1000 -   **404** – no such container
1001 -   **500** – server error
1002
1003 #### Unpause a container
1004
1005 `POST /containers/(id or name)/unpause`
1006
1007 Unpause the container `id`
1008
1009 **Example request**:
1010
1011     POST /v1.21/containers/e90e34656806/unpause HTTP/1.1
1012
1013 **Example response**:
1014
1015     HTTP/1.1 204 No Content
1016
1017 **Status codes**:
1018
1019 -   **204** – no error
1020 -   **404** – no such container
1021 -   **500** – server error
1022
1023 #### Attach to a container
1024
1025 `POST /containers/(id or name)/attach`
1026
1027 Attach to the container `id`
1028
1029 **Example request**:
1030
1031     POST /v1.21/containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
1032
1033 **Example response**:
1034
1035     HTTP/1.1 101 UPGRADED
1036     Content-Type: application/vnd.docker.raw-stream
1037     Connection: Upgrade
1038     Upgrade: tcp
1039
1040     {% raw %}
1041     {{ STREAM }}
1042     {% endraw %}
1043
1044 **Query parameters**:
1045
1046 -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
1047 -   **stream** – 1/True/true or 0/False/false, return stream.
1048         Default `false`.
1049 -   **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
1050         to `stdin`. Default `false`.
1051 -   **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
1052         `stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
1053 -   **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
1054         `stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
1055
1056 **Status codes**:
1057
1058 -   **101** – no error, hints proxy about hijacking
1059 -   **200** – no error, no upgrade header found
1060 -   **400** – bad parameter
1061 -   **404** – no such container
1062 -   **500** – server error
1063
1064 **Stream details**:
1065
1066 When using the TTY setting is enabled in
1067 [`POST /containers/create`
1068 ](#create-a-container),
1069 the stream is the raw data from the process PTY and client's `stdin`.
1070 When the TTY is disabled, then the stream is multiplexed to separate
1071 `stdout` and `stderr`.
1072
1073 The format is a **Header** and a **Payload** (frame).
1074
1075 **HEADER**
1076
1077 The header contains the information which the stream writes (`stdout` or
1078 `stderr`). It also contains the size of the associated frame encoded in the
1079 last four bytes (`uint32`).
1080
1081 It is encoded on the first eight bytes like this:
1082
1083     header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
1084
1085 `STREAM_TYPE` can be:
1086
1087 -   0: `stdin` (is written on `stdout`)
1088 -   1: `stdout`
1089 -   2: `stderr`
1090
1091 `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of
1092 the `uint32` size encoded as big endian.
1093
1094 **PAYLOAD**
1095
1096 The payload is the raw stream.
1097
1098 **IMPLEMENTATION**
1099
1100 The simplest way to implement the Attach protocol is the following:
1101
1102     1.  Read eight bytes.
1103     2.  Choose `stdout` or `stderr` depending on the first byte.
1104     3.  Extract the frame size from the last four bytes.
1105     4.  Read the extracted size and output it on the correct output.
1106     5.  Goto 1.
1107
1108 #### Attach to a container (websocket)
1109
1110 `GET /containers/(id or name)/attach/ws`
1111
1112 Attach to the container `id` via websocket
1113
1114 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455)
1115
1116 **Example request**
1117
1118     GET /v1.21/containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1
1119
1120 **Example response**
1121
1122     {% raw %}
1123     {{ STREAM }}
1124     {% endraw %}
1125
1126 **Query parameters**:
1127
1128 -   **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
1129 -   **stream** – 1/True/true or 0/False/false, return stream.
1130         Default `false`.
1131 -   **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
1132         to `stdin`. Default `false`.
1133 -   **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
1134         `stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
1135 -   **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
1136         `stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
1137
1138 **Status codes**:
1139
1140 -   **200** – no error
1141 -   **400** – bad parameter
1142 -   **404** – no such container
1143 -   **500** – server error
1144
1145 #### Wait a container
1146
1147 `POST /containers/(id or name)/wait`
1148
1149 Block until container `id` stops, then returns the exit code
1150
1151 **Example request**:
1152
1153     POST /v1.21/containers/16253994b7c4/wait HTTP/1.1
1154
1155 **Example response**:
1156
1157     HTTP/1.1 200 OK
1158     Content-Type: application/json
1159
1160     {"StatusCode": 0}
1161
1162 **Status codes**:
1163
1164 -   **200** – no error
1165 -   **404** – no such container
1166 -   **500** – server error
1167
1168 #### Remove a container
1169
1170 `DELETE /containers/(id or name)`
1171
1172 Remove the container `id` from the filesystem
1173
1174 **Example request**:
1175
1176     DELETE /v1.21/containers/16253994b7c4?v=1 HTTP/1.1
1177
1178 **Example response**:
1179
1180     HTTP/1.1 204 No Content
1181
1182 **Query parameters**:
1183
1184 -   **v** – 1/True/true or 0/False/false, Remove the volumes
1185         associated to the container. Default `false`.
1186 -   **force** - 1/True/true or 0/False/false, Kill then remove the container.
1187         Default `false`.
1188 -   **link** - 1/True/true or 0/False/false, Remove the specified
1189         link associated to the container. Default `false`.
1190
1191 **Status codes**:
1192
1193 -   **204** – no error
1194 -   **400** – bad parameter
1195 -   **404** – no such container
1196 -   **409** – conflict
1197 -   **500** – server error
1198
1199 #### Copy files or folders from a container
1200
1201 `POST /containers/(id or name)/copy`
1202
1203 Copy files or folders of container `id`
1204
1205 **Deprecated** in favor of the `archive` endpoint below.
1206
1207 **Example request**:
1208
1209     POST /v1.21/containers/4fa6e0f0c678/copy HTTP/1.1
1210     Content-Type: application/json
1211
1212     {
1213          "Resource": "test.txt"
1214     }
1215
1216 **Example response**:
1217
1218     HTTP/1.1 200 OK
1219     Content-Type: application/x-tar
1220
1221     {% raw %}
1222     {{ TAR STREAM }}
1223     {% endraw %}
1224
1225 **Status codes**:
1226
1227 -   **200** – no error
1228 -   **404** – no such container
1229 -   **500** – server error
1230
1231 #### Retrieving information about files and folders in a container
1232
1233 `HEAD /containers/(id or name)/archive`
1234
1235 See the description of the `X-Docker-Container-Path-Stat` header in the
1236 following section.
1237
1238 #### Get an archive of a filesystem resource in a container
1239
1240 `GET /containers/(id or name)/archive`
1241
1242 Get a tar archive of a resource in the filesystem of container `id`.
1243
1244 **Query parameters**:
1245
1246 - **path** - resource in the container's filesystem to archive. Required.
1247
1248     If not an absolute path, it is relative to the container's root directory.
1249     The resource specified by **path** must exist. To assert that the resource
1250     is expected to be a directory, **path** should end in `/` or  `/.`
1251     (assuming a path separator of `/`). If **path** ends in `/.` then this
1252     indicates that only the contents of the **path** directory should be
1253     copied. A symlink is always resolved to its target.
1254
1255     > **Note**: It is not possible to copy certain system files such as resources
1256     > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
1257     > container.
1258
1259 **Example request**:
1260
1261     GET /v1.21/containers/8cce319429b2/archive?path=/root HTTP/1.1
1262
1263 **Example response**:
1264
1265     HTTP/1.1 200 OK
1266     Content-Type: application/x-tar
1267     X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0=
1268
1269     {% raw %}
1270     {{ TAR STREAM }}
1271     {% endraw %}
1272
1273 On success, a response header `X-Docker-Container-Path-Stat` will be set to a
1274 base64-encoded JSON object containing some filesystem header information about
1275 the archived resource. The above example value would decode to the following
1276 JSON object (whitespace added for readability):
1277
1278 ```json
1279 {
1280     "name": "root",
1281     "size": 4096,
1282     "mode": 2147484096,
1283     "mtime": "2014-02-27T20:51:23Z",
1284     "linkTarget": ""
1285 }
1286 ```
1287
1288 A `HEAD` request can also be made to this endpoint if only this information is
1289 desired.
1290
1291 **Status codes**:
1292
1293 - **200** - success, returns archive of copied resource
1294 - **400** - client error, bad parameter, details in JSON response body, one of:
1295     - must specify path parameter (**path** cannot be empty)
1296     - not a directory (**path** was asserted to be a directory but exists as a
1297       file)
1298 - **404** - client error, resource not found, one of:
1299     – no such container (container `id` does not exist)
1300     - no such file or directory (**path** does not exist)
1301 - **500** - server error
1302
1303 #### Extract an archive of files or folders to a directory in a container
1304
1305 `PUT /containers/(id or name)/archive`
1306
1307 Upload a tar archive to be extracted to a path in the filesystem of container
1308 `id`.
1309
1310 **Query parameters**:
1311
1312 - **path** - path to a directory in the container
1313     to extract the archive's contents into. Required.
1314
1315     If not an absolute path, it is relative to the container's root directory.
1316     The **path** resource must exist.
1317 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error
1318     if unpacking the given content would cause an existing directory to be
1319     replaced with a non-directory and vice versa.
1320
1321 **Example request**:
1322
1323     PUT /v1.21/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1
1324     Content-Type: application/x-tar
1325
1326     {% raw %}
1327     {{ TAR STREAM }}
1328     {% endraw %}
1329
1330 **Example response**:
1331
1332     HTTP/1.1 200 OK
1333
1334 **Status codes**:
1335
1336 - **200** – the content was extracted successfully
1337 - **400** - client error, bad parameter, details in JSON response body, one of:
1338     - must specify path parameter (**path** cannot be empty)
1339     - not a directory (**path** should be a directory but exists as a file)
1340     - unable to overwrite existing directory with non-directory
1341       (if **noOverwriteDirNonDir**)
1342     - unable to overwrite existing non-directory with directory
1343       (if **noOverwriteDirNonDir**)
1344 - **403** - client error, permission denied, the volume
1345     or container rootfs is marked as read-only.
1346 - **404** - client error, resource not found, one of:
1347     – no such container (container `id` does not exist)
1348     - no such file or directory (**path** resource does not exist)
1349 - **500** – server error
1350
1351 ### 2.2 Images
1352
1353 #### List Images
1354
1355 `GET /images/json`
1356
1357 **Example request**:
1358
1359     GET /v1.21/images/json?all=0 HTTP/1.1
1360
1361 **Example response**:
1362
1363     HTTP/1.1 200 OK
1364     Content-Type: application/json
1365
1366     [
1367       {
1368          "RepoTags": [
1369            "ubuntu:12.04",
1370            "ubuntu:precise",
1371            "ubuntu:latest"
1372          ],
1373          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
1374          "Created": 1365714795,
1375          "Size": 131506275,
1376          "VirtualSize": 131506275,
1377          "Labels": {}
1378       },
1379       {
1380          "RepoTags": [
1381            "ubuntu:12.10",
1382            "ubuntu:quantal"
1383          ],
1384          "ParentId": "27cf784147099545",
1385          "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
1386          "Created": 1364102658,
1387          "Size": 24653,
1388          "VirtualSize": 180116135,
1389          "Labels": {
1390             "com.example.version": "v1"
1391          }
1392       }
1393     ]
1394
1395 **Example request, with digest information**:
1396
1397     GET /v1.21/images/json?digests=1 HTTP/1.1
1398
1399 **Example response, with digest information**:
1400
1401     HTTP/1.1 200 OK
1402     Content-Type: application/json
1403
1404     [
1405       {
1406         "Created": 1420064636,
1407         "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125",
1408         "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2",
1409         "RepoDigests": [
1410           "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
1411         ],
1412         "RepoTags": [
1413           "localhost:5000/test/busybox:latest",
1414           "playdate:latest"
1415         ],
1416         "Size": 0,
1417         "VirtualSize": 2429728,
1418         "Labels": {}
1419       }
1420     ]
1421
1422 The response shows a single image `Id` associated with two repositories
1423 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use
1424 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or
1425 `playdate:latest` to reference the image.
1426
1427 You can also use `RepoDigests` values to reference an image. In this response,
1428 the array has only one reference and that is to the
1429 `localhost:5000/test/busybox` repository; the `playdate` repository has no
1430 digest. You can reference this digest using the value:
1431 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...`
1432
1433 See the `docker run` and `docker build` commands for examples of digest and tag
1434 references on the command line.
1435
1436 **Query parameters**:
1437
1438 -   **all** – 1/True/true or 0/False/false, default false
1439 -   **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
1440   -   `dangling=true`
1441   -   `label=key` or `label="key=value"` of an image label
1442 -   **filter** - only return images with the specified name
1443
1444 #### Build image from a Dockerfile
1445
1446 `POST /build`
1447
1448 Build an image from a Dockerfile
1449
1450 **Example request**:
1451
1452     POST /v1.21/build HTTP/1.1
1453     Content-Type: application/x-tar
1454
1455     {% raw %}
1456     {{ TAR STREAM }}
1457     {% endraw %}
1458
1459 **Example response**:
1460
1461     HTTP/1.1 200 OK
1462     Content-Type: application/json
1463
1464     {"stream": "Step 1/5..."}
1465     {"stream": "..."}
1466     {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}
1467
1468 The input stream must be a `tar` archive compressed with one of the
1469 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`.
1470
1471 The archive must include a build instructions file, typically called
1472 `Dockerfile` at the archive's root. The `dockerfile` parameter may be
1473 used to specify a different build instructions file. To do this, its value must be
1474 the path to the alternate build instructions file to use.
1475
1476 The archive may include any number of other files,
1477 which are accessible in the build context (See the [*ADD build
1478 command*](../reference/builder.md#add)).
1479
1480 The Docker daemon performs a preliminary validation of the `Dockerfile` before
1481 starting the build, and returns an error if the syntax is incorrect. After that,
1482 each instruction is run one-by-one until the ID of the new image is output.
1483
1484 The build is canceled if the client drops the connection by quitting
1485 or being killed.
1486
1487 **Query parameters**:
1488
1489 -   **dockerfile** - Path within the build context to the `Dockerfile`. This is
1490         ignored if `remote` is specified and points to an external `Dockerfile`.
1491 -   **t** – A name and optional tag to apply to the image in the `name:tag` format.
1492         If you omit the `tag` the default `latest` value is assumed.
1493         You can provide one or more `t` parameters.
1494 -   **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
1495         URI points to a single text file, the file's contents are placed into
1496         a file called `Dockerfile` and the image is built from that file. If
1497         the URI points to a tarball, the file is downloaded by the daemon and
1498         the contents therein used as the context for the build. If the URI
1499         points to a tarball and the `dockerfile` parameter is also specified,
1500         there must be a file with the corresponding path inside the tarball.
1501 -   **q** – Suppress verbose build output.
1502 -   **nocache** – Do not use the cache when building the image.
1503 -   **pull** - Attempt to pull the image even if an older image exists locally.
1504 -   **rm** - Remove intermediate containers after a successful build (default behavior).
1505 -   **forcerm** - Always remove intermediate containers (includes `rm`).
1506 -   **memory** - Set memory limit for build.
1507 -   **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap.
1508 -   **cpushares** - CPU shares (relative weight).
1509 -   **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).
1510 -   **cpuperiod** - The length of a CPU period in microseconds.
1511 -   **cpuquota** - Microseconds of CPU time that the container can get in a CPU period.
1512 -   **buildargs** – JSON map of string pairs for build-time variables. Users pass
1513         these values at build-time. Docker uses the `buildargs` as the environment
1514         context for command(s) run via the Dockerfile's `RUN` instruction or for
1515         variable expansion in other Dockerfile instructions. This is not meant for
1516         passing secret values. [Read more about the buildargs instruction](../reference/builder.md#arg)
1517
1518 **Request Headers**:
1519
1520 -   **Content-type** – Set to `"application/x-tar"`.
1521 -   **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
1522         object with the following structure:
1523
1524             {
1525                 "docker.example.com": {
1526                     "username": "janedoe",
1527                     "password": "hunter2"
1528                 },
1529                 "https://index.docker.io/v1/": {
1530                     "username": "mobydock",
1531                     "password": "conta1n3rize14"
1532                 }
1533             }
1534
1535     This object maps the hostname of a registry to an object containing the
1536     "username" and "password" for that registry. Multiple registries may
1537     be specified as the build may be based on an image requiring
1538     authentication to pull from any arbitrary registry. Only the registry
1539     domain name (and port if not the default "443") are required. However
1540     (for legacy reasons) the "official" Docker, Inc. hosted registry must
1541     be specified with both a "https://" prefix and a "/v1/" suffix even
1542     though Docker will prefer to use the v2 registry API.
1543
1544 **Status codes**:
1545
1546 -   **200** – no error
1547 -   **500** – server error
1548
1549 #### Create an image
1550
1551 `POST /images/create`
1552
1553 Create an image either by pulling it from the registry or by importing it
1554
1555 **Example request**:
1556
1557     POST /v1.21/images/create?fromImage=busybox&tag=latest HTTP/1.1
1558
1559 **Example response**:
1560
1561     HTTP/1.1 200 OK
1562     Content-Type: application/json
1563
1564     {"status": "Pulling..."}
1565     {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
1566     {"error": "Invalid..."}
1567     ...
1568
1569 When using this endpoint to pull an image from the registry, the
1570 `X-Registry-Auth` header can be used to include
1571 a base64-encoded AuthConfig object.
1572
1573 **Query parameters**:
1574
1575 -   **fromImage** – Name of the image to pull. The name may include a tag or
1576         digest. This parameter may only be used when pulling an image.
1577 -   **fromSrc** – Source to import.  The value may be a URL from which the image
1578         can be retrieved or `-` to read the image from the request body.
1579         This parameter may only be used when importing an image.
1580 -   **repo** – Repository name given to an image when it is imported.
1581         The repo may include a tag. This parameter may only be used when importing
1582         an image.
1583 -   **tag** – Tag or digest. If empty when pulling an image, this causes all tags
1584         for the given image to be pulled.
1585
1586 **Request Headers**:
1587
1588 -   **X-Registry-Auth** – base64-encoded AuthConfig object
1589
1590 **Status codes**:
1591
1592 -   **200** – no error
1593 -   **404** - repository does not exist or no read access
1594 -   **500** – server error
1595
1596
1597
1598 #### Inspect an image
1599
1600 `GET /images/(name)/json`
1601
1602 Return low-level information on the image `name`
1603
1604 **Example request**:
1605
1606     GET /v1.21/images/example/json HTTP/1.1
1607
1608 **Example response**:
1609
1610     HTTP/1.1 200 OK
1611     Content-Type: application/json
1612
1613     {
1614        "Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c",
1615        "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a",
1616        "Comment" : "",
1617        "Os" : "linux",
1618        "Architecture" : "amd64",
1619        "Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
1620        "ContainerConfig" : {
1621           "Tty" : false,
1622           "Hostname" : "e611e15f9c9d",
1623           "Volumes" : null,
1624           "Domainname" : "",
1625           "AttachStdout" : false,
1626           "PublishService" : "",
1627           "AttachStdin" : false,
1628           "OpenStdin" : false,
1629           "StdinOnce" : false,
1630           "NetworkDisabled" : false,
1631           "OnBuild" : [],
1632           "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
1633           "User" : "",
1634           "WorkingDir" : "",
1635           "Entrypoint" : null,
1636           "MacAddress" : "",
1637           "AttachStderr" : false,
1638           "Labels" : {
1639              "com.example.license" : "GPL",
1640              "com.example.version" : "1.0",
1641              "com.example.vendor" : "Acme"
1642           },
1643           "Env" : [
1644              "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
1645           ],
1646           "ExposedPorts" : null,
1647           "Cmd" : [
1648              "/bin/sh",
1649              "-c",
1650              "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0"
1651           ]
1652        },
1653        "DockerVersion" : "1.9.0-dev",
1654        "VirtualSize" : 188359297,
1655        "Size" : 0,
1656        "Author" : "",
1657        "Created" : "2015-09-10T08:30:53.26995814Z",
1658        "GraphDriver" : {
1659           "Name" : "aufs",
1660           "Data" : null
1661        },
1662        "RepoDigests" : [
1663           "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
1664        ],
1665        "RepoTags" : [
1666           "example:1.0",
1667           "example:latest",
1668           "example:stable"
1669        ],
1670        "Config" : {
1671           "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
1672           "NetworkDisabled" : false,
1673           "OnBuild" : [],
1674           "StdinOnce" : false,
1675           "PublishService" : "",
1676           "AttachStdin" : false,
1677           "OpenStdin" : false,
1678           "Domainname" : "",
1679           "AttachStdout" : false,
1680           "Tty" : false,
1681           "Hostname" : "e611e15f9c9d",
1682           "Volumes" : null,
1683           "Cmd" : [
1684              "/bin/bash"
1685           ],
1686           "ExposedPorts" : null,
1687           "Env" : [
1688              "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
1689           ],
1690           "Labels" : {
1691              "com.example.vendor" : "Acme",
1692              "com.example.version" : "1.0",
1693              "com.example.license" : "GPL"
1694           },
1695           "Entrypoint" : null,
1696           "MacAddress" : "",
1697           "AttachStderr" : false,
1698           "WorkingDir" : "",
1699           "User" : ""
1700        }
1701     }
1702
1703 **Status codes**:
1704
1705 -   **200** – no error
1706 -   **404** – no such image
1707 -   **500** – server error
1708
1709 #### Get the history of an image
1710
1711 `GET /images/(name)/history`
1712
1713 Return the history of the image `name`
1714
1715 **Example request**:
1716
1717     GET /v1.21/images/ubuntu/history HTTP/1.1
1718
1719 **Example response**:
1720
1721     HTTP/1.1 200 OK
1722     Content-Type: application/json
1723
1724     [
1725         {
1726             "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
1727             "Created": 1398108230,
1728             "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
1729             "Tags": [
1730                 "ubuntu:lucid",
1731                 "ubuntu:10.04"
1732             ],
1733             "Size": 182964289,
1734             "Comment": ""
1735         },
1736         {
1737             "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
1738             "Created": 1398108222,
1739             "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/",
1740             "Tags": null,
1741             "Size": 0,
1742             "Comment": ""
1743         },
1744         {
1745             "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
1746             "Created": 1371157430,
1747             "CreatedBy": "",
1748             "Tags": [
1749                 "scratch12:latest",
1750                 "scratch:latest"
1751             ],
1752             "Size": 0,
1753             "Comment": "Imported from -"
1754         }
1755     ]
1756
1757 **Status codes**:
1758
1759 -   **200** – no error
1760 -   **404** – no such image
1761 -   **500** – server error
1762
1763 #### Push an image on the registry
1764
1765 `POST /images/(name)/push`
1766
1767 Push the image `name` on the registry
1768
1769 **Example request**:
1770
1771     POST /v1.21/images/test/push HTTP/1.1
1772
1773 **Example response**:
1774
1775     HTTP/1.1 200 OK
1776     Content-Type: application/json
1777
1778     {"status": "Pushing..."}
1779     {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
1780     {"error": "Invalid..."}
1781     ...
1782
1783 If you wish to push an image on to a private registry, that image must already have a tag
1784 into a repository which references that registry `hostname` and `port`.  This repository name should
1785 then be used in the URL. This duplicates the command line's flow.
1786
1787 **Example request**:
1788
1789     POST /v1.21/images/registry.acme.com:5000/test/push HTTP/1.1
1790
1791
1792 **Query parameters**:
1793
1794 -   **tag** – The tag to associate with the image on the registry. This is optional.
1795
1796 **Request Headers**:
1797
1798 -   **X-Registry-Auth** – base64-encoded AuthConfig object.
1799
1800 **Status codes**:
1801
1802 -   **200** – no error
1803 -   **404** – no such image
1804 -   **500** – server error
1805
1806 #### Tag an image into a repository
1807
1808 `POST /images/(name)/tag`
1809
1810 Tag the image `name` into a repository
1811
1812 **Example request**:
1813
1814     POST /v1.21/images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1
1815
1816 **Example response**:
1817
1818     HTTP/1.1 201 Created
1819
1820 **Query parameters**:
1821
1822 -   **repo** – The repository to tag in
1823 -   **force** – 1/True/true or 0/False/false, default false
1824 -   **tag** - The new tag name
1825
1826 **Status codes**:
1827
1828 -   **201** – no error
1829 -   **400** – bad parameter
1830 -   **404** – no such image
1831 -   **409** – conflict
1832 -   **500** – server error
1833
1834 #### Remove an image
1835
1836 `DELETE /images/(name)`
1837
1838 Remove the image `name` from the filesystem
1839
1840 **Example request**:
1841
1842     DELETE /v1.21/images/test HTTP/1.1
1843
1844 **Example response**:
1845
1846     HTTP/1.1 200 OK
1847     Content-type: application/json
1848
1849     [
1850      {"Untagged": "3e2f21a89f"},
1851      {"Deleted": "3e2f21a89f"},
1852      {"Deleted": "53b4f83ac9"}
1853     ]
1854
1855 **Query parameters**:
1856
1857 -   **force** – 1/True/true or 0/False/false, default false
1858 -   **noprune** – 1/True/true or 0/False/false, default false
1859
1860 **Status codes**:
1861
1862 -   **200** – no error
1863 -   **404** – no such image
1864 -   **409** – conflict
1865 -   **500** – server error
1866
1867 #### Search images
1868
1869 `GET /images/search`
1870
1871 Search for an image on [Docker Hub](https://hub.docker.com).
1872
1873 > **Note**:
1874 > The response keys have changed from API v1.6 to reflect the JSON
1875 > sent by the registry server to the docker daemon's request.
1876
1877 **Example request**:
1878
1879     GET /v1.21/images/search?term=sshd HTTP/1.1
1880
1881 **Example response**:
1882
1883     HTTP/1.1 200 OK
1884     Content-Type: application/json
1885
1886     [
1887             {
1888                 "description": "",
1889                 "is_official": false,
1890                 "is_automated": false,
1891                 "name": "wma55/u1210sshd",
1892                 "star_count": 0
1893             },
1894             {
1895                 "description": "",
1896                 "is_official": false,
1897                 "is_automated": false,
1898                 "name": "jdswinbank/sshd",
1899                 "star_count": 0
1900             },
1901             {
1902                 "description": "",
1903                 "is_official": false,
1904                 "is_automated": false,
1905                 "name": "vgauthier/sshd",
1906                 "star_count": 0
1907             }
1908     ...
1909     ]
1910
1911 **Query parameters**:
1912
1913 -   **term** – term to search
1914
1915 **Status codes**:
1916
1917 -   **200** – no error
1918 -   **500** – server error
1919
1920 ### 2.3 Misc
1921
1922 #### Check auth configuration
1923
1924 `POST /auth`
1925
1926 Get the default username and email
1927
1928 **Example request**:
1929
1930     POST /v1.21/auth HTTP/1.1
1931     Content-Type: application/json
1932
1933     {
1934          "username": "hannibal",
1935          "password": "xxxx",
1936          "email": "hannibal@a-team.com",
1937          "serveraddress": "https://index.docker.io/v1/"
1938     }
1939
1940 **Example response**:
1941
1942     HTTP/1.1 200 OK
1943
1944 **Status codes**:
1945
1946 -   **200** – no error
1947 -   **204** – no error
1948 -   **500** – server error
1949
1950 #### Display system-wide information
1951
1952 `GET /info`
1953
1954 Display system-wide information
1955
1956 **Example request**:
1957
1958     GET /v1.21/info HTTP/1.1
1959
1960 **Example response**:
1961
1962     HTTP/1.1 200 OK
1963     Content-Type: application/json
1964
1965     {
1966         "ClusterStore": "etcd://localhost:2379",
1967         "Containers": 11,
1968         "CpuCfsPeriod": true,
1969         "CpuCfsQuota": true,
1970         "Debug": false,
1971         "DockerRootDir": "/var/lib/docker",
1972         "Driver": "btrfs",
1973         "DriverStatus": [[""]],
1974         "ExecutionDriver": "native-0.1",
1975         "ExperimentalBuild": false,
1976         "HttpProxy": "http://test:test@localhost:8080",
1977         "HttpsProxy": "https://test:test@localhost:8080",
1978         "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
1979         "IPv4Forwarding": true,
1980         "Images": 16,
1981         "IndexServerAddress": "https://index.docker.io/v1/",
1982         "InitPath": "/usr/bin/docker",
1983         "InitSha1": "",
1984         "KernelVersion": "3.12.0-1-amd64",
1985         "Labels": [
1986             "storage=ssd"
1987         ],
1988         "MemTotal": 2099236864,
1989         "MemoryLimit": true,
1990         "NCPU": 1,
1991         "NEventsListener": 0,
1992         "NFd": 11,
1993         "NGoroutines": 21,
1994         "Name": "prod-server-42",
1995         "NoProxy": "9.81.1.160",
1996         "OomKillDisable": true,
1997         "OperatingSystem": "Boot2Docker",
1998         "RegistryConfig": {
1999             "IndexConfigs": {
2000                 "docker.io": {
2001                     "Mirrors": null,
2002                     "Name": "docker.io",
2003                     "Official": true,
2004                     "Secure": true
2005                 }
2006             },
2007             "InsecureRegistryCIDRs": [
2008                 "127.0.0.0/8"
2009             ]
2010         },
2011         "ServerVersion": "1.9.0",
2012         "SwapLimit": false,
2013         "SystemTime": "2015-03-10T11:11:23.730591467-07:00"
2014     }
2015
2016 **Status codes**:
2017
2018 -   **200** – no error
2019 -   **500** – server error
2020
2021 #### Show the docker version information
2022
2023 `GET /version`
2024
2025 Show the docker version information
2026
2027 **Example request**:
2028
2029     GET /v1.21/version HTTP/1.1
2030
2031 **Example response**:
2032
2033     HTTP/1.1 200 OK
2034     Content-Type: application/json
2035
2036     {
2037          "Version": "1.5.0",
2038          "Os": "linux",
2039          "KernelVersion": "3.18.5-tinycore64",
2040          "GoVersion": "go1.4.1",
2041          "GitCommit": "a8a31ef",
2042          "Arch": "amd64",
2043          "ApiVersion": "1.20",
2044          "Experimental": false
2045     }
2046
2047 **Status codes**:
2048
2049 -   **200** – no error
2050 -   **500** – server error
2051
2052 #### Ping the docker server
2053
2054 `GET /_ping`
2055
2056 Ping the docker server
2057
2058 **Example request**:
2059
2060     GET /v1.21/_ping HTTP/1.1
2061
2062 **Example response**:
2063
2064     HTTP/1.1 200 OK
2065     Content-Type: text/plain
2066
2067     OK
2068
2069 **Status codes**:
2070
2071 -   **200** - no error
2072 -   **500** - server error
2073
2074 #### Create a new image from a container's changes
2075
2076 `POST /commit`
2077
2078 Create a new image from a container's changes
2079
2080 **Example request**:
2081
2082     POST /v1.21/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
2083     Content-Type: application/json
2084
2085     {
2086          "Hostname": "",
2087          "Domainname": "",
2088          "User": "",
2089          "AttachStdin": false,
2090          "AttachStdout": true,
2091          "AttachStderr": true,
2092          "Tty": false,
2093          "OpenStdin": false,
2094          "StdinOnce": false,
2095          "Env": null,
2096          "Cmd": [
2097                  "date"
2098          ],
2099          "Mounts": [
2100            {
2101              "Source": "/data",
2102              "Destination": "/data",
2103              "Mode": "ro,Z",
2104              "RW": false
2105            }
2106          ],
2107          "Labels": {
2108                  "key1": "value1",
2109                  "key2": "value2"
2110           },
2111          "WorkingDir": "",
2112          "NetworkDisabled": false,
2113          "ExposedPorts": {
2114                  "22/tcp": {}
2115          }
2116     }
2117
2118 **Example response**:
2119
2120     HTTP/1.1 201 Created
2121     Content-Type: application/json
2122
2123     {"Id": "596069db4bf5"}
2124
2125 **JSON parameters**:
2126
2127 -  **config** - the container's configuration
2128
2129 **Query parameters**:
2130
2131 -   **container** – source container
2132 -   **repo** – repository
2133 -   **tag** – tag
2134 -   **comment** – commit message
2135 -   **author** – author (e.g., "John Hannibal Smith
2136     <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
2137 -   **pause** – 1/True/true or 0/False/false, whether to pause the container before committing
2138 -   **changes** – Dockerfile instructions to apply while committing
2139
2140 **Status codes**:
2141
2142 -   **201** – no error
2143 -   **404** – no such container
2144 -   **500** – server error
2145
2146 #### Monitor Docker's events
2147
2148 `GET /events`
2149
2150 Get container events from docker, in real time via streaming.
2151
2152 Docker containers report the following events:
2153
2154     attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause
2155
2156 Docker images report the following events:
2157
2158     delete, import, pull, push, tag, untag
2159
2160 **Example request**:
2161
2162     GET /v1.21/events?since=1374067924
2163
2164 **Example response**:
2165
2166     HTTP/1.1 200 OK
2167     Content-Type: application/json
2168
2169     {"status":"pull","id":"busybox:latest","time":1442421700,"timeNano":1442421700598988358}
2170     {"status":"create","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716853979870}
2171     {"status":"attach","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716894759198}
2172     {"status":"start","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716983607193}
2173
2174 **Query parameters**:
2175
2176 -   **since** – Timestamp. Show all events created since timestamp and then stream
2177 -   **until** – Timestamp. Show events created until given timestamp and stop streaming
2178 -   **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters:
2179   -   `container=<string>`; -- container to filter
2180   -   `event=<string>`; -- event to filter
2181   -   `image=<string>`; -- image to filter
2182   -   `label=<string>`; -- image and container label to filter
2183
2184 **Status codes**:
2185
2186 -   **200** – no error
2187 -   **500** – server error
2188
2189 #### Get a tarball containing all images in a repository
2190
2191 `GET /images/(name)/get`
2192
2193 Get a tarball containing all images and metadata for the repository specified
2194 by `name`.
2195
2196 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
2197 (and its parents) are returned. If `name` is an image ID, similarly only that
2198 image (and its parents) are returned, but with the exclusion of the
2199 'repositories' file in the tarball, as there were no image names referenced.
2200
2201 See the [image tarball format](#image-tarball-format) for more details.
2202
2203 **Example request**
2204
2205     GET /v1.21/images/ubuntu/get
2206
2207 **Example response**:
2208
2209     HTTP/1.1 200 OK
2210     Content-Type: application/x-tar
2211
2212     Binary data stream
2213
2214 **Status codes**:
2215
2216 -   **200** – no error
2217 -   **500** – server error
2218
2219 #### Get a tarball containing all images
2220
2221 `GET /images/get`
2222
2223 Get a tarball containing all images and metadata for one or more repositories.
2224
2225 For each value of the `names` parameter: if it is a specific name and tag (e.g.
2226 `ubuntu:latest`), then only that image (and its parents) are returned; if it is
2227 an image ID, similarly only that image (and its parents) are returned and there
2228 would be no names referenced in the 'repositories' file for this image ID.
2229
2230 See the [image tarball format](#image-tarball-format) for more details.
2231
2232 **Example request**
2233
2234     GET /v1.21/images/get?names=myname%2Fmyapp%3Alatest&names=busybox
2235
2236 **Example response**:
2237
2238     HTTP/1.1 200 OK
2239     Content-Type: application/x-tar
2240
2241     Binary data stream
2242
2243 **Status codes**:
2244
2245 -   **200** – no error
2246 -   **500** – server error
2247
2248 #### Load a tarball with a set of images and tags into docker
2249
2250 `POST /images/load`
2251
2252 Load a set of images and tags into a Docker repository.
2253 See the [image tarball format](#image-tarball-format) for more details.
2254
2255 **Example request**
2256
2257     POST /v1.21/images/load
2258     Content-Type: application/x-tar
2259
2260     Tarball in body
2261
2262 **Example response**:
2263
2264     HTTP/1.1 200 OK
2265
2266 **Status codes**:
2267
2268 -   **200** – no error
2269 -   **500** – server error
2270
2271 #### Image tarball format
2272
2273 An image tarball contains one directory per image layer (named using its long ID),
2274 each containing these files:
2275
2276 - `VERSION`: currently `1.0` - the file format version
2277 - `json`: detailed layer information, similar to `docker inspect layer_id`
2278 - `layer.tar`: A tarfile containing the filesystem changes in this layer
2279
2280 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories
2281 for storing attribute changes and deletions.
2282
2283 If the tarball defines a repository, the tarball should also include a `repositories` file at
2284 the root that contains a list of repository and tag names mapped to layer IDs.
2285
2286 ```
2287 {"hello-world":
2288     {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
2289 }
2290 ```
2291
2292 #### Exec Create
2293
2294 `POST /containers/(id or name)/exec`
2295
2296 Sets up an exec instance in a running container `id`
2297
2298 **Example request**:
2299
2300     POST /v1.21/containers/e90e34656806/exec HTTP/1.1
2301     Content-Type: application/json
2302
2303     {
2304       "AttachStdin": true,
2305       "AttachStdout": true,
2306       "AttachStderr": true,
2307       "Cmd": ["sh"],
2308       "Privileged": true,
2309       "Tty": true,
2310       "User": "123:456"
2311     }
2312
2313 **Example response**:
2314
2315     HTTP/1.1 201 Created
2316     Content-Type: application/json
2317
2318     {
2319          "Id": "f90e34656806",
2320          "Warnings":[]
2321     }
2322
2323 **JSON parameters**:
2324
2325 -   **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
2326 -   **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
2327 -   **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command.
2328 -   **Tty** - Boolean value to allocate a pseudo-TTY.
2329 -   **Cmd** - Command to run specified as a string or an array of strings.
2330 -   **Privileged** - Boolean value, runs the exec process with extended privileges.
2331 -   **User** - A string value specifying the user, and optionally, group to run
2332         the exec process inside the container. Format is one of: `"user"`,
2333         `"user:group"`, `"uid"`, or `"uid:gid"`.
2334
2335 **Status codes**:
2336
2337 -   **201** – no error
2338 -   **404** – no such container
2339 -   **409** - container is paused
2340 -   **500** - server error
2341
2342 #### Exec Start
2343
2344 `POST /exec/(id)/start`
2345
2346 Starts a previously set up `exec` instance `id`. If `detach` is true, this API
2347 returns after starting the `exec` command. Otherwise, this API sets up an
2348 interactive session with the `exec` command.
2349
2350 **Example request**:
2351
2352     POST /v1.21/exec/e90e34656806/start HTTP/1.1
2353     Content-Type: application/json
2354
2355     {
2356      "Detach": false,
2357      "Tty": false
2358     }
2359
2360 **Example response**:
2361
2362     HTTP/1.1 200 OK
2363     Content-Type: application/vnd.docker.raw-stream
2364
2365     {% raw %}
2366     {{ STREAM }}
2367     {% endraw %}
2368
2369 **JSON parameters**:
2370
2371 -   **Detach** - Detach from the `exec` command.
2372 -   **Tty** - Boolean value to allocate a pseudo-TTY.
2373
2374 **Status codes**:
2375
2376 -   **200** – no error
2377 -   **404** – no such exec instance
2378 -   **409** - container is paused
2379
2380 **Stream details**:
2381
2382 Similar to the stream behavior of `POST /containers/(id or name)/attach` API
2383
2384 #### Exec Resize
2385
2386 `POST /exec/(id)/resize`
2387
2388 Resizes the `tty` session used by the `exec` command `id`.  The unit is number of characters.
2389 This API is valid only if `tty` was specified as part of creating and starting the `exec` command.
2390
2391 **Example request**:
2392
2393     POST /v1.21/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1
2394     Content-Type: text/plain
2395
2396 **Example response**:
2397
2398     HTTP/1.1 201 Created
2399     Content-Type: text/plain
2400
2401 **Query parameters**:
2402
2403 -   **h** – height of `tty` session
2404 -   **w** – width
2405
2406 **Status codes**:
2407
2408 -   **201** – no error
2409 -   **404** – no such exec instance
2410
2411 #### Exec Inspect
2412
2413 `GET /exec/(id)/json`
2414
2415 Return low-level information about the `exec` command `id`.
2416
2417 **Example request**:
2418
2419     GET /v1.21/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1
2420
2421 **Example response**:
2422
2423     HTTP/1.1 200 OK
2424     Content-Type: plain/text
2425
2426     {
2427       "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39",
2428       "Running" : false,
2429       "ExitCode" : 2,
2430       "ProcessConfig" : {
2431         "privileged" : false,
2432         "user" : "",
2433         "tty" : false,
2434         "entrypoint" : "sh",
2435         "arguments" : [
2436           "-c",
2437           "exit 2"
2438         ]
2439       },
2440       "OpenStdin" : false,
2441       "OpenStderr" : false,
2442       "OpenStdout" : false,
2443       "Container" : {
2444         "State" : {
2445           "Status" : "running",
2446           "Running" : true,
2447           "Paused" : false,
2448           "Restarting" : false,
2449           "OOMKilled" : false,
2450           "Pid" : 3650,
2451           "ExitCode" : 0,
2452           "Error" : "",
2453           "StartedAt" : "2014-11-17T22:26:03.717657531Z",
2454           "FinishedAt" : "0001-01-01T00:00:00Z"
2455         },
2456         "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c",
2457         "Created" : "2014-11-17T22:26:03.626304998Z",
2458         "Path" : "date",
2459         "Args" : [],
2460         "Config" : {
2461           "Hostname" : "8f177a186b97",
2462           "Domainname" : "",
2463           "User" : "",
2464           "AttachStdin" : false,
2465           "AttachStdout" : false,
2466           "AttachStderr" : false,
2467           "ExposedPorts" : null,
2468           "Tty" : false,
2469           "OpenStdin" : false,
2470           "StdinOnce" : false,
2471           "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ],
2472           "Cmd" : [
2473             "date"
2474           ],
2475           "Image" : "ubuntu",
2476           "Volumes" : null,
2477           "WorkingDir" : "",
2478           "Entrypoint" : null,
2479           "NetworkDisabled" : false,
2480           "MacAddress" : "",
2481           "OnBuild" : null,
2482           "SecurityOpt" : null
2483         },
2484         "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5",
2485         "NetworkSettings" : {
2486           "Bridge": "",
2487           "SandboxID": "",
2488           "HairpinMode": false,
2489           "LinkLocalIPv6Address": "",
2490           "LinkLocalIPv6PrefixLen": 0,
2491           "Ports": null,
2492           "SandboxKey": "",
2493           "SecondaryIPAddresses": null,
2494           "SecondaryIPv6Addresses": null,
2495           "EndpointID": "",
2496           "Gateway": "",
2497           "GlobalIPv6Address": "",
2498           "GlobalIPv6PrefixLen": 0,
2499           "IPAddress": "",
2500           "IPPrefixLen": 0,
2501           "IPv6Gateway": "",
2502           "MacAddress": "",
2503           "Networks": {
2504             "bridge": {
2505               "EndpointID": "",
2506               "Gateway": "",
2507               "IPAddress": "",
2508               "IPPrefixLen": 0,
2509               "IPv6Gateway": "",
2510               "GlobalIPv6Address": "",
2511               "GlobalIPv6PrefixLen": 0,
2512               "MacAddress": ""
2513             }
2514           }
2515         },
2516         "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf",
2517         "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname",
2518         "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts",
2519         "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
2520         "Name" : "/test",
2521         "Driver" : "aufs",
2522         "ExecDriver" : "native-0.2",
2523         "MountLabel" : "",
2524         "ProcessLabel" : "",
2525         "AppArmorProfile" : "",
2526         "RestartCount" : 0,
2527         "Mounts" : []
2528       }
2529     }
2530
2531 **Status codes**:
2532
2533 -   **200** – no error
2534 -   **404** – no such exec instance
2535 -   **500** - server error
2536
2537 ### 2.4 Volumes
2538
2539 #### List volumes
2540
2541 `GET /volumes`
2542
2543 **Example request**:
2544
2545     GET /v1.21/volumes HTTP/1.1
2546
2547 **Example response**:
2548
2549     HTTP/1.1 200 OK
2550     Content-Type: application/json
2551
2552     {
2553       "Volumes": [
2554         {
2555           "Name": "tardis",
2556           "Driver": "local",
2557           "Mountpoint": "/var/lib/docker/volumes/tardis"
2558         }
2559       ]
2560     }
2561
2562 **Query parameters**:
2563
2564 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true`
2565
2566 **Status codes**:
2567
2568 -   **200** - no error
2569 -   **500** - server error
2570
2571 #### Create a volume
2572
2573 `POST /volumes/create`
2574
2575 Create a volume
2576
2577 **Example request**:
2578
2579     POST /v1.21/volumes/create HTTP/1.1
2580     Content-Type: application/json
2581
2582     {
2583       "Name": "tardis"
2584     }
2585
2586 **Example response**:
2587
2588     HTTP/1.1 201 Created
2589     Content-Type: application/json
2590
2591     {
2592       "Name": "tardis",
2593       "Driver": "local",
2594       "Mountpoint": "/var/lib/docker/volumes/tardis"
2595     }
2596
2597 **Status codes**:
2598
2599 - **201** - no error
2600 - **500**  - server error
2601
2602 **JSON parameters**:
2603
2604 - **Name** - The new volume's name. If not specified, Docker generates a name.
2605 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name.
2606 - **DriverOpts** - A mapping of driver options and values. These options are
2607     passed directly to the driver and are driver specific.
2608
2609 #### Inspect a volume
2610
2611 `GET /volumes/(name)`
2612
2613 Return low-level information on the volume `name`
2614
2615 **Example request**:
2616
2617     GET /volumes/tardis
2618
2619 **Example response**:
2620
2621     HTTP/1.1 200 OK
2622     Content-Type: application/json
2623
2624     {
2625       "Name": "tardis",
2626       "Driver": "local",
2627       "Mountpoint": "/var/lib/docker/volumes/tardis"
2628     }
2629
2630 **Status codes**:
2631
2632 -   **200** - no error
2633 -   **404** - no such volume
2634 -   **500** - server error
2635
2636 #### Remove a volume
2637
2638 `DELETE /volumes/(name)`
2639
2640 Instruct the driver to remove the volume (`name`).
2641
2642 **Example request**:
2643
2644     DELETE /v1.21/volumes/tardis HTTP/1.1
2645
2646 **Example response**:
2647
2648     HTTP/1.1 204 No Content
2649
2650 **Status codes**:
2651
2652 -   **204** - no error
2653 -   **404** - no such volume or volume driver
2654 -   **409** - volume is in use and cannot be removed
2655 -   **500** - server error
2656
2657 ### 2.5 Networks
2658
2659 #### List networks
2660
2661 `GET /networks`
2662
2663 **Example request**:
2664
2665     GET /v1.21/networks HTTP/1.1
2666
2667 **Example response**:
2668
2669 ```
2670 HTTP/1.1 200 OK
2671 Content-Type: application/json
2672
2673 [
2674   {
2675     "Name": "bridge",
2676     "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
2677     "Scope": "local",
2678     "Driver": "bridge",
2679     "IPAM": {
2680       "Driver": "default",
2681       "Config": [
2682         {
2683           "Subnet": "172.17.0.0/16"
2684         }
2685       ]
2686     },
2687     "Containers": {
2688       "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": {
2689         "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda",
2690         "MacAddress": "02:42:ac:11:00:02",
2691         "IPv4Address": "172.17.0.2/16",
2692         "IPv6Address": ""
2693       }
2694     },
2695     "Options": {
2696       "com.docker.network.bridge.default_bridge": "true",
2697       "com.docker.network.bridge.enable_icc": "true",
2698       "com.docker.network.bridge.enable_ip_masquerade": "true",
2699       "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
2700       "com.docker.network.bridge.name": "docker0",
2701       "com.docker.network.driver.mtu": "1500"
2702     }
2703   },
2704   {
2705     "Name": "none",
2706     "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
2707     "Scope": "local",
2708     "Driver": "null",
2709     "IPAM": {
2710       "Driver": "default",
2711       "Config": []
2712     },
2713     "Containers": {},
2714     "Options": {}
2715   },
2716   {
2717     "Name": "host",
2718     "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
2719     "Scope": "local",
2720     "Driver": "host",
2721     "IPAM": {
2722       "Driver": "default",
2723       "Config": []
2724     },
2725     "Containers": {},
2726     "Options": {}
2727   }
2728 ]
2729 ```
2730
2731 **Query parameters**:
2732
2733 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the networks list. Available filters: `name=[network-names]` , `id=[network-ids]`
2734
2735 **Status codes**:
2736
2737 -   **200** - no error
2738 -   **500** - server error
2739
2740 #### Inspect network
2741
2742 `GET /networks/(id or name)`
2743
2744 Return low-level information on the network `id`
2745
2746 **Example request**:
2747
2748     GET /v1.21/networks/f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566 HTTP/1.1
2749
2750 **Example response**:
2751
2752 ```
2753 HTTP/1.1 200 OK
2754 Content-Type: application/json
2755
2756 {
2757   "Name": "bridge",
2758   "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
2759   "Scope": "local",
2760   "Driver": "bridge",
2761   "IPAM": {
2762     "Driver": "default",
2763     "Config": [
2764       {
2765         "Subnet": "172.17.0.0/16"
2766       }
2767     ]
2768   },
2769   "Containers": {
2770     "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": {
2771       "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda",
2772       "MacAddress": "02:42:ac:11:00:02",
2773       "IPv4Address": "172.17.0.2/16",
2774       "IPv6Address": ""
2775     }
2776   },
2777   "Options": {
2778     "com.docker.network.bridge.default_bridge": "true",
2779     "com.docker.network.bridge.enable_icc": "true",
2780     "com.docker.network.bridge.enable_ip_masquerade": "true",
2781     "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
2782     "com.docker.network.bridge.name": "docker0",
2783     "com.docker.network.driver.mtu": "1500"
2784   }
2785 }
2786 ```
2787
2788 **Status codes**:
2789
2790 -   **200** - no error
2791 -   **404** - network not found
2792 -   **500** - server error
2793
2794 #### Create a network
2795
2796 `POST /networks/create`
2797
2798 Create a network
2799
2800 **Example request**:
2801
2802 ```
2803 POST /v1.21/networks/create HTTP/1.1
2804 Content-Type: application/json
2805
2806 {
2807   "Name":"isolated_nw",
2808   "CheckDuplicate":true,
2809   "Driver":"bridge",
2810   "IPAM":{
2811     "Driver": "default",
2812     "Config":[
2813       {
2814         "Subnet":"172.20.0.0/16",
2815         "IPRange":"172.20.10.0/24",
2816         "Gateway":"172.20.10.11"
2817       }
2818     ]
2819   }
2820 }
2821 ```
2822
2823 **Example response**:
2824
2825 ```
2826 HTTP/1.1 201 Created
2827 Content-Type: application/json
2828
2829 {
2830   "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
2831   "Warning": ""
2832 }
2833 ```
2834
2835 **Status codes**:
2836
2837 - **201** - no error
2838 - **404** - plugin not found
2839 - **500** - server error
2840
2841 **JSON parameters**:
2842
2843 - **Name** - The new network's name. this is a mandatory field
2844 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
2845     Since Network is primarily keyed based on a random ID and not on the name,
2846     and network name is strictly a user-friendly alias to the network which is uniquely identified using ID,
2847     there is no guaranteed way to check for duplicates across a cluster of docker hosts.
2848     This parameter CheckDuplicate is there to provide a best effort checking of any networks
2849     which has the same name but it is not guaranteed to catch all name collisions.
2850 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
2851 - **IPAM** - Optional custom IP scheme for the network
2852   - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver
2853   - **Config** - List of IPAM configuration options, specified as a map:
2854       `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}`
2855 - **Options** - Network specific options to be used by the drivers
2856
2857 #### Connect a container to a network
2858
2859 `POST /networks/(id or name)/connect`
2860
2861 Connect a container to a network
2862
2863 **Example request**:
2864
2865 ```
2866 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
2867 Content-Type: application/json
2868
2869 {
2870   "Container":"3613f73ba0e4"
2871 }
2872 ```
2873
2874 **Example response**:
2875
2876     HTTP/1.1 200 OK
2877
2878 **Status codes**:
2879
2880 - **200** - no error
2881 - **404** - network or container is not found
2882 - **500** - Internal Server Error
2883
2884 **JSON parameters**:
2885
2886 - **container** - container-id/name to be connected to the network
2887
2888 #### Disconnect a container from a network
2889
2890 `POST /networks/(id or name)/disconnect`
2891
2892 Disconnect a container from a network
2893
2894 **Example request**:
2895
2896 ```
2897 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
2898 Content-Type: application/json
2899
2900 {
2901   "Container":"3613f73ba0e4"
2902 }
2903 ```
2904
2905 **Example response**:
2906
2907     HTTP/1.1 200 OK
2908
2909 **Status codes**:
2910
2911 - **200** - no error
2912 - **404** - network or container not found
2913 - **500** - Internal Server Error
2914
2915 **JSON parameters**:
2916
2917 - **Container** - container-id/name to be disconnected from a network
2918
2919 #### Remove a network
2920
2921 `DELETE /networks/(id or name)`
2922
2923 Instruct the driver to remove the network (`id`).
2924
2925 **Example request**:
2926
2927     DELETE /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1
2928
2929 **Example response**:
2930
2931     HTTP/1.1 200 OK
2932
2933 **Status codes**:
2934
2935 -   **200** - no error
2936 -   **403** - operation not supported for pre-defined networks
2937 -   **404** - no such network
2938 -   **500** - server error
2939
2940 ## 3. Going further
2941
2942 ### 3.1 Inside `docker run`
2943
2944 As an example, the `docker run` command line makes the following API calls:
2945
2946 - Create the container
2947
2948 - If the status code is 404, it means the image doesn't exist:
2949     - Try to pull it.
2950     - Then, retry to create the container.
2951
2952 - Start the container.
2953
2954 - If you are not in detached mode:
2955 - Attach to the container, using `logs=1` (to have `stdout` and
2956       `stderr` from the container's start) and `stream=1`
2957
2958 - If in detached mode or only `stdin` is attached, display the container's id.
2959
2960 ### 3.2 Hijacking
2961
2962 In this version of the API, `/attach`, uses hijacking to transport `stdin`,
2963 `stdout`, and `stderr` on the same socket.
2964
2965 To hint potential proxies about connection hijacking, Docker client sends
2966 connection upgrade headers similarly to websocket.
2967
2968     Upgrade: tcp
2969     Connection: Upgrade
2970
2971 When Docker daemon detects the `Upgrade` header, it switches its status code
2972 from **200 OK** to **101 UPGRADED** and resends the same headers.
2973
2974
2975 ### 3.3 CORS Requests
2976
2977 To set cross origin requests to the Engine API please give values to
2978 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all,
2979 default or blank means CORS disabled
2980
2981     $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"