github.com/0xfoo/docker@v1.8.2/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 - **filter** - only return images with the specified name 795 796 797 798 ### Create an image 799 800 `POST /images/create` 801 802 Create an image, either by pull it from the registry or by importing i 803 804 **Example request**: 805 806 POST /images/create?fromImage=ubuntu HTTP/1.1 807 808 **Example response**: 809 810 HTTP/1.1 200 OK 811 Content-Type: application/json 812 813 {"status": "Pulling..."} 814 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 815 {"error": "Invalid..."} 816 ... 817 818 When using this endpoint to pull an image from the registry, the 819 `X-Registry-Auth` header can be used to include 820 a base64-encoded AuthConfig object. 821 822 Query Parameters: 823 824 - **fromImage** – name of the image to pull 825 - **fromSrc** – source to import, - means stdin 826 - **repo** – repository 827 - **tag** – tag 828 - **registry** – the registry to pull from 829 830 Request Headers: 831 832 - **X-Registry-Auth** – base64-encoded AuthConfig object 833 834 Status Codes: 835 836 - **200** – no error 837 - **500** – server error 838 839 840 841 ### Inspect an image 842 843 `GET /images/(name)/json` 844 845 Return low-level information on the image `name` 846 847 **Example request**: 848 849 GET /images/ubuntu/json HTTP/1.1 850 851 **Example response**: 852 853 HTTP/1.1 200 OK 854 Content-Type: application/json 855 856 { 857 "Created": "2013-03-23T22:24:18.818426-07:00", 858 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 859 "ContainerConfig": 860 { 861 "Hostname": "", 862 "User": "", 863 "Memory": 0, 864 "MemorySwap": 0, 865 "AttachStdin": false, 866 "AttachStdout": false, 867 "AttachStderr": false, 868 "PortSpecs": null, 869 "Tty": true, 870 "OpenStdin": true, 871 "StdinOnce": false, 872 "Env": null, 873 "Cmd": ["/bin/bash"], 874 "Dns": null, 875 "Image": "ubuntu", 876 "Volumes": null, 877 "VolumesFrom": "", 878 "WorkingDir": "" 879 }, 880 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 881 "Parent": "27cf784147099545", 882 "Size": 6824592 883 } 884 885 Status Codes: 886 887 - **200** – no error 888 - **404** – no such image 889 - **500** – server error 890 891 ### Get the history of an image 892 893 `GET /images/(name)/history` 894 895 Return the history of the image `name` 896 897 **Example request**: 898 899 GET /images/ubuntu/history HTTP/1.1 900 901 **Example response**: 902 903 HTTP/1.1 200 OK 904 Content-Type: application/json 905 906 [ 907 { 908 "Id": "b750fe79269d", 909 "Created": 1364102658, 910 "CreatedBy": "/bin/bash" 911 }, 912 { 913 "Id": "27cf78414709", 914 "Created": 1364068391, 915 "CreatedBy": "" 916 } 917 ] 918 919 Status Codes: 920 921 - **200** – no error 922 - **404** – no such image 923 - **500** – server error 924 925 ### Push an image on the registry 926 927 `POST /images/(name)/push` 928 929 Push the image `name` on the registry 930 931 **Example request**: 932 933 POST /images/test/push HTTP/1.1 934 935 **Example response**: 936 937 HTTP/1.1 200 OK 938 Content-Type: application/json 939 940 {"status": "Pushing..."} 941 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 942 {"error": "Invalid..."} 943 ... 944 945 If you wish to push an image on to a private registry, that image must already have been tagged 946 into a repository which references that registry host name and port. This repository name should 947 then be used in the URL. This mirrors the flow of the CLI. 948 949 **Example request**: 950 951 POST /images/registry.acme.com:5000/test/push HTTP/1.1 952 953 954 Query Parameters: 955 956 - **tag** – the tag to associate with the image on the registry, optional 957 958 Request Headers: 959 960 - **X-Registry-Auth** – include a base64-encoded AuthConfig object. 961 962 Status Codes: 963 964 - **200** – no error 965 - **404** – no such image 966 - **500** – server error 967 968 ### Tag an image into a repository 969 970 `POST /images/(name)/tag` 971 972 Tag the image `name` into a repository 973 974 **Example request**: 975 976 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 977 978 **Example response**: 979 980 HTTP/1.1 201 OK 981 982 Query Parameters: 983 984 - **repo** – The repository to tag in 985 - **force** – 1/True/true or 0/False/false, default false 986 - **tag** - The new tag name 987 988 Status Codes: 989 990 - **201** – no error 991 - **400** – bad parameter 992 - **404** – no such image 993 - **409** – conflict 994 - **500** – server error 995 996 ### Remove an image 997 998 `DELETE /images/(name)` 999 1000 Remove the image `name` from the filesystem 1001 1002 **Example request**: 1003 1004 DELETE /images/test HTTP/1.1 1005 1006 **Example response**: 1007 1008 HTTP/1.1 200 OK 1009 Content-type: application/json 1010 1011 [ 1012 {"Untagged": "3e2f21a89f"}, 1013 {"Deleted": "3e2f21a89f"}, 1014 {"Deleted": "53b4f83ac9"} 1015 ] 1016 1017 Query Parameters: 1018 1019 - **force** – 1/True/true or 0/False/false, default false 1020 - **noprune** – 1/True/true or 0/False/false, default false 1021 1022 Status Codes: 1023 1024 - **200** – no error 1025 - **404** – no such image 1026 - **409** – conflict 1027 - **500** – server error 1028 1029 ### Search images 1030 1031 `GET /images/search` 1032 1033 Search for an image on [Docker Hub](https://hub.docker.com). 1034 1035 > **Note**: 1036 > The response keys have changed from API v1.6 to reflect the JSON 1037 > sent by the registry server to the docker daemon's request. 1038 1039 **Example request**: 1040 1041 GET /images/search?term=sshd HTTP/1.1 1042 1043 **Example response**: 1044 1045 HTTP/1.1 200 OK 1046 Content-Type: application/json 1047 1048 [ 1049 { 1050 "description": "", 1051 "is_official": false, 1052 "is_automated": false, 1053 "name": "wma55/u1210sshd", 1054 "star_count": 0 1055 }, 1056 { 1057 "description": "", 1058 "is_official": false, 1059 "is_automated": false, 1060 "name": "jdswinbank/sshd", 1061 "star_count": 0 1062 }, 1063 { 1064 "description": "", 1065 "is_official": false, 1066 "is_automated": false, 1067 "name": "vgauthier/sshd", 1068 "star_count": 0 1069 } 1070 ... 1071 ] 1072 1073 Query Parameters: 1074 1075 - **term** – term to search 1076 1077 Status Codes: 1078 1079 - **200** – no error 1080 - **500** – server error 1081 1082 ## 2.3 Misc 1083 1084 ### Build an image from Dockerfile via stdin 1085 1086 `POST /build` 1087 1088 Build an image from Dockerfile via stdin 1089 1090 **Example request**: 1091 1092 POST /build HTTP/1.1 1093 1094 {{ TAR STREAM }} 1095 1096 **Example response**: 1097 1098 HTTP/1.1 200 OK 1099 Content-Type: application/json 1100 1101 {"stream": "Step 1..."} 1102 {"stream": "..."} 1103 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1104 1105 The stream must be a tar archive compressed with one of the 1106 following algorithms: identity (no compression), gzip, bzip2, xz. 1107 1108 The archive must include a file called `Dockerfile` 1109 at its root. It may include any number of other files, 1110 which will be accessible in the build context (See the [*ADD build 1111 command*](/reference/builder/#dockerbuilder)). 1112 1113 Query Parameters: 1114 1115 - **t** – repository name (and optionally a tag) to be applied to 1116 the resulting image in case of success 1117 - **remote** – git or HTTP/HTTPS URI build source 1118 - **q** – suppress verbose build output 1119 - **nocache** – do not use the cache when building the image 1120 - **rm** - remove intermediate containers after a successful build (default behavior) 1121 - **forcerm** - always remove intermediate containers (includes rm) 1122 1123 Request Headers: 1124 1125 - **Content-type** – should be set to `"application/tar"`. 1126 - **X-Registry-Config** – base64-encoded ConfigFile object 1127 1128 Status Codes: 1129 1130 - **200** – no error 1131 - **500** – server error 1132 1133 ### Check auth configuration 1134 1135 `POST /auth` 1136 1137 Get the default username and email 1138 1139 **Example request**: 1140 1141 POST /auth HTTP/1.1 1142 Content-Type: application/json 1143 1144 { 1145 "username":" hannibal", 1146 "password: "xxxx", 1147 "email": "hannibal@a-team.com", 1148 "serveraddress": "https://index.docker.io/v1/" 1149 } 1150 1151 **Example response**: 1152 1153 HTTP/1.1 200 OK 1154 1155 Status Codes: 1156 1157 - **200** – no error 1158 - **204** – no error 1159 - **500** – server error 1160 1161 ### Display system-wide information 1162 1163 `GET /info` 1164 1165 Display system-wide information 1166 1167 **Example request**: 1168 1169 GET /info HTTP/1.1 1170 1171 **Example response**: 1172 1173 HTTP/1.1 200 OK 1174 Content-Type: application/json 1175 1176 { 1177 "Containers": 11, 1178 "Images": 16, 1179 "Driver": "btrfs", 1180 "ExecutionDriver": "native-0.1", 1181 "KernelVersion": "3.12.0-1-amd64" 1182 "Debug": false, 1183 "NFd": 11, 1184 "NGoroutines": 21, 1185 "NEventsListener": 0, 1186 "InitPath": "/usr/bin/docker", 1187 "IndexServerAddress": ["https://index.docker.io/v1/"], 1188 "MemoryLimit": true, 1189 "SwapLimit": false, 1190 "IPv4Forwarding": true 1191 } 1192 1193 Status Codes: 1194 1195 - **200** – no error 1196 - **500** – server error 1197 1198 ### Show the docker version information 1199 1200 `GET /version` 1201 1202 Show the docker version information 1203 1204 **Example request**: 1205 1206 GET /version HTTP/1.1 1207 1208 **Example response**: 1209 1210 HTTP/1.1 200 OK 1211 Content-Type: application/json 1212 1213 { 1214 "ApiVersion": "1.12", 1215 "Version": "0.2.2", 1216 "GitCommit": "5a2a5cc+CHANGES", 1217 "GoVersion": "go1.0.3" 1218 } 1219 1220 Status Codes: 1221 1222 - **200** – no error 1223 - **500** – server error 1224 1225 ### Ping the docker server 1226 1227 `GET /_ping` 1228 1229 Ping the docker server 1230 1231 **Example request**: 1232 1233 GET /_ping HTTP/1.1 1234 1235 **Example response**: 1236 1237 HTTP/1.1 200 OK 1238 Content-Type: text/plain 1239 1240 OK 1241 1242 Status Codes: 1243 1244 - **200** - no error 1245 - **500** - server error 1246 1247 ### Create a new image from a container's changes 1248 1249 `POST /commit` 1250 1251 Create a new image from a container's changes 1252 1253 **Example request**: 1254 1255 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1256 Content-Type: application/json 1257 1258 { 1259 "Hostname": "", 1260 "Domainname": "", 1261 "User": "", 1262 "Memory": 0, 1263 "MemorySwap": 0, 1264 "CpuShares": 512, 1265 "Cpuset": "0,1", 1266 "AttachStdin": false, 1267 "AttachStdout": true, 1268 "AttachStderr": true, 1269 "PortSpecs": null, 1270 "Tty": false, 1271 "OpenStdin": false, 1272 "StdinOnce": false, 1273 "Env": null, 1274 "Cmd": [ 1275 "date" 1276 ], 1277 "Volumes": { 1278 "/tmp": {} 1279 }, 1280 "WorkingDir": "", 1281 "NetworkDisabled": false, 1282 "ExposedPorts": { 1283 "22/tcp": {} 1284 } 1285 } 1286 1287 **Example response**: 1288 1289 HTTP/1.1 201 Created 1290 Content-Type: application/vnd.docker.raw-stream 1291 1292 {"Id": "596069db4bf5"} 1293 1294 Json Parameters: 1295 1296 - **config** - the container's configuration 1297 1298 Query Parameters: 1299 1300 - **container** – source container 1301 - **repo** – repository 1302 - **tag** – tag 1303 - **comment** – commit message 1304 - **author** – author (e.g., "John Hannibal Smith 1305 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1306 1307 Status Codes: 1308 1309 - **201** – no error 1310 - **404** – no such container 1311 - **500** – server error 1312 1313 ### Monitor Docker's events 1314 1315 `GET /events` 1316 1317 Get container events from docker, either in real time via streaming, or via 1318 polling (using since). 1319 1320 Docker containers will report the following events: 1321 1322 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1323 1324 and Docker images will report: 1325 1326 untag, delete 1327 1328 **Example request**: 1329 1330 GET /events?since=1374067924 1331 1332 **Example response**: 1333 1334 HTTP/1.1 200 OK 1335 Content-Type: application/json 1336 1337 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1338 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1339 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1340 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1341 1342 Query Parameters: 1343 1344 - **since** – timestamp used for polling 1345 - **until** – timestamp used for polling 1346 1347 Status Codes: 1348 1349 - **200** – no error 1350 - **500** – server error 1351 1352 ### Get a tarball containing all images and tags in a repository 1353 1354 `GET /images/(name)/get` 1355 1356 Get a tarball containing all images and metadata for the repository 1357 specified by `name`. 1358 1359 See the [image tarball format](#image-tarball-format) for more details. 1360 1361 **Example request** 1362 1363 GET /images/ubuntu/get 1364 1365 **Example response**: 1366 1367 HTTP/1.1 200 OK 1368 Content-Type: application/x-tar 1369 1370 Binary data stream 1371 1372 Status Codes: 1373 1374 - **200** – no error 1375 - **500** – server error 1376 1377 ### Load a tarball with a set of images and tags into docker 1378 1379 `POST /images/load` 1380 1381 Load a set of images and tags into the docker repository. 1382 See the [image tarball format](#image-tarball-format) for more details. 1383 1384 **Example request** 1385 1386 POST /images/load 1387 1388 Tarball in body 1389 1390 **Example response**: 1391 1392 HTTP/1.1 200 OK 1393 1394 Status Codes: 1395 1396 - **200** – no error 1397 - **500** – server error 1398 1399 ### Image tarball format 1400 1401 An image tarball contains one directory per image layer (named using its long ID), 1402 each containing three files: 1403 1404 1. `VERSION`: currently `1.0` - the file format version 1405 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1406 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1407 1408 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1409 for storing attribute changes and deletions. 1410 1411 If the tarball defines a repository, there will also be a `repositories` file at 1412 the root that contains a list of repository and tag names mapped to layer IDs. 1413 1414 ``` 1415 {"hello-world": 1416 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1417 } 1418 ``` 1419 1420 # 3. Going further 1421 1422 ## 3.1 Inside `docker run` 1423 1424 As an example, the `docker run` command line makes the following API calls: 1425 1426 - Create the container 1427 1428 - If the status code is 404, it means the image doesn't exist: 1429 - Try to pull it 1430 - Then retry to create the container 1431 1432 - Start the container 1433 1434 - If you are not in detached mode: 1435 - Attach to the container, using logs=1 (to have stdout and 1436 stderr from the container's start) and stream=1 1437 1438 - If in detached mode or only stdin is attached: 1439 - Display the container's id 1440 1441 ## 3.2 Hijacking 1442 1443 In this version of the API, /attach, uses hijacking to transport stdin, 1444 stdout and stderr on the same socket. This might change in the future. 1445 1446 ## 3.3 CORS Requests 1447 1448 To enable cross origin requests to the remote api add the flag 1449 "--api-enable-cors" when running docker in daemon mode. 1450 1451 $ docker -d -H="192.168.1.9:2375" --api-enable-cors