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