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