github.com/45cali/docker@v1.11.1/docs/reference/api/docker_remote_api_v1.14.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Remote API v1.14" 4 description = "API Documentation for Docker" 5 keywords = ["API, Docker, rcli, REST, documentation"] 6 [menu.main] 7 parent = "engine_remoteapi" 8 weight = 7 9 +++ 10 <![end-metadata]--> 11 12 # Docker Remote API v1.14 13 14 ## 1. Brief introduction 15 16 - The Remote API has replaced `rcli`. 17 - The daemon listens on `unix:///var/run/docker.sock` but you can 18 [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). 19 - The API tends to be REST, but for some complex commands, like `attach` 20 or `pull`, the HTTP connection is hijacked to transport `STDOUT`, 21 `STDIN` and `STDERR`. 22 23 # 2. Endpoints 24 25 ## 2.1 Containers 26 27 ### List containers 28 29 `GET /containers/json` 30 31 List containers 32 33 **Example request**: 34 35 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 36 37 **Example response**: 38 39 HTTP/1.1 200 OK 40 Content-Type: application/json 41 42 [ 43 { 44 "Id": "8dfafdbc3a40", 45 "Image": "ubuntu:latest", 46 "Command": "echo 1", 47 "Created": 1367854155, 48 "Status": "Exit 0", 49 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 50 "SizeRw": 12288, 51 "SizeRootFs": 0 52 }, 53 { 54 "Id": "9cd87474be90", 55 "Image": "ubuntu:latest", 56 "Command": "echo 222222", 57 "Created": 1367854155, 58 "Status": "Exit 0", 59 "Ports": [], 60 "SizeRw": 12288, 61 "SizeRootFs": 0 62 }, 63 { 64 "Id": "3176a2479c92", 65 "Image": "ubuntu:latest", 66 "Command": "echo 3333333333333333", 67 "Created": 1367854154, 68 "Status": "Exit 0", 69 "Ports":[], 70 "SizeRw":12288, 71 "SizeRootFs":0 72 }, 73 { 74 "Id": "4cb07b47f9fb", 75 "Image": "ubuntu:latest", 76 "Command": "echo 444444444444444444444444444444444", 77 "Created": 1367854152, 78 "Status": "Exit 0", 79 "Ports": [], 80 "SizeRw": 12288, 81 "SizeRootFs": 0 82 } 83 ] 84 85 Query Parameters: 86 87 - **all** – 1/True/true or 0/False/false, Show all containers. 88 Only running containers are shown by default (i.e., this defaults to false) 89 - **limit** – Show `limit` last created containers, include non-running ones. 90 - **since** – Show only containers created since Id, include non-running ones. 91 - **before** – Show only containers created before Id, include non-running ones. 92 - **size** – 1/True/true or 0/False/false, Show the containers sizes 93 - **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: 94 - exited=<int> -- containers with exit code of <int> 95 - status=(restarting|running|paused|exited) 96 97 Status Codes: 98 99 - **200** – no error 100 - **400** – bad parameter 101 - **500** – server error 102 103 ### Create a container 104 105 `POST /containers/create` 106 107 Create a container 108 109 **Example request**: 110 111 POST /containers/create HTTP/1.1 112 Content-Type: application/json 113 114 { 115 "Hostname":"", 116 "Domainname": "", 117 "User":"", 118 "Memory":0, 119 "MemorySwap":0, 120 "CpuShares": 512, 121 "Cpuset": "0,1", 122 "AttachStdin":false, 123 "AttachStdout":true, 124 "AttachStderr":true, 125 "PortSpecs":null, 126 "Tty":false, 127 "OpenStdin":false, 128 "StdinOnce":false, 129 "Env": [ 130 "FOO=bar", 131 "BAZ=quux" 132 ], 133 "Cmd":[ 134 "date" 135 ], 136 "Image":"ubuntu", 137 "Volumes":{ 138 "/tmp": {} 139 }, 140 "WorkingDir":"", 141 "NetworkDisabled": false, 142 "ExposedPorts":{ 143 "22/tcp": {} 144 }, 145 "RestartPolicy": { "Name": "always" } 146 } 147 148 **Example response**: 149 150 HTTP/1.1 201 Created 151 Content-Type: application/json 152 153 { 154 "Id":"e90e34656806" 155 "Warnings":[] 156 } 157 158 Json Parameters: 159 160 - **RestartPolicy** – The behavior to apply when the container exits. The 161 value is an object with a `Name` property of either `"always"` to 162 always restart or `"on-failure"` to restart only when the container 163 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 164 controls the number of times to retry before giving up. 165 The default is not to restart. (optional) 166 An ever increasing delay (double the previous delay, starting at 100mS) 167 is added before each restart to prevent flooding the server. 168 - **config** – the container's configuration 169 170 Query Parameters: 171 172 - **name** – Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`. 173 174 Status Codes: 175 176 - **201** – no error 177 - **404** – no such container 178 - **406** – impossible to attach (container not running) 179 - **500** – server error 180 181 ### Inspect a container 182 183 `GET /containers/(id or name)/json` 184 185 Return low-level information on the container `id` 186 187 188 **Example request**: 189 190 GET /containers/4fa6e0f0c678/json HTTP/1.1 191 192 **Example response**: 193 194 HTTP/1.1 200 OK 195 Content-Type: application/json 196 197 { 198 "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", 199 "Created": "2013-05-07T14:51:42.041847+02:00", 200 "Path": "date", 201 "Args": [], 202 "Config": { 203 "Hostname": "4fa6e0f0c678", 204 "User": "", 205 "Memory": 0, 206 "MemorySwap": 0, 207 "AttachStdin": false, 208 "AttachStdout": true, 209 "AttachStderr": true, 210 "PortSpecs": null, 211 "Tty": false, 212 "OpenStdin": false, 213 "StdinOnce": false, 214 "Env": null, 215 "Cmd": [ 216 "date" 217 ], 218 "Dns": null, 219 "Image": "ubuntu", 220 "Volumes": {}, 221 "VolumesFrom": "", 222 "WorkingDir": "" 223 }, 224 "State": { 225 "Running": false, 226 "Pid": 0, 227 "ExitCode": 0, 228 "StartedAt": "2013-05-07T14:51:42.087658+02:01360", 229 "Ghost": false 230 }, 231 "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 232 "NetworkSettings": { 233 "IpAddress": "", 234 "IpPrefixLen": 0, 235 "Gateway": "", 236 "Bridge": "", 237 "PortMapping": null 238 }, 239 "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", 240 "ResolvConfPath": "/etc/resolv.conf", 241 "Volumes": {}, 242 "HostConfig": { 243 "Binds": null, 244 "ContainerIDFile": "", 245 "LxcConf": [], 246 "Privileged": false, 247 "PortBindings": { 248 "80/tcp": [ 249 { 250 "HostIp": "0.0.0.0", 251 "HostPort": "49153" 252 } 253 ] 254 }, 255 "Links": ["/name:alias"], 256 "PublishAllPorts": false, 257 "CapAdd": ["NET_ADMIN"], 258 "CapDrop": ["MKNOD"] 259 } 260 } 261 262 Status Codes: 263 264 - **200** – no error 265 - **404** – no such container 266 - **500** – server error 267 268 ### List processes running inside a container 269 270 `GET /containers/(id or name)/top` 271 272 List processes running inside the container `id`. On Unix systems this 273 is done by running the `ps` command. This endpoint is not 274 supported on Windows. 275 276 **Example request**: 277 278 GET /containers/4fa6e0f0c678/top HTTP/1.1 279 280 **Example response**: 281 282 HTTP/1.1 200 OK 283 Content-Type: application/json 284 285 { 286 "Titles" : [ 287 "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" 288 ], 289 "Processes" : [ 290 [ 291 "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" 292 ], 293 [ 294 "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" 295 ] 296 ] 297 } 298 299 **Example request**: 300 301 GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 302 303 **Example response**: 304 305 HTTP/1.1 200 OK 306 Content-Type: application/json 307 308 { 309 "Titles" : [ 310 "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" 311 ] 312 "Processes" : [ 313 [ 314 "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" 315 ], 316 [ 317 "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" 318 ] 319 ], 320 } 321 322 Query Parameters: 323 324 - **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` 325 326 Status Codes: 327 328 - **200** – no error 329 - **404** – no such container 330 - **500** – server error 331 332 ### Get container logs 333 334 `GET /containers/(id or name)/logs` 335 336 Get stdout and stderr logs from the container ``id`` 337 338 **Example request**: 339 340 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 341 342 **Example response**: 343 344 HTTP/1.1 200 OK 345 Content-Type: application/vnd.docker.raw-stream 346 347 {{ STREAM }} 348 349 Query Parameters: 350 351 - **follow** – 1/True/true or 0/False/false, return stream. Default false 352 - **stdout** – 1/True/true or 0/False/false, show stdout log. Default false 353 - **stderr** – 1/True/true or 0/False/false, show stderr log. Default false 354 - **timestamps** – 1/True/true or 0/False/false, print timestamps for every 355 log line. Default false 356 - **tail** – Output specified number of lines at the end of logs: `all` or 357 `<number>`. Default all 358 359 Status Codes: 360 361 - **200** – no error 362 - **404** – no such container 363 - **500** – server error 364 365 ### Inspect changes on a container's filesystem 366 367 `GET /containers/(id or name)/changes` 368 369 Inspect changes on container `id`'s filesystem 370 371 **Example request**: 372 373 GET /containers/4fa6e0f0c678/changes HTTP/1.1 374 375 **Example response**: 376 377 HTTP/1.1 200 OK 378 Content-Type: application/json 379 380 [ 381 { 382 "Path": "/dev", 383 "Kind": 0 384 }, 385 { 386 "Path": "/dev/kmsg", 387 "Kind": 1 388 }, 389 { 390 "Path": "/test", 391 "Kind": 1 392 } 393 ] 394 395 Status Codes: 396 397 - **200** – no error 398 - **404** – no such container 399 - **500** – server error 400 401 ### Export a container 402 403 `GET /containers/(id or name)/export` 404 405 Export the contents of container `id` 406 407 **Example request**: 408 409 GET /containers/4fa6e0f0c678/export HTTP/1.1 410 411 **Example response**: 412 413 HTTP/1.1 200 OK 414 Content-Type: application/octet-stream 415 416 {{ TAR STREAM }} 417 418 Status Codes: 419 420 - **200** – no error 421 - **404** – no such container 422 - **500** – server error 423 424 ### Start a container 425 426 `POST /containers/(id or name)/start` 427 428 Start the container `id` 429 430 **Example request**: 431 432 POST /containers/e90e34656806/start HTTP/1.1 433 Content-Type: application/json 434 435 { 436 "Binds":["/tmp:/tmp"], 437 "Links":["redis3:redis"], 438 "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], 439 "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, 440 "PublishAllPorts":false, 441 "Privileged":false, 442 "Dns": ["8.8.8.8"], 443 "VolumesFrom": ["parent", "other:ro"], 444 "CapAdd": ["NET_ADMIN"], 445 "CapDrop": ["MKNOD"] 446 } 447 448 **Example response**: 449 450 HTTP/1.1 204 No Content 451 452 Json Parameters: 453 454 - **hostConfig** – the container's host configuration (optional) 455 456 Status Codes: 457 458 - **204** – no error 459 - **304** – container already started 460 - **404** – no such container 461 - **500** – server error 462 463 ### Stop a container 464 465 `POST /containers/(id or name)/stop` 466 467 Stop the container `id` 468 469 **Example request**: 470 471 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 472 473 **Example response**: 474 475 HTTP/1.1 204 No Content 476 477 Query Parameters: 478 479 - **t** – number of seconds to wait before killing the container 480 481 Status Codes: 482 483 - **204** – no error 484 - **304** – container already stopped 485 - **404** – no such container 486 - **500** – server error 487 488 ### Restart a container 489 490 `POST /containers/(id or name)/restart` 491 492 Restart the container `id` 493 494 **Example request**: 495 496 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 497 498 **Example response**: 499 500 HTTP/1.1 204 No Content 501 502 Query Parameters: 503 504 - **t** – number of seconds to wait before killing the container 505 506 Status Codes: 507 508 - **204** – no error 509 - **404** – no such container 510 - **500** – server error 511 512 ### Kill a container 513 514 `POST /containers/(id or name)/kill` 515 516 Kill the container `id` 517 518 **Example request**: 519 520 POST /containers/e90e34656806/kill HTTP/1.1 521 522 **Example response**: 523 524 HTTP/1.1 204 No Content 525 526 Query Parameters 527 528 - **signal** - Signal to send to the container: integer or string like "SIGINT". 529 When not set, SIGKILL is assumed and the call will wait for the container to exit. 530 531 Status Codes: 532 533 - **204** – no error 534 - **404** – no such container 535 - **500** – server error 536 537 ### Pause a container 538 539 `POST /containers/(id or name)/pause` 540 541 Pause the container `id` 542 543 **Example request**: 544 545 POST /containers/e90e34656806/pause HTTP/1.1 546 547 **Example response**: 548 549 HTTP/1.1 204 No Content 550 551 Status Codes: 552 553 - **204** – no error 554 - **404** – no such container 555 - **500** – server error 556 557 ### Unpause a container 558 559 `POST /containers/(id or name)/unpause` 560 561 Unpause the container `id` 562 563 **Example request**: 564 565 POST /containers/e90e34656806/unpause HTTP/1.1 566 567 **Example response**: 568 569 HTTP/1.1 204 No Content 570 571 Status Codes: 572 573 - **204** – no error 574 - **404** – no such container 575 - **500** – server error 576 577 ### Attach to a container 578 579 `POST /containers/(id or name)/attach` 580 581 Attach to the container `id` 582 583 **Example request**: 584 585 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 586 587 **Example response**: 588 589 HTTP/1.1 200 OK 590 Content-Type: application/vnd.docker.raw-stream 591 592 {{ STREAM }} 593 594 Query Parameters: 595 596 - **logs** – 1/True/true or 0/False/false, return logs. Default false 597 - **stream** – 1/True/true or 0/False/false, return stream. Default false 598 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. 599 Default false 600 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 601 stdout log, if stream=true, attach to stdout. Default false 602 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 603 stderr log, if stream=true, attach to stderr. Default false 604 605 Status Codes: 606 607 - **200** – no error 608 - **400** – bad parameter 609 - **404** – no such container 610 - **500** – server error 611 612 **Stream details**: 613 614 When using the TTY setting is enabled in 615 [`POST /containers/create`](#create-a-container), 616 the stream is the raw data from the process PTY and client's stdin. 617 When the TTY is disabled, then the stream is multiplexed to separate 618 stdout and stderr. 619 620 The format is a **Header** and a **Payload** (frame). 621 622 **HEADER** 623 624 The header will contain the information on which stream write the 625 stream (stdout or stderr). It also contain the size of the 626 associated frame encoded on the last 4 bytes (uint32). 627 628 It is encoded on the first 8 bytes like this: 629 630 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 631 632 `STREAM_TYPE` can be: 633 634 - 0: stdin (will be written on stdout) 635 - 1: stdout 636 - 2: stderr 637 638 `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of 639 the uint32 size encoded as big endian. 640 641 **PAYLOAD** 642 643 The payload is the raw stream. 644 645 **IMPLEMENTATION** 646 647 The simplest way to implement the Attach protocol is the following: 648 649 1. Read 8 bytes 650 2. chose stdout or stderr depending on the first byte 651 3. Extract the frame size from the last 4 bytes 652 4. Read the extracted size and output it on the correct output 653 5. Goto 1 654 655 ### Attach to a container (websocket) 656 657 `GET /containers/(id or name)/attach/ws` 658 659 Attach to the container `id` via websocket 660 661 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 662 663 **Example request** 664 665 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 666 667 **Example response** 668 669 {{ STREAM }} 670 671 Query Parameters: 672 673 - **logs** – 1/True/true or 0/False/false, return logs. Default false 674 - **stream** – 1/True/true or 0/False/false, return stream. 675 Default false 676 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 677 to stdin. Default false 678 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 679 stdout log, if stream=true, attach to stdout. Default false 680 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 681 stderr log, if stream=true, attach to stderr. Default false 682 683 Status Codes: 684 685 - **200** – no error 686 - **400** – bad parameter 687 - **404** – no such container 688 - **500** – server error 689 690 ### Wait a container 691 692 `POST /containers/(id or name)/wait` 693 694 Block until container `id` stops, then returns the exit code 695 696 **Example request**: 697 698 POST /containers/16253994b7c4/wait HTTP/1.1 699 700 **Example response**: 701 702 HTTP/1.1 200 OK 703 Content-Type: application/json 704 705 {"StatusCode": 0} 706 707 Status Codes: 708 709 - **200** – no error 710 - **404** – no such container 711 - **500** – server error 712 713 ### Remove a container 714 715 `DELETE /containers/(id or name)` 716 717 Remove the container `id` from the filesystem 718 719 **Example request**: 720 721 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 722 723 **Example response**: 724 725 HTTP/1.1 204 No Content 726 727 Query Parameters: 728 729 - **v** – 1/True/true or 0/False/false, Remove the volumes 730 associated to the container. Default false 731 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 732 Default false 733 734 Status Codes: 735 736 - **204** – no error 737 - **400** – bad parameter 738 - **404** – no such container 739 - **500** – server error 740 741 ### Copy files or folders from a container 742 743 `POST /containers/(id or name)/copy` 744 745 Copy files or folders of container `id` 746 747 **Example request**: 748 749 POST /containers/4fa6e0f0c678/copy HTTP/1.1 750 Content-Type: application/json 751 752 { 753 "Resource": "test.txt" 754 } 755 756 **Example response**: 757 758 HTTP/1.1 200 OK 759 Content-Type: application/octet-stream 760 761 {{ TAR STREAM }} 762 763 Status Codes: 764 765 - **200** – no error 766 - **404** – no such container 767 - **500** – server error 768 769 ## 2.2 Images 770 771 ### List Images 772 773 `GET /images/json` 774 775 **Example request**: 776 777 GET /images/json?all=0 HTTP/1.1 778 779 **Example response**: 780 781 HTTP/1.1 200 OK 782 Content-Type: application/json 783 784 [ 785 { 786 "RepoTags": [ 787 "ubuntu:12.04", 788 "ubuntu:precise", 789 "ubuntu:latest" 790 ], 791 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 792 "Created": 1365714795, 793 "Size": 131506275, 794 "VirtualSize": 131506275 795 }, 796 { 797 "RepoTags": [ 798 "ubuntu:12.10", 799 "ubuntu:quantal" 800 ], 801 "ParentId": "27cf784147099545", 802 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 803 "Created": 1364102658, 804 "Size": 24653, 805 "VirtualSize": 180116135 806 } 807 ] 808 809 810 Query Parameters: 811 812 - **all** – 1/True/true or 0/False/false, default false 813 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 814 - dangling=true 815 - **filter** - only return images with the specified name 816 817 ### Create an image 818 819 `POST /images/create` 820 821 Create an image, either by pulling it from the registry or by importing it 822 823 **Example request**: 824 825 POST /images/create?fromImage=ubuntu HTTP/1.1 826 827 **Example response**: 828 829 HTTP/1.1 200 OK 830 Content-Type: application/json 831 832 {"status": "Pulling..."} 833 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 834 {"error": "Invalid..."} 835 ... 836 837 When using this endpoint to pull an image from the registry, the 838 `X-Registry-Auth` header can be used to include 839 a base64-encoded AuthConfig object. 840 841 Query Parameters: 842 843 - **fromImage** – name of the image to pull 844 - **fromSrc** – source to import, - means stdin 845 - **repo** – repository 846 - **tag** – tag 847 - **registry** – the registry to pull from 848 849 Request Headers: 850 851 - **X-Registry-Auth** – base64-encoded AuthConfig object 852 853 Status Codes: 854 855 - **200** – no error 856 - **500** – server error 857 858 859 860 ### Inspect an image 861 862 `GET /images/(name)/json` 863 864 Return low-level information on the image `name` 865 866 **Example request**: 867 868 GET /images/ubuntu/json HTTP/1.1 869 870 **Example response**: 871 872 HTTP/1.1 200 OK 873 Content-Type: application/json 874 875 { 876 "Created": "2013-03-23T22:24:18.818426-07:00", 877 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 878 "ContainerConfig": 879 { 880 "Hostname": "", 881 "User": "", 882 "Memory": 0, 883 "MemorySwap": 0, 884 "AttachStdin": false, 885 "AttachStdout": false, 886 "AttachStderr": false, 887 "PortSpecs": null, 888 "Tty": true, 889 "OpenStdin": true, 890 "StdinOnce": false, 891 "Env": null, 892 "Cmd": ["/bin/bash"], 893 "Dns": null, 894 "Image": "ubuntu", 895 "Volumes": null, 896 "VolumesFrom": "", 897 "WorkingDir": "" 898 }, 899 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 900 "Parent": "27cf784147099545", 901 "Size": 6824592 902 } 903 904 Status Codes: 905 906 - **200** – no error 907 - **404** – no such image 908 - **500** – server error 909 910 ### Get the history of an image 911 912 `GET /images/(name)/history` 913 914 Return the history of the image `name` 915 916 **Example request**: 917 918 GET /images/ubuntu/history HTTP/1.1 919 920 **Example response**: 921 922 HTTP/1.1 200 OK 923 Content-Type: application/json 924 925 [ 926 { 927 "Id": "b750fe79269d", 928 "Created": 1364102658, 929 "CreatedBy": "/bin/bash" 930 }, 931 { 932 "Id": "27cf78414709", 933 "Created": 1364068391, 934 "CreatedBy": "" 935 } 936 ] 937 938 Status Codes: 939 940 - **200** – no error 941 - **404** – no such image 942 - **500** – server error 943 944 ### Push an image on the registry 945 946 `POST /images/(name)/push` 947 948 Push the image `name` on the registry 949 950 **Example request**: 951 952 POST /images/test/push HTTP/1.1 953 954 **Example response**: 955 956 HTTP/1.1 200 OK 957 Content-Type: application/json 958 959 {"status": "Pushing..."} 960 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 961 {"error": "Invalid..."} 962 ... 963 964 If you wish to push an image on to a private registry, that image must already have been tagged 965 into a repository which references that registry host name and port. This repository name should 966 then be used in the URL. This mirrors the flow of the CLI. 967 968 **Example request**: 969 970 POST /images/registry.acme.com:5000/test/push HTTP/1.1 971 972 973 Query Parameters: 974 975 - **tag** – the tag to associate with the image on the registry, optional 976 977 Request Headers: 978 979 - **X-Registry-Auth** – include a base64-encoded AuthConfig object. 980 981 Status Codes: 982 983 - **200** – no error 984 - **404** – no such image 985 - **500** – server error 986 987 ### Tag an image into a repository 988 989 `POST /images/(name)/tag` 990 991 Tag the image `name` into a repository 992 993 **Example request**: 994 995 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 996 997 **Example response**: 998 999 HTTP/1.1 201 Created 1000 1001 Query Parameters: 1002 1003 - **repo** – The repository to tag in 1004 - **force** – 1/True/true or 0/False/false, default false 1005 - **tag** - The new tag name 1006 1007 Status Codes: 1008 1009 - **201** – no error 1010 - **400** – bad parameter 1011 - **404** – no such image 1012 - **409** – conflict 1013 - **500** – server error 1014 1015 ### Remove an image 1016 1017 `DELETE /images/(name)` 1018 1019 Remove the image `name` from the filesystem 1020 1021 **Example request**: 1022 1023 DELETE /images/test HTTP/1.1 1024 1025 **Example response**: 1026 1027 HTTP/1.1 200 OK 1028 Content-type: application/json 1029 1030 [ 1031 {"Untagged": "3e2f21a89f"}, 1032 {"Deleted": "3e2f21a89f"}, 1033 {"Deleted": "53b4f83ac9"} 1034 ] 1035 1036 Query Parameters: 1037 1038 - **force** – 1/True/true or 0/False/false, default false 1039 - **noprune** – 1/True/true or 0/False/false, default false 1040 1041 Status Codes: 1042 1043 - **200** – no error 1044 - **404** – no such image 1045 - **409** – conflict 1046 - **500** – server error 1047 1048 ### Search images 1049 1050 `GET /images/search` 1051 1052 Search for an image on [Docker Hub](https://hub.docker.com). 1053 1054 > **Note**: 1055 > The response keys have changed from API v1.6 to reflect the JSON 1056 > sent by the registry server to the docker daemon's request. 1057 1058 **Example request**: 1059 1060 GET /images/search?term=sshd HTTP/1.1 1061 1062 **Example response**: 1063 1064 HTTP/1.1 200 OK 1065 Content-Type: application/json 1066 1067 [ 1068 { 1069 "description": "", 1070 "is_official": false, 1071 "is_automated": false, 1072 "name": "wma55/u1210sshd", 1073 "star_count": 0 1074 }, 1075 { 1076 "description": "", 1077 "is_official": false, 1078 "is_automated": false, 1079 "name": "jdswinbank/sshd", 1080 "star_count": 0 1081 }, 1082 { 1083 "description": "", 1084 "is_official": false, 1085 "is_automated": false, 1086 "name": "vgauthier/sshd", 1087 "star_count": 0 1088 } 1089 ... 1090 ] 1091 1092 Query Parameters: 1093 1094 - **term** – term to search 1095 1096 Status Codes: 1097 1098 - **200** – no error 1099 - **500** – server error 1100 1101 ## 2.3 Misc 1102 1103 ### Build an image from Dockerfile via stdin 1104 1105 `POST /build` 1106 1107 Build an image from Dockerfile via stdin 1108 1109 **Example request**: 1110 1111 POST /build HTTP/1.1 1112 1113 {{ TAR STREAM }} 1114 1115 **Example response**: 1116 1117 HTTP/1.1 200 OK 1118 Content-Type: application/json 1119 1120 {"stream": "Step 1..."} 1121 {"stream": "..."} 1122 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1123 1124 The stream must be a tar archive compressed with one of the 1125 following algorithms: identity (no compression), gzip, bzip2, xz. 1126 1127 The archive must include a file called `Dockerfile` 1128 at its root. It may include any number of other files, 1129 which will be accessible in the build context (See the [*ADD build 1130 command*](../../reference/builder.md#dockerbuilder)). 1131 1132 Query Parameters: 1133 1134 - **t** – repository name (and optionally a tag) to be applied to 1135 the resulting image in case of success 1136 - **remote** – git or HTTP/HTTPS URI build source 1137 - **q** – suppress verbose build output 1138 - **nocache** – do not use the cache when building the image 1139 - **rm** - remove intermediate containers after a successful build (default behavior) 1140 - **forcerm** - always remove intermediate containers (includes rm) 1141 1142 Request Headers: 1143 1144 - **Content-type** – should be set to `"application/tar"`. 1145 - **X-Registry-Config** – base64-encoded ConfigFile object 1146 1147 Status Codes: 1148 1149 - **200** – no error 1150 - **500** – server error 1151 1152 ### Check auth configuration 1153 1154 `POST /auth` 1155 1156 Get the default username and email 1157 1158 **Example request**: 1159 1160 POST /auth HTTP/1.1 1161 Content-Type: application/json 1162 1163 { 1164 "username":" hannibal", 1165 "password: "xxxx", 1166 "email": "hannibal@a-team.com", 1167 "serveraddress": "https://index.docker.io/v1/" 1168 } 1169 1170 **Example response**: 1171 1172 HTTP/1.1 200 OK 1173 1174 Status Codes: 1175 1176 - **200** – no error 1177 - **204** – no error 1178 - **500** – server error 1179 1180 ### Display system-wide information 1181 1182 `GET /info` 1183 1184 Display system-wide information 1185 1186 **Example request**: 1187 1188 GET /info HTTP/1.1 1189 1190 **Example response**: 1191 1192 HTTP/1.1 200 OK 1193 Content-Type: application/json 1194 1195 { 1196 "Containers": 11, 1197 "Images": 16, 1198 "Driver": "btrfs", 1199 "ExecutionDriver": "native-0.1", 1200 "KernelVersion": "3.12.0-1-amd64" 1201 "Debug": false, 1202 "NFd": 11, 1203 "NGoroutines": 21, 1204 "NEventsListener": 0, 1205 "InitPath": "/usr/bin/docker", 1206 "IndexServerAddress": ["https://index.docker.io/v1/"], 1207 "MemoryLimit": true, 1208 "SwapLimit": false, 1209 "IPv4Forwarding": true 1210 } 1211 1212 Status Codes: 1213 1214 - **200** – no error 1215 - **500** – server error 1216 1217 ### Show the docker version information 1218 1219 `GET /version` 1220 1221 Show the docker version information 1222 1223 **Example request**: 1224 1225 GET /version HTTP/1.1 1226 1227 **Example response**: 1228 1229 HTTP/1.1 200 OK 1230 Content-Type: application/json 1231 1232 { 1233 "ApiVersion": "1.12", 1234 "Version": "0.2.2", 1235 "GitCommit": "5a2a5cc+CHANGES", 1236 "GoVersion": "go1.0.3" 1237 } 1238 1239 Status Codes: 1240 1241 - **200** – no error 1242 - **500** – server error 1243 1244 ### Ping the docker server 1245 1246 `GET /_ping` 1247 1248 Ping the docker server 1249 1250 **Example request**: 1251 1252 GET /_ping HTTP/1.1 1253 1254 **Example response**: 1255 1256 HTTP/1.1 200 OK 1257 Content-Type: text/plain 1258 1259 OK 1260 1261 Status Codes: 1262 1263 - **200** - no error 1264 - **500** - server error 1265 1266 ### Create a new image from a container's changes 1267 1268 `POST /commit` 1269 1270 Create a new image from a container's changes 1271 1272 **Example request**: 1273 1274 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1275 Content-Type: application/json 1276 1277 { 1278 "Hostname": "", 1279 "Domainname": "", 1280 "User": "", 1281 "Memory": 0, 1282 "MemorySwap": 0, 1283 "CpuShares": 512, 1284 "Cpuset": "0,1", 1285 "AttachStdin": false, 1286 "AttachStdout": true, 1287 "AttachStderr": true, 1288 "PortSpecs": null, 1289 "Tty": false, 1290 "OpenStdin": false, 1291 "StdinOnce": false, 1292 "Env": null, 1293 "Cmd": [ 1294 "date" 1295 ], 1296 "Volumes": { 1297 "/tmp": {} 1298 }, 1299 "WorkingDir": "", 1300 "NetworkDisabled": false, 1301 "ExposedPorts": { 1302 "22/tcp": {} 1303 } 1304 } 1305 1306 **Example response**: 1307 1308 HTTP/1.1 201 Created 1309 Content-Type: application/json 1310 1311 {"Id": "596069db4bf5"} 1312 1313 Json Parameters: 1314 1315 - **config** - the container's configuration 1316 1317 Query Parameters: 1318 1319 - **container** – source container 1320 - **repo** – repository 1321 - **tag** – tag 1322 - **comment** – commit message 1323 - **author** – author (e.g., "John Hannibal Smith 1324 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1325 1326 Status Codes: 1327 1328 - **201** – no error 1329 - **404** – no such container 1330 - **500** – server error 1331 1332 ### Monitor Docker's events 1333 1334 `GET /events` 1335 1336 Get container events from docker, either in real time via streaming, or via 1337 polling (using since). 1338 1339 Docker containers will report the following events: 1340 1341 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1342 1343 and Docker images will report: 1344 1345 untag, delete 1346 1347 **Example request**: 1348 1349 GET /events?since=1374067924 1350 1351 **Example response**: 1352 1353 HTTP/1.1 200 OK 1354 Content-Type: application/json 1355 1356 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1357 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1358 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1359 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1360 1361 Query Parameters: 1362 1363 - **since** – timestamp used for polling 1364 - **until** – timestamp used for polling 1365 1366 Status Codes: 1367 1368 - **200** – no error 1369 - **500** – server error 1370 1371 ### Get a tarball containing all images and tags in a repository 1372 1373 `GET /images/(name)/get` 1374 1375 Get a tarball containing all images and metadata for the repository 1376 specified by `name`. 1377 1378 See the [image tarball format](#image-tarball-format) for more details. 1379 1380 **Example request** 1381 1382 GET /images/ubuntu/get 1383 1384 **Example response**: 1385 1386 HTTP/1.1 200 OK 1387 Content-Type: application/x-tar 1388 1389 Binary data stream 1390 1391 Status Codes: 1392 1393 - **200** – no error 1394 - **500** – server error 1395 1396 ### Load a tarball with a set of images and tags into docker 1397 1398 `POST /images/load` 1399 1400 Load a set of images and tags into the docker repository. 1401 See the [image tarball format](#image-tarball-format) for more details. 1402 1403 **Example request** 1404 1405 POST /images/load 1406 1407 Tarball in body 1408 1409 **Example response**: 1410 1411 HTTP/1.1 200 OK 1412 1413 Status Codes: 1414 1415 - **200** – no error 1416 - **500** – server error 1417 1418 ### Image tarball format 1419 1420 An image tarball contains one directory per image layer (named using its long ID), 1421 each containing three files: 1422 1423 1. `VERSION`: currently `1.0` - the file format version 1424 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1425 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1426 1427 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1428 for storing attribute changes and deletions. 1429 1430 If the tarball defines a repository, there will also be a `repositories` file at 1431 the root that contains a list of repository and tag names mapped to layer IDs. 1432 1433 ``` 1434 {"hello-world": 1435 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1436 } 1437 ``` 1438 1439 # 3. Going further 1440 1441 ## 3.1 Inside `docker run` 1442 1443 As an example, the `docker run` command line makes the following API calls: 1444 1445 - Create the container 1446 1447 - If the status code is 404, it means the image doesn't exist: 1448 - Try to pull it 1449 - Then retry to create the container 1450 1451 - Start the container 1452 1453 - If you are not in detached mode: 1454 - Attach to the container, using logs=1 (to have stdout and 1455 stderr from the container's start) and stream=1 1456 1457 - If in detached mode or only stdin is attached: 1458 - Display the container's id 1459 1460 ## 3.2 Hijacking 1461 1462 In this version of the API, /attach, uses hijacking to transport stdin, 1463 stdout and stderr on the same socket. This might change in the future. 1464 1465 ## 3.3 CORS Requests 1466 1467 To enable cross origin requests to the remote api add the flag 1468 "--api-enable-cors" when running docker in daemon mode. 1469 1470 $ docker -d -H="192.168.1.9:2375" --api-enable-cors