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