github.com/demonoid81/moby@v0.0.0-20200517203328-62dd8e17c460/docs/api/v1.18.md (about) 1 --- 2 title: "Engine API v1.18" 3 description: "API Documentation for Docker" 4 keywords: "API, Docker, rcli, REST, documentation" 5 redirect_from: 6 - /engine/reference/api/docker_remote_api_v1.18/ 7 - /reference/api/docker_remote_api_v1.18/ 8 --- 9 10 <!-- This file is maintained within the moby/moby GitHub 11 repository at https://github.com/moby/moby/. 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](https://docs.docker.com/engine/reference/commandline/dockerd/#bind-docker-to-another-host-port-or-a-unix-socket). 23 - The API tends to be REST, but for some complex commands, like `attach` 24 or `pull`, the HTTP connection is hijacked to transport `stdout`, 25 `stdin` and `stderr`. 26 - A `Content-Length` header should be present in `POST` requests to endpoints 27 that expect a body. 28 - To lock to a specific version of the API, you prefix the URL with the version 29 of the API to use. For example, `/v1.18/info`. If no version is included in 30 the URL, the maximum supported API version is used. 31 - If the API version specified in the URL is not supported by the daemon, a HTTP 32 `400 Bad Request` error message is returned. 33 34 ## 2. Endpoints 35 36 ### 2.1 Containers 37 38 #### List containers 39 40 `GET /containers/json` 41 42 List containers 43 44 **Example request**: 45 46 GET /v1.18/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 47 48 **Example response**: 49 50 HTTP/1.1 200 OK 51 Content-Type: application/json 52 53 [ 54 { 55 "Id": "8dfafdbc3a40", 56 "Names":["/boring_feynman"], 57 "Image": "ubuntu:latest", 58 "Command": "echo 1", 59 "Created": 1367854155, 60 "Status": "Exit 0", 61 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 62 "Labels": { 63 "com.example.vendor": "Acme", 64 "com.example.license": "GPL", 65 "com.example.version": "1.0" 66 }, 67 "SizeRw": 12288, 68 "SizeRootFs": 0 69 }, 70 { 71 "Id": "9cd87474be90", 72 "Names":["/coolName"], 73 "Image": "ubuntu:latest", 74 "Command": "echo 222222", 75 "Created": 1367854155, 76 "Status": "Exit 0", 77 "Ports": [], 78 "Labels": {}, 79 "SizeRw": 12288, 80 "SizeRootFs": 0 81 }, 82 { 83 "Id": "3176a2479c92", 84 "Names":["/sleepy_dog"], 85 "Image": "ubuntu:latest", 86 "Command": "echo 3333333333333333", 87 "Created": 1367854154, 88 "Status": "Exit 0", 89 "Ports":[], 90 "Labels": {}, 91 "SizeRw":12288, 92 "SizeRootFs":0 93 }, 94 { 95 "Id": "4cb07b47f9fb", 96 "Names":["/running_cat"], 97 "Image": "ubuntu:latest", 98 "Command": "echo 444444444444444444444444444444444", 99 "Created": 1367854152, 100 "Status": "Exit 0", 101 "Ports": [], 102 "Labels": {}, 103 "SizeRw": 12288, 104 "SizeRootFs": 0 105 } 106 ] 107 108 **Query parameters**: 109 110 - **all** – 1/True/true or 0/False/false, Show all containers. 111 Only running containers are shown by default (i.e., this defaults to false) 112 - **limit** – Show `limit` last created 113 containers, include non-running ones. 114 - **since** – Show only containers created since Id, include 115 non-running ones. 116 - **before** – Show only containers created before Id, include 117 non-running ones. 118 - **size** – 1/True/true or 0/False/false, Show the containers 119 sizes 120 - **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters: 121 - `exited=<int>`; -- containers with exit code of `<int>` ; 122 - `status=`(`restarting`|`running`|`paused`|`exited`) 123 - `label=key` or `label="key=value"` of a container label 124 125 **Status codes**: 126 127 - **200** – no error 128 - **400** – bad parameter 129 - **500** – server error 130 131 #### Create a container 132 133 `POST /containers/create` 134 135 Create a container 136 137 **Example request**: 138 139 POST /v1.18/containers/create HTTP/1.1 140 Content-Type: application/json 141 Content-Length: 12345 142 143 { 144 "Hostname": "", 145 "Domainname": "", 146 "User": "", 147 "AttachStdin": false, 148 "AttachStdout": true, 149 "AttachStderr": true, 150 "Tty": false, 151 "OpenStdin": false, 152 "StdinOnce": false, 153 "Env": [ 154 "FOO=bar", 155 "BAZ=quux" 156 ], 157 "Cmd": [ 158 "date" 159 ], 160 "Entrypoint": null, 161 "Image": "ubuntu", 162 "Labels": { 163 "com.example.vendor": "Acme", 164 "com.example.license": "GPL", 165 "com.example.version": "1.0" 166 }, 167 "Volumes": { 168 "/volumes/data": {} 169 }, 170 "WorkingDir": "", 171 "NetworkDisabled": false, 172 "MacAddress": "12:34:56:78:9a:bc", 173 "ExposedPorts": { 174 "22/tcp": {} 175 }, 176 "HostConfig": { 177 "Binds": ["/tmp:/tmp"], 178 "Links": ["redis3:redis"], 179 "LxcConf": {"lxc.utsname":"docker"}, 180 "Memory": 0, 181 "MemorySwap": 0, 182 "CpuShares": 512, 183 "CpusetCpus": "0,1", 184 "PidMode": "", 185 "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, 186 "PublishAllPorts": false, 187 "Privileged": false, 188 "ReadonlyRootfs": false, 189 "Dns": ["8.8.8.8"], 190 "DnsSearch": [""], 191 "ExtraHosts": null, 192 "VolumesFrom": ["parent", "other:ro"], 193 "CapAdd": ["NET_ADMIN"], 194 "CapDrop": ["MKNOD"], 195 "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, 196 "NetworkMode": "bridge", 197 "Devices": [], 198 "Ulimits": [{}], 199 "LogConfig": { "Type": "json-file", "Config": {} }, 200 "SecurityOpt": [], 201 "CgroupParent": "" 202 } 203 } 204 205 **Example response**: 206 207 HTTP/1.1 201 Created 208 Content-Type: application/json 209 210 { 211 "Id":"e90e34656806", 212 "Warnings":[] 213 } 214 215 **JSON parameters**: 216 217 - **Hostname** - A string value containing the hostname to use for the 218 container. 219 - **Domainname** - A string value containing the domain name to use 220 for the container. 221 - **User** - A string value specifying the user inside the container. 222 - **AttachStdin** - Boolean value, attaches to `stdin`. 223 - **AttachStdout** - Boolean value, attaches to `stdout`. 224 - **AttachStderr** - Boolean value, attaches to `stderr`. 225 - **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed. 226 - **OpenStdin** - Boolean value, opens `stdin`, 227 - **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects. 228 - **Env** - A list of environment variables in the form of `["VAR=value", ...]` 229 - **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }` 230 - **Cmd** - Command to run specified as a string or an array of strings. 231 - **Entrypoint** - Set the entry point for the container as a string or an array 232 of strings. 233 - **Image** - A string specifying the image name to use for the container. 234 - **Volumes** - An object mapping mount point paths (strings) inside the 235 container to empty objects. 236 - **WorkingDir** - A string specifying the working directory for commands to 237 run in. 238 - **NetworkDisabled** - Boolean value, when true disables networking for the 239 container 240 - **ExposedPorts** - An object mapping ports to an empty object in the form of: 241 `"ExposedPorts": { "<port>/<tcp|udp>: {}" }` 242 - **HostConfig** 243 - **Binds** – A list of bind mounts for this container. Each item is a string in one of these forms: 244 + `host-src:container-dest` to bind-mount a host path into the 245 container. Both `host-src`, and `container-dest` must be an 246 _absolute_ path. 247 + `host-src:container-dest:ro` to make the bind mount read-only 248 inside the container. Both `host-src`, and `container-dest` must be 249 an _absolute_ path. 250 - **Links** - A list of links for the container. Each link entry should be 251 in the form of `container_name:alias`. 252 - **LxcConf** - LXC specific configurations. These configurations only 253 work when using the `lxc` execution driver. 254 - **Memory** - Memory limit in bytes. 255 - **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. 256 You must use this with `memory` and make the swap value larger than `memory`. 257 - **CpuShares** - An integer value containing the container's CPU Shares 258 (ie. the relative weight vs other containers). 259 - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. 260 - **PidMode** - Set the PID (Process) Namespace mode for the container; 261 `"container:<name|id>"`: joins another container's PID namespace 262 `"host"`: use the host's PID namespace inside the container 263 - **PortBindings** - A map of exposed container ports and the host port they 264 should map to. A JSON object in the form 265 `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }` 266 Take note that `port` is specified as a string and not an integer value. 267 - **PublishAllPorts** - Allocates an ephemeral host port for all of a container's 268 exposed ports. Specified as a boolean value. 269 270 Ports are de-allocated when the container stops and allocated when the container starts. 271 The allocated port might be changed when restarting the container. 272 273 The port is selected from the ephemeral port range that depends on the kernel. 274 For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`. 275 - **Privileged** - Gives the container full access to the host. Specified as 276 a boolean value. 277 - **ReadonlyRootfs** - Mount the container's root filesystem as read only. 278 Specified as a boolean value. 279 - **Dns** - A list of DNS servers for the container to use. 280 - **DnsSearch** - A list of DNS search domains 281 - **ExtraHosts** - A list of hostnames/IP mappings to add to the 282 container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. 283 - **VolumesFrom** - A list of volumes to inherit from another container. 284 Specified in the form `<container name>[:<ro|rw>]` 285 - **CapAdd** - A list of kernel capabilities to add to the container. 286 - **Capdrop** - A list of kernel capabilities to drop from the container. 287 - **RestartPolicy** – The behavior to apply when the container exits. The 288 value is an object with a `Name` property of either `"always"` to 289 always restart or `"on-failure"` to restart only when the container 290 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 291 controls the number of times to retry before giving up. 292 The default is not to restart. (optional) 293 An ever increasing delay (double the previous delay, starting at 100mS) 294 is added before each restart to prevent flooding the server. 295 - **NetworkMode** - Sets the networking mode for the container. Supported 296 values are: `bridge`, `host`, `none`, and `container:<name|id>` 297 - **Devices** - A list of devices to add to the container specified as a JSON object in the 298 form 299 `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` 300 - **Ulimits** - A list of ulimits to set in the container, specified as 301 `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example: 302 `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }` 303 - **SecurityOpt**: A list of string values to customize labels for MLS 304 systems, such as SELinux. 305 - **LogConfig** - Log configuration for the container, specified as a JSON object in the form 306 `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`. 307 Available types: `json-file`, `syslog`, `journald`, `none`. 308 `json-file` logging driver. 309 - **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. 310 311 **Query parameters**: 312 313 - **name** – Assign the specified name to the container. Must 314 match `/?[a-zA-Z0-9_-]+`. 315 316 **Status codes**: 317 318 - **201** – no error 319 - **400** – bad parameter 320 - **404** – no such container 321 - **406** – impossible to attach (container not running) 322 - **409** – conflict 323 - **500** – server error 324 325 #### Inspect a container 326 327 `GET /containers/(id or name)/json` 328 329 Return low-level information on the container `id` 330 331 **Example request**: 332 333 GET /v1.18/containers/4fa6e0f0c678/json HTTP/1.1 334 335 **Example response**: 336 337 HTTP/1.1 200 OK 338 Content-Type: application/json 339 340 { 341 "AppArmorProfile": "", 342 "Args": [ 343 "-c", 344 "exit 9" 345 ], 346 "Config": { 347 "AttachStderr": true, 348 "AttachStdin": false, 349 "AttachStdout": true, 350 "Cmd": [ 351 "/bin/sh", 352 "-c", 353 "exit 9" 354 ], 355 "Domainname": "", 356 "Entrypoint": null, 357 "Env": [ 358 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 359 ], 360 "ExposedPorts": null, 361 "Hostname": "ba033ac44011", 362 "Image": "ubuntu", 363 "Labels": { 364 "com.example.vendor": "Acme", 365 "com.example.license": "GPL", 366 "com.example.version": "1.0" 367 }, 368 "MacAddress": "", 369 "NetworkDisabled": false, 370 "OnBuild": null, 371 "OpenStdin": false, 372 "PortSpecs": null, 373 "StdinOnce": false, 374 "Tty": false, 375 "User": "", 376 "Volumes": null, 377 "WorkingDir": "" 378 }, 379 "Created": "2015-01-06T15:47:31.485331387Z", 380 "Driver": "devicemapper", 381 "ExecDriver": "native-0.2", 382 "ExecIDs": null, 383 "HostConfig": { 384 "Binds": null, 385 "CapAdd": null, 386 "CapDrop": null, 387 "ContainerIDFile": "", 388 "CpusetCpus": "", 389 "CpuShares": 0, 390 "Devices": [], 391 "Dns": null, 392 "DnsSearch": null, 393 "ExtraHosts": null, 394 "IpcMode": "", 395 "Links": null, 396 "LxcConf": [], 397 "Memory": 0, 398 "MemorySwap": 0, 399 "NetworkMode": "bridge", 400 "PidMode": "", 401 "PortBindings": {}, 402 "Privileged": false, 403 "ReadonlyRootfs": false, 404 "PublishAllPorts": false, 405 "RestartPolicy": { 406 "MaximumRetryCount": 2, 407 "Name": "on-failure" 408 }, 409 "LogConfig": { 410 "Config": null, 411 "Type": "json-file" 412 }, 413 "SecurityOpt": null, 414 "VolumesFrom": null, 415 "Ulimits": [{}] 416 }, 417 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", 418 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", 419 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 420 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", 421 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", 422 "MountLabel": "", 423 "Name": "/boring_euclid", 424 "NetworkSettings": { 425 "Bridge": "", 426 "Gateway": "", 427 "IPAddress": "", 428 "IPPrefixLen": 0, 429 "MacAddress": "", 430 "PortMapping": null, 431 "Ports": null 432 }, 433 "Path": "/bin/sh", 434 "ProcessLabel": "", 435 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", 436 "RestartCount": 1, 437 "State": { 438 "Error": "", 439 "ExitCode": 9, 440 "FinishedAt": "2015-01-06T15:47:32.080254511Z", 441 "OOMKilled": false, 442 "Paused": false, 443 "Pid": 0, 444 "Restarting": false, 445 "Running": true, 446 "StartedAt": "2015-01-06T15:47:32.072697474Z" 447 }, 448 "Volumes": {}, 449 "VolumesRW": {} 450 } 451 452 **Status codes**: 453 454 - **200** – no error 455 - **404** – no such container 456 - **500** – server error 457 458 #### List processes running inside a container 459 460 `GET /containers/(id or name)/top` 461 462 List processes running inside the container `id`. On Unix systems this 463 is done by running the `ps` command. This endpoint is not 464 supported on Windows. 465 466 **Example request**: 467 468 GET /v1.18/containers/4fa6e0f0c678/top HTTP/1.1 469 470 **Example response**: 471 472 HTTP/1.1 200 OK 473 Content-Type: application/json 474 475 { 476 "Titles" : [ 477 "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" 478 ], 479 "Processes" : [ 480 [ 481 "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" 482 ], 483 [ 484 "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" 485 ] 486 ] 487 } 488 489 **Example request**: 490 491 GET /v1.18/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 492 493 **Example response**: 494 495 HTTP/1.1 200 OK 496 Content-Type: application/json 497 498 { 499 "Titles" : [ 500 "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" 501 ] 502 "Processes" : [ 503 [ 504 "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" 505 ], 506 [ 507 "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" 508 ] 509 ], 510 } 511 512 **Query parameters**: 513 514 - **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` 515 516 **Status codes**: 517 518 - **200** – no error 519 - **404** – no such container 520 - **500** – server error 521 522 #### Get container logs 523 524 `GET /containers/(id or name)/logs` 525 526 Get `stdout` and `stderr` logs from the container ``id`` 527 528 > **Note**: 529 > This endpoint works only for containers with the `json-file` or `journald` logging drivers. 530 531 **Example request**: 532 533 GET /v1.18/containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 534 535 **Example response**: 536 537 HTTP/1.1 101 UPGRADED 538 Content-Type: application/vnd.docker.raw-stream 539 Connection: Upgrade 540 Upgrade: tcp 541 542 {% raw %} 543 {{ STREAM }} 544 {% endraw %} 545 546 **Query parameters**: 547 548 - **follow** – 1/True/true or 0/False/false, return stream. Default `false`. 549 - **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`. 550 - **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`. 551 - **timestamps** – 1/True/true or 0/False/false, print timestamps for 552 every log line. Default `false`. 553 - **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all. 554 555 **Status codes**: 556 557 - **101** – no error, hints proxy about hijacking 558 - **200** – no error, no upgrade header found 559 - **404** – no such container 560 - **500** – server error 561 562 #### Inspect changes on a container's filesystem 563 564 `GET /containers/(id or name)/changes` 565 566 Inspect changes on container `id`'s filesystem 567 568 **Example request**: 569 570 GET /v1.18/containers/4fa6e0f0c678/changes HTTP/1.1 571 572 **Example response**: 573 574 HTTP/1.1 200 OK 575 Content-Type: application/json 576 577 [ 578 { 579 "Path": "/dev", 580 "Kind": 0 581 }, 582 { 583 "Path": "/dev/kmsg", 584 "Kind": 1 585 }, 586 { 587 "Path": "/test", 588 "Kind": 1 589 } 590 ] 591 592 Values for `Kind`: 593 594 - `0`: Modify 595 - `1`: Add 596 - `2`: Delete 597 598 **Status codes**: 599 600 - **200** – no error 601 - **404** – no such container 602 - **500** – server error 603 604 #### Export a container 605 606 `GET /containers/(id or name)/export` 607 608 Export the contents of container `id` 609 610 **Example request**: 611 612 GET /v1.18/containers/4fa6e0f0c678/export HTTP/1.1 613 614 **Example response**: 615 616 HTTP/1.1 200 OK 617 Content-Type: application/octet-stream 618 619 {% raw %} 620 {{ TAR STREAM }} 621 {% endraw %} 622 623 **Status codes**: 624 625 - **200** – no error 626 - **404** – no such container 627 - **500** – server error 628 629 #### Get container stats based on resource usage 630 631 `GET /containers/(id or name)/stats` 632 633 This endpoint returns a live stream of a container's resource usage statistics. 634 635 **Example request**: 636 637 GET /v1.18/containers/redis1/stats HTTP/1.1 638 639 **Example response**: 640 641 HTTP/1.1 200 OK 642 Content-Type: application/json 643 644 { 645 "read" : "2015-01-08T22:57:31.547920715Z", 646 "network" : { 647 "rx_dropped" : 0, 648 "rx_bytes" : 648, 649 "rx_errors" : 0, 650 "tx_packets" : 8, 651 "tx_dropped" : 0, 652 "rx_packets" : 8, 653 "tx_errors" : 0, 654 "tx_bytes" : 648 655 }, 656 "memory_stats" : { 657 "stats" : { 658 "total_pgmajfault" : 0, 659 "cache" : 0, 660 "mapped_file" : 0, 661 "total_inactive_file" : 0, 662 "pgpgout" : 414, 663 "rss" : 6537216, 664 "total_mapped_file" : 0, 665 "writeback" : 0, 666 "unevictable" : 0, 667 "pgpgin" : 477, 668 "total_unevictable" : 0, 669 "pgmajfault" : 0, 670 "total_rss" : 6537216, 671 "total_rss_huge" : 6291456, 672 "total_writeback" : 0, 673 "total_inactive_anon" : 0, 674 "rss_huge" : 6291456, 675 "hierarchical_memory_limit" : 67108864, 676 "total_pgfault" : 964, 677 "total_active_file" : 0, 678 "active_anon" : 6537216, 679 "total_active_anon" : 6537216, 680 "total_pgpgout" : 414, 681 "total_cache" : 0, 682 "inactive_anon" : 0, 683 "active_file" : 0, 684 "pgfault" : 964, 685 "inactive_file" : 0, 686 "total_pgpgin" : 477 687 }, 688 "max_usage" : 6651904, 689 "usage" : 6537216, 690 "failcnt" : 0, 691 "limit" : 67108864 692 }, 693 "blkio_stats" : {}, 694 "cpu_stats" : { 695 "cpu_usage" : { 696 "percpu_usage" : [ 697 16970827, 698 1839451, 699 7107380, 700 10571290 701 ], 702 "usage_in_usermode" : 10000000, 703 "total_usage" : 36488948, 704 "usage_in_kernelmode" : 20000000 705 }, 706 "system_cpu_usage" : 20091722000000000, 707 "throttling_data" : {} 708 } 709 } 710 711 **Status codes**: 712 713 - **200** – no error 714 - **404** – no such container 715 - **500** – server error 716 717 #### Resize a container TTY 718 719 `POST /containers/(id or name)/resize?h=<height>&w=<width>` 720 721 Resize the TTY for container with `id`. You must restart the container for the resize to take effect. 722 723 **Example request**: 724 725 POST /v1.18/containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 726 727 **Example response**: 728 729 HTTP/1.1 200 OK 730 Content-Length: 0 731 Content-Type: text/plain; charset=utf-8 732 733 **Query parameters**: 734 735 - **h** – height of `tty` session 736 - **w** – width 737 738 **Status codes**: 739 740 - **200** – no error 741 - **404** – No such container 742 - **500** – Cannot resize container 743 744 #### Start a container 745 746 `POST /containers/(id or name)/start` 747 748 Start the container `id` 749 750 > **Note**: 751 > For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. 752 > See [create a container](#create-a-container) for details. 753 754 **Example request**: 755 756 POST /v1.18/containers/e90e34656806/start HTTP/1.1 757 758 **Example response**: 759 760 HTTP/1.1 204 No Content 761 762 **Status codes**: 763 764 - **204** – no error 765 - **304** – container already started 766 - **404** – no such container 767 - **500** – server error 768 769 #### Stop a container 770 771 `POST /containers/(id or name)/stop` 772 773 Stop the container `id` 774 775 **Example request**: 776 777 POST /v1.18/containers/e90e34656806/stop?t=5 HTTP/1.1 778 779 **Example response**: 780 781 HTTP/1.1 204 No Content 782 783 **Query parameters**: 784 785 - **t** – number of seconds to wait before killing the container 786 787 **Status codes**: 788 789 - **204** – no error 790 - **304** – container already stopped 791 - **404** – no such container 792 - **500** – server error 793 794 #### Restart a container 795 796 `POST /containers/(id or name)/restart` 797 798 Restart the container `id` 799 800 **Example request**: 801 802 POST /v1.18/containers/e90e34656806/restart?t=5 HTTP/1.1 803 804 **Example response**: 805 806 HTTP/1.1 204 No Content 807 808 **Query parameters**: 809 810 - **t** – number of seconds to wait before killing the container 811 812 **Status codes**: 813 814 - **204** – no error 815 - **404** – no such container 816 - **500** – server error 817 818 #### Kill a container 819 820 `POST /containers/(id or name)/kill` 821 822 Kill the container `id` 823 824 **Example request**: 825 826 POST /v1.18/containers/e90e34656806/kill HTTP/1.1 827 828 **Example response**: 829 830 HTTP/1.1 204 No Content 831 832 **Query parameters**: 833 834 - **signal** - Signal to send to the container: integer or string like `SIGINT`. 835 When not set, `SIGKILL` is assumed and the call waits for the container to exit. 836 837 **Status codes**: 838 839 - **204** – no error 840 - **404** – no such container 841 - **500** – server error 842 843 #### Rename a container 844 845 `POST /containers/(id or name)/rename` 846 847 Rename the container `id` to a `new_name` 848 849 **Example request**: 850 851 POST /v1.18/containers/e90e34656806/rename?name=new_name HTTP/1.1 852 853 **Example response**: 854 855 HTTP/1.1 204 No Content 856 857 **Query parameters**: 858 859 - **name** – new name for the container 860 861 **Status codes**: 862 863 - **204** – no error 864 - **404** – no such container 865 - **409** - conflict name already assigned 866 - **500** – server error 867 868 #### Pause a container 869 870 `POST /containers/(id or name)/pause` 871 872 Pause the container `id` 873 874 **Example request**: 875 876 POST /v1.18/containers/e90e34656806/pause HTTP/1.1 877 878 **Example response**: 879 880 HTTP/1.1 204 No Content 881 882 **Status codes**: 883 884 - **204** – no error 885 - **404** – no such container 886 - **500** – server error 887 888 #### Unpause a container 889 890 `POST /containers/(id or name)/unpause` 891 892 Unpause the container `id` 893 894 **Example request**: 895 896 POST /v1.18/containers/e90e34656806/unpause HTTP/1.1 897 898 **Example response**: 899 900 HTTP/1.1 204 No Content 901 902 **Status codes**: 903 904 - **204** – no error 905 - **404** – no such container 906 - **500** – server error 907 908 #### Attach to a container 909 910 `POST /containers/(id or name)/attach` 911 912 Attach to the container `id` 913 914 **Example request**: 915 916 POST /v1.18/containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 917 918 **Example response**: 919 920 HTTP/1.1 101 UPGRADED 921 Content-Type: application/vnd.docker.raw-stream 922 Connection: Upgrade 923 Upgrade: tcp 924 925 {% raw %} 926 {{ STREAM }} 927 {% endraw %} 928 929 **Query parameters**: 930 931 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 932 - **stream** – 1/True/true or 0/False/false, return stream. 933 Default `false`. 934 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 935 to `stdin`. Default `false`. 936 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 937 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 938 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 939 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 940 941 **Status codes**: 942 943 - **101** – no error, hints proxy about hijacking 944 - **200** – no error, no upgrade header found 945 - **400** – bad parameter 946 - **404** – no such container 947 - **500** – server error 948 949 **Stream details**: 950 951 When using the TTY setting is enabled in 952 [`POST /containers/create` 953 ](#create-a-container), 954 the stream is the raw data from the process PTY and client's `stdin`. 955 When the TTY is disabled, then the stream is multiplexed to separate 956 `stdout` and `stderr`. 957 958 The format is a **Header** and a **Payload** (frame). 959 960 **HEADER** 961 962 The header contains the information which the stream writes (`stdout` or 963 `stderr`). It also contains the size of the associated frame encoded in the 964 last four bytes (`uint32`). 965 966 It is encoded on the first eight bytes like this: 967 968 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 969 970 `STREAM_TYPE` can be: 971 972 - 0: `stdin` (is written on `stdout`) 973 - 1: `stdout` 974 - 2: `stderr` 975 976 `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of 977 the `uint32` size encoded as big endian. 978 979 **PAYLOAD** 980 981 The payload is the raw stream. 982 983 **IMPLEMENTATION** 984 985 The simplest way to implement the Attach protocol is the following: 986 987 1. Read eight bytes. 988 2. Choose `stdout` or `stderr` depending on the first byte. 989 3. Extract the frame size from the last four bytes. 990 4. Read the extracted size and output it on the correct output. 991 5. Goto 1. 992 993 #### Attach to a container (websocket) 994 995 `GET /containers/(id or name)/attach/ws` 996 997 Attach to the container `id` via websocket 998 999 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 1000 1001 **Example request** 1002 1003 GET /v1.18/containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 1004 1005 **Example response** 1006 1007 {% raw %} 1008 {{ STREAM }} 1009 {% endraw %} 1010 1011 **Query parameters**: 1012 1013 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1014 - **stream** – 1/True/true or 0/False/false, return stream. 1015 Default `false`. 1016 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1017 to `stdin`. Default `false`. 1018 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1019 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1020 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1021 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1022 1023 **Status codes**: 1024 1025 - **200** – no error 1026 - **400** – bad parameter 1027 - **404** – no such container 1028 - **500** – server error 1029 1030 #### Wait a container 1031 1032 `POST /containers/(id or name)/wait` 1033 1034 Block until container `id` stops, then returns the exit code 1035 1036 **Example request**: 1037 1038 POST /v1.18/containers/16253994b7c4/wait HTTP/1.1 1039 1040 **Example response**: 1041 1042 HTTP/1.1 200 OK 1043 Content-Type: application/json 1044 1045 {"StatusCode": 0} 1046 1047 **Status codes**: 1048 1049 - **200** – no error 1050 - **404** – no such container 1051 - **500** – server error 1052 1053 #### Remove a container 1054 1055 `DELETE /containers/(id or name)` 1056 1057 Remove the container `id` from the filesystem 1058 1059 **Example request**: 1060 1061 DELETE /v1.18/containers/16253994b7c4?v=1 HTTP/1.1 1062 1063 **Example response**: 1064 1065 HTTP/1.1 204 No Content 1066 1067 **Query parameters**: 1068 1069 - **v** – 1/True/true or 0/False/false, Remove the volumes 1070 associated to the container. Default `false`. 1071 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 1072 Default `false`. 1073 - **link** - 1/True/true or 0/False/false, Remove the specified 1074 link associated to the container. Default `false`. 1075 1076 **Status codes**: 1077 1078 - **204** – no error 1079 - **400** – bad parameter 1080 - **404** – no such container 1081 - **409** – conflict 1082 - **500** – server error 1083 1084 #### Copy files or folders from a container 1085 1086 `POST /containers/(id or name)/copy` 1087 1088 Copy files or folders of container `id` 1089 1090 **Example request**: 1091 1092 POST /v1.18/containers/4fa6e0f0c678/copy HTTP/1.1 1093 Content-Type: application/json 1094 Content-Length: 12345 1095 1096 { 1097 "Resource": "test.txt" 1098 } 1099 1100 **Example response**: 1101 1102 HTTP/1.1 200 OK 1103 Content-Type: application/x-tar 1104 1105 {% raw %} 1106 {{ TAR STREAM }} 1107 {% endraw %} 1108 1109 **Status codes**: 1110 1111 - **200** – no error 1112 - **404** – no such container 1113 - **500** – server error 1114 1115 ### 2.2 Images 1116 1117 #### List Images 1118 1119 `GET /images/json` 1120 1121 **Example request**: 1122 1123 GET /v1.18/images/json?all=0 HTTP/1.1 1124 1125 **Example response**: 1126 1127 HTTP/1.1 200 OK 1128 Content-Type: application/json 1129 1130 [ 1131 { 1132 "RepoTags": [ 1133 "ubuntu:12.04", 1134 "ubuntu:precise", 1135 "ubuntu:latest" 1136 ], 1137 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1138 "Created": 1365714795, 1139 "Size": 131506275, 1140 "VirtualSize": 131506275 1141 }, 1142 { 1143 "RepoTags": [ 1144 "ubuntu:12.10", 1145 "ubuntu:quantal" 1146 ], 1147 "ParentId": "27cf784147099545", 1148 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1149 "Created": 1364102658, 1150 "Size": 24653, 1151 "VirtualSize": 180116135 1152 } 1153 ] 1154 1155 **Example request, with digest information**: 1156 1157 GET /v1.18/images/json?digests=1 HTTP/1.1 1158 1159 **Example response, with digest information**: 1160 1161 HTTP/1.1 200 OK 1162 Content-Type: application/json 1163 1164 [ 1165 { 1166 "Created": 1420064636, 1167 "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", 1168 "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", 1169 "RepoDigests": [ 1170 "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1171 ], 1172 "RepoTags": [ 1173 "localhost:5000/test/busybox:latest", 1174 "playdate:latest" 1175 ], 1176 "Size": 0, 1177 "VirtualSize": 2429728 1178 } 1179 ] 1180 1181 The response shows a single image `Id` associated with two repositories 1182 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use 1183 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or 1184 `playdate:latest` to reference the image. 1185 1186 You can also use `RepoDigests` values to reference an image. In this response, 1187 the array has only one reference and that is to the 1188 `localhost:5000/test/busybox` repository; the `playdate` repository has no 1189 digest. You can reference this digest using the value: 1190 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` 1191 1192 See the `docker run` and `docker build` commands for examples of digest and tag 1193 references on the command line. 1194 1195 **Query parameters**: 1196 1197 - **all** – 1/True/true or 0/False/false, default false 1198 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1199 - `dangling=true` 1200 - `label=key` or `label="key=value"` of an image label 1201 - **filter** - only return images with the specified name 1202 1203 #### Build image from a Dockerfile 1204 1205 `POST /build` 1206 1207 Build an image from a Dockerfile 1208 1209 **Example request**: 1210 1211 POST /v1.18/build HTTP/1.1 1212 Content-Type: application/x-tar 1213 1214 {% raw %} 1215 {{ TAR STREAM }} 1216 {% endraw %} 1217 1218 **Example response**: 1219 1220 HTTP/1.1 200 OK 1221 Content-Type: application/json 1222 1223 {"stream": "Step 1/5..."} 1224 {"stream": "..."} 1225 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1226 1227 The input stream must be a `tar` archive compressed with one of the 1228 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. 1229 1230 The archive must include a build instructions file, typically called 1231 `Dockerfile` at the archive's root. The `dockerfile` parameter may be 1232 used to specify a different build instructions file. To do this, its value must be 1233 the path to the alternate build instructions file to use. 1234 1235 The archive may include any number of other files, 1236 which are accessible in the build context (See the [*ADD build 1237 command*](https://docs.docker.com/engine/reference/builder/#add)). 1238 1239 The Docker daemon performs a preliminary validation of the `Dockerfile` before 1240 starting the build, and returns an error if the syntax is incorrect. After that, 1241 each instruction is run one-by-one until the ID of the new image is output. 1242 1243 The build is canceled if the client drops the connection by quitting 1244 or being killed. 1245 1246 **Query parameters**: 1247 1248 - **dockerfile** - Path within the build context to the Dockerfile. This is 1249 ignored if `remote` is specified and points to an individual filename. 1250 - **t** – A name and optional tag to apply to the image in the `name:tag` format. 1251 If you omit the `tag` the default `latest` value is assumed. 1252 - **remote** – A Git repository URI or HTTP/HTTPS context URI. If the 1253 URI points to a single text file, the file's contents are placed into 1254 a file called `Dockerfile` and the image is built from that file. 1255 - **q** – Suppress verbose build output. 1256 - **nocache** – Do not use the cache when building the image. 1257 - **pull** - Attempt to pull the image even if an older image exists locally. 1258 - **rm** - Remove intermediate containers after a successful build (default behavior). 1259 - **forcerm** - Always remove intermediate containers (includes `rm`). 1260 - **memory** - Set memory limit for build. 1261 - **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap. 1262 - **cpushares** - CPU shares (relative weight). 1263 - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). 1264 1265 **Request Headers**: 1266 1267 - **Content-type** – Set to `"application/x-tar"`. 1268 - **X-Registry-Config** – base64-encoded ConfigFile object 1269 1270 **Status codes**: 1271 1272 - **200** – no error 1273 - **500** – server error 1274 1275 #### Create an image 1276 1277 `POST /images/create` 1278 1279 Create an image either by pulling it from the registry or by importing it 1280 1281 **Example request**: 1282 1283 POST /v1.18/images/create?fromImage=busybox&tag=latest HTTP/1.1 1284 1285 **Example response**: 1286 1287 HTTP/1.1 200 OK 1288 Content-Type: application/json 1289 1290 {"status": "Pulling..."} 1291 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1292 {"error": "Invalid..."} 1293 ... 1294 1295 When using this endpoint to pull an image from the registry, the 1296 `X-Registry-Auth` header can be used to include 1297 a base64-encoded AuthConfig object. 1298 1299 **Query parameters**: 1300 1301 - **fromImage** – Name of the image to pull. 1302 - **fromSrc** – Source to import. The value may be a URL from which the image 1303 can be retrieved or `-` to read the image from the request body. 1304 - **repo** – Repository name. 1305 - **tag** – Tag. If empty when pulling an image, this causes all tags 1306 for the given image to be pulled. 1307 1308 **Request Headers**: 1309 1310 - **X-Registry-Auth** – base64-encoded AuthConfig object 1311 1312 **Status codes**: 1313 1314 - **200** – no error 1315 - **404** - repository does not exist or no read access 1316 - **500** – server error 1317 1318 1319 1320 #### Inspect an image 1321 1322 `GET /images/(name)/json` 1323 1324 Return low-level information on the image `name` 1325 1326 **Example request**: 1327 1328 GET /v1.18/images/ubuntu/json HTTP/1.1 1329 1330 **Example response**: 1331 1332 HTTP/1.1 200 OK 1333 Content-Type: application/json 1334 1335 { 1336 "Created": "2013-03-23T22:24:18.818426-07:00", 1337 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 1338 "ContainerConfig": { 1339 "Hostname": "", 1340 "User": "", 1341 "AttachStdin": false, 1342 "AttachStdout": false, 1343 "AttachStderr": false, 1344 "Tty": true, 1345 "OpenStdin": true, 1346 "StdinOnce": false, 1347 "Env": null, 1348 "Cmd": ["/bin/bash"], 1349 "Dns": null, 1350 "Image": "ubuntu", 1351 "Labels": { 1352 "com.example.vendor": "Acme", 1353 "com.example.license": "GPL", 1354 "com.example.version": "1.0" 1355 }, 1356 "Volumes": null, 1357 "VolumesFrom": "", 1358 "WorkingDir": "" 1359 }, 1360 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1361 "Parent": "27cf784147099545", 1362 "Size": 6824592 1363 } 1364 1365 **Status codes**: 1366 1367 - **200** – no error 1368 - **404** – no such image 1369 - **500** – server error 1370 1371 #### Get the history of an image 1372 1373 `GET /images/(name)/history` 1374 1375 Return the history of the image `name` 1376 1377 **Example request**: 1378 1379 GET /v1.18/images/ubuntu/history HTTP/1.1 1380 1381 **Example response**: 1382 1383 HTTP/1.1 200 OK 1384 Content-Type: application/json 1385 1386 [ 1387 { 1388 "Id": "b750fe79269d", 1389 "Created": 1364102658, 1390 "CreatedBy": "/bin/bash" 1391 }, 1392 { 1393 "Id": "27cf78414709", 1394 "Created": 1364068391, 1395 "CreatedBy": "" 1396 } 1397 ] 1398 1399 **Status codes**: 1400 1401 - **200** – no error 1402 - **404** – no such image 1403 - **500** – server error 1404 1405 #### Push an image on the registry 1406 1407 `POST /images/(name)/push` 1408 1409 Push the image `name` on the registry 1410 1411 **Example request**: 1412 1413 POST /v1.18/images/test/push HTTP/1.1 1414 1415 **Example response**: 1416 1417 HTTP/1.1 200 OK 1418 Content-Type: application/json 1419 1420 {"status": "Pushing..."} 1421 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1422 {"error": "Invalid..."} 1423 ... 1424 1425 If you wish to push an image on to a private registry, that image must already have a tag 1426 into a repository which references that registry `hostname` and `port`. This repository name should 1427 then be used in the URL. This duplicates the command line's flow. 1428 1429 **Example request**: 1430 1431 POST /v1.18/images/registry.acme.com:5000/test/push HTTP/1.1 1432 1433 1434 **Query parameters**: 1435 1436 - **tag** – The tag to associate with the image on the registry. This is optional. 1437 1438 **Request Headers**: 1439 1440 - **X-Registry-Auth** – base64-encoded AuthConfig object. 1441 1442 **Status codes**: 1443 1444 - **200** – no error 1445 - **404** – no such image 1446 - **500** – server error 1447 1448 #### Tag an image into a repository 1449 1450 `POST /images/(name)/tag` 1451 1452 Tag the image `name` into a repository 1453 1454 **Example request**: 1455 1456 POST /v1.18/images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 1457 1458 **Example response**: 1459 1460 HTTP/1.1 201 Created 1461 1462 **Query parameters**: 1463 1464 - **repo** – The repository to tag in 1465 - **force** – 1/True/true or 0/False/false, default false 1466 - **tag** - The new tag name 1467 1468 **Status codes**: 1469 1470 - **201** – no error 1471 - **400** – bad parameter 1472 - **404** – no such image 1473 - **409** – conflict 1474 - **500** – server error 1475 1476 #### Remove an image 1477 1478 `DELETE /images/(name)` 1479 1480 Remove the image `name` from the filesystem 1481 1482 **Example request**: 1483 1484 DELETE /v1.18/images/test HTTP/1.1 1485 1486 **Example response**: 1487 1488 HTTP/1.1 200 OK 1489 Content-type: application/json 1490 1491 [ 1492 {"Untagged": "3e2f21a89f"}, 1493 {"Deleted": "3e2f21a89f"}, 1494 {"Deleted": "53b4f83ac9"} 1495 ] 1496 1497 **Query parameters**: 1498 1499 - **force** – 1/True/true or 0/False/false, default false 1500 - **noprune** – 1/True/true or 0/False/false, default false 1501 1502 **Status codes**: 1503 1504 - **200** – no error 1505 - **404** – no such image 1506 - **409** – conflict 1507 - **500** – server error 1508 1509 #### Search images 1510 1511 `GET /images/search` 1512 1513 Search for an image on [Docker Hub](https://hub.docker.com). 1514 1515 > **Note**: 1516 > The response keys have changed from API v1.6 to reflect the JSON 1517 > sent by the registry server to the docker daemon's request. 1518 1519 **Example request**: 1520 1521 GET /v1.18/images/search?term=sshd HTTP/1.1 1522 1523 **Example response**: 1524 1525 HTTP/1.1 200 OK 1526 Content-Type: application/json 1527 1528 [ 1529 { 1530 "star_count": 12, 1531 "is_official": false, 1532 "name": "wma55/u1210sshd", 1533 "is_automated": false, 1534 "description": "" 1535 }, 1536 { 1537 "star_count": 10, 1538 "is_official": false, 1539 "name": "jdswinbank/sshd", 1540 "is_automated": false, 1541 "description": "" 1542 }, 1543 { 1544 "star_count": 18, 1545 "is_official": false, 1546 "name": "vgauthier/sshd", 1547 "is_automated": false, 1548 "description": "" 1549 } 1550 ... 1551 ] 1552 1553 **Query parameters**: 1554 1555 - **term** – term to search 1556 1557 **Status codes**: 1558 1559 - **200** – no error 1560 - **500** – server error 1561 1562 ### 2.3 Misc 1563 1564 #### Check auth configuration 1565 1566 `POST /auth` 1567 1568 Get the default username and email 1569 1570 **Example request**: 1571 1572 POST /v1.18/auth HTTP/1.1 1573 Content-Type: application/json 1574 Content-Length: 12345 1575 1576 { 1577 "username": "hannibal", 1578 "password": "xxxx", 1579 "email": "hannibal@a-team.com", 1580 "serveraddress": "https://index.docker.io/v1/" 1581 } 1582 1583 **Example response**: 1584 1585 HTTP/1.1 200 OK 1586 1587 **Status codes**: 1588 1589 - **200** – no error 1590 - **204** – no error 1591 - **500** – server error 1592 1593 #### Display system-wide information 1594 1595 `GET /info` 1596 1597 Display system-wide information 1598 1599 **Example request**: 1600 1601 GET /v1.18/info HTTP/1.1 1602 1603 **Example response**: 1604 1605 HTTP/1.1 200 OK 1606 Content-Type: application/json 1607 1608 { 1609 "Containers": 11, 1610 "Debug": 0, 1611 "DockerRootDir": "/var/lib/docker", 1612 "Driver": "btrfs", 1613 "DriverStatus": [[""]], 1614 "ExecutionDriver": "native-0.1", 1615 "HttpProxy": "http://test:test@localhost:8080", 1616 "HttpsProxy": "https://test:test@localhost:8080", 1617 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 1618 "IPv4Forwarding": 1, 1619 "Images": 16, 1620 "IndexServerAddress": "https://index.docker.io/v1/", 1621 "InitPath": "/usr/bin/docker", 1622 "InitSha1": "", 1623 "KernelVersion": "3.12.0-1-amd64", 1624 "Labels": [ 1625 "storage=ssd" 1626 ], 1627 "MemTotal": 2099236864, 1628 "MemoryLimit": 1, 1629 "NCPU": 1, 1630 "NEventsListener": 0, 1631 "NFd": 11, 1632 "NGoroutines": 21, 1633 "Name": "prod-server-42", 1634 "NoProxy": "9.81.1.160", 1635 "OperatingSystem": "Boot2Docker", 1636 "RegistryConfig": { 1637 "IndexConfigs": { 1638 "docker.io": { 1639 "Mirrors": null, 1640 "Name": "docker.io", 1641 "Official": true, 1642 "Secure": true 1643 } 1644 }, 1645 "InsecureRegistryCIDRs": [ 1646 "127.0.0.0/8" 1647 ] 1648 }, 1649 "SwapLimit": 0, 1650 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 1651 } 1652 1653 **Status codes**: 1654 1655 - **200** – no error 1656 - **500** – server error 1657 1658 #### Show the docker version information 1659 1660 `GET /version` 1661 1662 Show the docker version information 1663 1664 **Example request**: 1665 1666 GET /v1.18/version HTTP/1.1 1667 1668 **Example response**: 1669 1670 HTTP/1.1 200 OK 1671 Content-Type: application/json 1672 1673 { 1674 "Version": "1.5.0", 1675 "Os": "linux", 1676 "KernelVersion": "3.18.5-tinycore64", 1677 "GoVersion": "go1.4.1", 1678 "GitCommit": "a8a31ef", 1679 "Arch": "amd64", 1680 "ApiVersion": "1.18" 1681 } 1682 1683 **Status codes**: 1684 1685 - **200** – no error 1686 - **500** – server error 1687 1688 #### Ping the docker server 1689 1690 `GET /_ping` 1691 1692 Ping the docker server 1693 1694 **Example request**: 1695 1696 GET /v1.18/_ping HTTP/1.1 1697 1698 **Example response**: 1699 1700 HTTP/1.1 200 OK 1701 Content-Type: text/plain 1702 1703 OK 1704 1705 **Status codes**: 1706 1707 - **200** - no error 1708 - **500** - server error 1709 1710 #### Create a new image from a container's changes 1711 1712 `POST /commit` 1713 1714 Create a new image from a container's changes 1715 1716 **Example request**: 1717 1718 POST /v1.18/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1719 Content-Type: application/json 1720 Content-Length: 12345 1721 1722 { 1723 "Hostname": "", 1724 "Domainname": "", 1725 "User": "", 1726 "AttachStdin": false, 1727 "AttachStdout": true, 1728 "AttachStderr": true, 1729 "PortSpecs": null, 1730 "Tty": false, 1731 "OpenStdin": false, 1732 "StdinOnce": false, 1733 "Env": null, 1734 "Cmd": [ 1735 "date" 1736 ], 1737 "Volumes": { 1738 "/tmp": {} 1739 }, 1740 "WorkingDir": "", 1741 "NetworkDisabled": false, 1742 "ExposedPorts": { 1743 "22/tcp": {} 1744 } 1745 } 1746 1747 **Example response**: 1748 1749 HTTP/1.1 201 Created 1750 Content-Type: application/json 1751 1752 {"Id": "596069db4bf5"} 1753 1754 **JSON parameters**: 1755 1756 - **config** - the container's configuration 1757 1758 **Query parameters**: 1759 1760 - **container** – source container 1761 - **repo** – repository 1762 - **tag** – tag 1763 - **comment** – commit message 1764 - **author** – author (e.g., "John Hannibal Smith 1765 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1766 1767 **Status codes**: 1768 1769 - **201** – no error 1770 - **404** – no such container 1771 - **500** – server error 1772 1773 #### Monitor Docker's events 1774 1775 `GET /events` 1776 1777 Get container events from docker, in real time via streaming. 1778 1779 Docker containers report the following events: 1780 1781 create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause 1782 1783 Docker images report the following events: 1784 1785 untag, delete 1786 1787 **Example request**: 1788 1789 GET /v1.18/events?since=1374067924 1790 1791 **Example response**: 1792 1793 HTTP/1.1 200 OK 1794 Content-Type: application/json 1795 1796 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1797 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1798 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1799 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1800 1801 **Query parameters**: 1802 1803 - **since** – Timestamp. Show all events created since timestamp and then stream 1804 - **until** – Timestamp. Show events created until given timestamp and stop streaming 1805 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 1806 - `container=<string>`; -- container to filter 1807 - `event=<string>`; -- event to filter 1808 - `image=<string>`; -- image to filter 1809 1810 **Status codes**: 1811 1812 - **200** – no error 1813 - **500** – server error 1814 1815 #### Get a tarball containing all images in a repository 1816 1817 `GET /images/(name)/get` 1818 1819 Get a tarball containing all images and metadata for the repository specified 1820 by `name`. 1821 1822 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 1823 (and its parents) are returned. If `name` is an image ID, similarly only that 1824 image (and its parents) are returned, but with the exclusion of the 1825 'repositories' file in the tarball, as there were no image names referenced. 1826 1827 See the [image tarball format](#image-tarball-format) for more details. 1828 1829 **Example request** 1830 1831 GET /v1.18/images/ubuntu/get 1832 1833 **Example response**: 1834 1835 HTTP/1.1 200 OK 1836 Content-Type: application/x-tar 1837 1838 Binary data stream 1839 1840 **Status codes**: 1841 1842 - **200** – no error 1843 - **500** – server error 1844 1845 #### Get a tarball containing all images 1846 1847 `GET /images/get` 1848 1849 Get a tarball containing all images and metadata for one or more repositories. 1850 1851 For each value of the `names` parameter: if it is a specific name and tag (e.g. 1852 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 1853 an image ID, similarly only that image (and its parents) are returned and there 1854 would be no names referenced in the 'repositories' file for this image ID. 1855 1856 See the [image tarball format](#image-tarball-format) for more details. 1857 1858 **Example request** 1859 1860 GET /v1.18/images/get?names=myname%2Fmyapp%3Alatest&names=busybox 1861 1862 **Example response**: 1863 1864 HTTP/1.1 200 OK 1865 Content-Type: application/x-tar 1866 1867 Binary data stream 1868 1869 **Status codes**: 1870 1871 - **200** – no error 1872 - **500** – server error 1873 1874 #### Load a tarball with a set of images and tags into docker 1875 1876 `POST /images/load` 1877 1878 Load a set of images and tags into a Docker repository. 1879 See the [image tarball format](#image-tarball-format) for more details. 1880 1881 **Example request** 1882 1883 POST /v1.18/images/load 1884 Content-Type: application/x-tar 1885 Content-Length: 12345 1886 1887 Tarball in body 1888 1889 **Example response**: 1890 1891 HTTP/1.1 200 OK 1892 1893 **Status codes**: 1894 1895 - **200** – no error 1896 - **500** – server error 1897 1898 #### Image tarball format 1899 1900 An image tarball contains one directory per image layer (named using its long ID), 1901 each containing these files: 1902 1903 - `VERSION`: currently `1.0` - the file format version 1904 - `json`: detailed layer information, similar to `docker inspect layer_id` 1905 - `layer.tar`: A tarfile containing the filesystem changes in this layer 1906 1907 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 1908 for storing attribute changes and deletions. 1909 1910 If the tarball defines a repository, the tarball should also include a `repositories` file at 1911 the root that contains a list of repository and tag names mapped to layer IDs. 1912 1913 ``` 1914 {"hello-world": 1915 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1916 } 1917 ``` 1918 1919 #### Exec Create 1920 1921 `POST /containers/(id or name)/exec` 1922 1923 Sets up an exec instance in a running container `id` 1924 1925 **Example request**: 1926 1927 POST /v1.18/containers/e90e34656806/exec HTTP/1.1 1928 Content-Type: application/json 1929 Content-Length: 12345 1930 1931 { 1932 "AttachStdin": true, 1933 "AttachStdout": true, 1934 "AttachStderr": true, 1935 "Cmd": ["sh"], 1936 "Tty": true 1937 } 1938 1939 **Example response**: 1940 1941 HTTP/1.1 201 Created 1942 Content-Type: application/json 1943 1944 { 1945 "Id": "f90e34656806", 1946 "Warnings":[] 1947 } 1948 1949 **JSON parameters**: 1950 1951 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 1952 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 1953 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 1954 - **Tty** - Boolean value to allocate a pseudo-TTY. 1955 - **Cmd** - Command to run specified as a string or an array of strings. 1956 1957 1958 **Status codes**: 1959 1960 - **201** – no error 1961 - **404** – no such container 1962 1963 #### Exec Start 1964 1965 `POST /exec/(id)/start` 1966 1967 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 1968 returns after starting the `exec` command. Otherwise, this API sets up an 1969 interactive session with the `exec` command. 1970 1971 **Example request**: 1972 1973 POST /v1.18/exec/e90e34656806/start HTTP/1.1 1974 Content-Type: application/json 1975 Content-Length: 12345 1976 1977 { 1978 "Detach": false, 1979 "Tty": false 1980 } 1981 1982 **Example response**: 1983 1984 HTTP/1.1 200 OK 1985 Content-Type: application/vnd.docker.raw-stream 1986 1987 {% raw %} 1988 {{ STREAM }} 1989 {% endraw %} 1990 1991 **JSON parameters**: 1992 1993 - **Detach** - Detach from the `exec` command. 1994 - **Tty** - Boolean value to allocate a pseudo-TTY. 1995 1996 **Status codes**: 1997 1998 - **200** – no error 1999 - **404** – no such exec instance 2000 2001 **Stream details**: 2002 2003 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2004 2005 #### Exec Resize 2006 2007 `POST /exec/(id)/resize` 2008 2009 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2010 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2011 2012 **Example request**: 2013 2014 POST /v1.18/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2015 Content-Type: text/plain 2016 2017 **Example response**: 2018 2019 HTTP/1.1 201 Created 2020 Content-Type: text/plain 2021 2022 **Query parameters**: 2023 2024 - **h** – height of `tty` session 2025 - **w** – width 2026 2027 **Status codes**: 2028 2029 - **201** – no error 2030 - **404** – no such exec instance 2031 2032 #### Exec Inspect 2033 2034 `GET /exec/(id)/json` 2035 2036 Return low-level information about the `exec` command `id`. 2037 2038 **Example request**: 2039 2040 GET /v1.18/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2041 2042 **Example response**: 2043 2044 HTTP/1.1 200 OK 2045 Content-Type: plain/text 2046 2047 { 2048 "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", 2049 "Running" : false, 2050 "ExitCode" : 2, 2051 "ProcessConfig" : { 2052 "privileged" : false, 2053 "user" : "", 2054 "tty" : false, 2055 "entrypoint" : "sh", 2056 "arguments" : [ 2057 "-c", 2058 "exit 2" 2059 ] 2060 }, 2061 "OpenStdin" : false, 2062 "OpenStderr" : false, 2063 "OpenStdout" : false, 2064 "Container" : { 2065 "State" : { 2066 "Running" : true, 2067 "Paused" : false, 2068 "Restarting" : false, 2069 "OOMKilled" : false, 2070 "Pid" : 3650, 2071 "ExitCode" : 0, 2072 "Error" : "", 2073 "StartedAt" : "2014-11-17T22:26:03.717657531Z", 2074 "FinishedAt" : "0001-01-01T00:00:00Z" 2075 }, 2076 "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", 2077 "Created" : "2014-11-17T22:26:03.626304998Z", 2078 "Path" : "date", 2079 "Args" : [], 2080 "Config" : { 2081 "Hostname" : "8f177a186b97", 2082 "Domainname" : "", 2083 "User" : "", 2084 "AttachStdin" : false, 2085 "AttachStdout" : false, 2086 "AttachStderr" : false, 2087 "PortSpecs": null, 2088 "ExposedPorts" : null, 2089 "Tty" : false, 2090 "OpenStdin" : false, 2091 "StdinOnce" : false, 2092 "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], 2093 "Cmd" : [ 2094 "date" 2095 ], 2096 "Image" : "ubuntu", 2097 "Volumes" : null, 2098 "WorkingDir" : "", 2099 "Entrypoint" : null, 2100 "NetworkDisabled" : false, 2101 "MacAddress" : "", 2102 "OnBuild" : null, 2103 "SecurityOpt" : null 2104 }, 2105 "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", 2106 "NetworkSettings" : { 2107 "IPAddress" : "172.17.0.2", 2108 "IPPrefixLen" : 16, 2109 "MacAddress" : "02:42:ac:11:00:02", 2110 "Gateway" : "172.17.42.1", 2111 "Bridge" : "docker0", 2112 "PortMapping" : null, 2113 "Ports" : {} 2114 }, 2115 "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", 2116 "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", 2117 "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", 2118 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 2119 "Name" : "/test", 2120 "Driver" : "aufs", 2121 "ExecDriver" : "native-0.2", 2122 "MountLabel" : "", 2123 "ProcessLabel" : "", 2124 "AppArmorProfile" : "", 2125 "RestartCount" : 0, 2126 "Volumes" : {}, 2127 "VolumesRW" : {} 2128 } 2129 } 2130 2131 **Status codes**: 2132 2133 - **200** – no error 2134 - **404** – no such exec instance 2135 - **500** - server error 2136 2137 ## 3. Going further 2138 2139 ### 3.1 Inside `docker run` 2140 2141 As an example, the `docker run` command line makes the following API calls: 2142 2143 - Create the container 2144 2145 - If the status code is 404, it means the image doesn't exist: 2146 - Try to pull it. 2147 - Then, retry to create the container. 2148 2149 - Start the container. 2150 2151 - If you are not in detached mode: 2152 - Attach to the container, using `logs=1` (to have `stdout` and 2153 `stderr` from the container's start) and `stream=1` 2154 2155 - If in detached mode or only `stdin` is attached, display the container's id. 2156 2157 ### 3.2 Hijacking 2158 2159 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 2160 `stdout`, and `stderr` on the same socket. 2161 2162 To hint potential proxies about connection hijacking, Docker client sends 2163 connection upgrade headers similarly to websocket. 2164 2165 Upgrade: tcp 2166 Connection: Upgrade 2167 2168 When Docker daemon detects the `Upgrade` header, it switches its status code 2169 from **200 OK** to **101 UPGRADED** and resends the same headers. 2170 2171 This might change in the future. 2172 2173 ### 3.3 CORS Requests 2174 2175 To set cross origin requests to the Engine API please give values to 2176 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 2177 default or blank means CORS disabled 2178 2179 $ docker -d -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"