github.com/netbrain/docker@v1.9.0-rc2/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](../../articles/basics.md#bind-docker-to-another-hostport-or-a-unix-socket). 19 - The API tends to be REST, but for some complex commands, like `attach` 20 or `pull`, the HTTP connection is hijacked to transport `STDOUT`, 21 `STDIN` and `STDERR`. 22 23 # 2. Endpoints 24 25 ## 2.1 Containers 26 27 ### List containers 28 29 `GET /containers/json` 30 31 List containers 32 33 **Example request**: 34 35 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 36 37 **Example response**: 38 39 HTTP/1.1 200 OK 40 Content-Type: application/json 41 42 [ 43 { 44 "Id": "8dfafdbc3a40", 45 "Image": "ubuntu:latest", 46 "Command": "echo 1", 47 "Created": 1367854155, 48 "Status": "Exit 0", 49 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 50 "SizeRw": 12288, 51 "SizeRootFs": 0 52 }, 53 { 54 "Id": "9cd87474be90", 55 "Image": "ubuntu:latest", 56 "Command": "echo 222222", 57 "Created": 1367854155, 58 "Status": "Exit 0", 59 "Ports": [], 60 "SizeRw": 12288, 61 "SizeRootFs": 0 62 }, 63 { 64 "Id": "3176a2479c92", 65 "Image": "ubuntu:latest", 66 "Command": "echo 3333333333333333", 67 "Created": 1367854154, 68 "Status": "Exit 0", 69 "Ports":[], 70 "SizeRw":12288, 71 "SizeRootFs":0 72 }, 73 { 74 "Id": "4cb07b47f9fb", 75 "Image": "ubuntu:latest", 76 "Command": "echo 444444444444444444444444444444444", 77 "Created": 1367854152, 78 "Status": "Exit 0", 79 "Ports": [], 80 "SizeRw": 12288, 81 "SizeRootFs": 0 82 } 83 ] 84 85 Query Parameters: 86 87 - **all** – 1/True/true or 0/False/false, Show all containers. 88 Only running containers are shown by defaul 89 - **limit** – Show `limit` last created 90 containers, include non-running ones. 91 - **since** – Show only containers created since Id, include 92 non-running ones. 93 - **before** – Show only containers created before Id, include 94 non-running ones. 95 - **size** – 1/True/true or 0/False/false, Show the containers 96 sizes 97 - **filters** – a JSON encoded value of the filters (a map[string][]string) 98 to process on the images list. 99 100 Status Codes: 101 102 - **200** – no error 103 - **400** – bad parameter 104 - **500** – server error 105 106 ### Create a container 107 108 `POST /containers/create` 109 110 Create a container 111 112 **Example request**: 113 114 POST /containers/create HTTP/1.1 115 Content-Type: application/json 116 117 { 118 "Hostname":"", 119 "Domainname": "", 120 "User":"", 121 "Memory":0, 122 "MemorySwap":0, 123 "CpuShares": 512, 124 "Cpuset": "0,1", 125 "AttachStdin":false, 126 "AttachStdout":true, 127 "AttachStderr":true, 128 "PortSpecs":null, 129 "Tty":false, 130 "OpenStdin":false, 131 "StdinOnce":false, 132 "Env":null, 133 "Cmd":[ 134 "date" 135 ], 136 "Image":"ubuntu", 137 "Volumes":{ 138 "/tmp": {} 139 }, 140 "WorkingDir":"", 141 "NetworkDisabled": false, 142 "ExposedPorts":{ 143 "22/tcp": {} 144 } 145 } 146 147 **Example response**: 148 149 HTTP/1.1 201 Created 150 Content-Type: application/json 151 152 { 153 "Id":"e90e34656806" 154 "Warnings":[] 155 } 156 157 Json Parameters: 158 159 - **config** – the container's configuration 160 161 Query Parameters: 162 163 164 165 - **name** – Assign the specified name to the container. Mus 166 match `/?[a-zA-Z0-9_-]+`. 167 168 Status Codes: 169 170 - **201** – no error 171 - **404** – no such container 172 - **406** – impossible to attach (container not running) 173 - **500** – server error 174 175 ### Inspect a container 176 177 `GET /containers/(id)/json` 178 179 Return low-level information on the container `id` 180 181 182 **Example request**: 183 184 GET /containers/4fa6e0f0c678/json HTTP/1.1 185 186 **Example response**: 187 188 HTTP/1.1 200 OK 189 Content-Type: application/json 190 191 { 192 "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", 193 "Created": "2013-05-07T14:51:42.041847+02:00", 194 "Path": "date", 195 "Args": [], 196 "Config": { 197 "Hostname": "4fa6e0f0c678", 198 "User": "", 199 "Memory": 0, 200 "MemorySwap": 0, 201 "AttachStdin": false, 202 "AttachStdout": true, 203 "AttachStderr": true, 204 "PortSpecs": null, 205 "Tty": false, 206 "OpenStdin": false, 207 "StdinOnce": false, 208 "Env": null, 209 "Cmd": [ 210 "date" 211 ], 212 "Dns": null, 213 "Image": "ubuntu", 214 "Volumes": {}, 215 "VolumesFrom": "", 216 "WorkingDir": "" 217 }, 218 "State": { 219 "Running": false, 220 "Pid": 0, 221 "ExitCode": 0, 222 "StartedAt": "2013-05-07T14:51:42.087658+02:01360", 223 "Ghost": false 224 }, 225 "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 226 "NetworkSettings": { 227 "IpAddress": "", 228 "IpPrefixLen": 0, 229 "Gateway": "", 230 "Bridge": "", 231 "PortMapping": null 232 }, 233 "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", 234 "ResolvConfPath": "/etc/resolv.conf", 235 "Volumes": {}, 236 "HostConfig": { 237 "Binds": null, 238 "ContainerIDFile": "", 239 "LxcConf": [], 240 "Privileged": false, 241 "PortBindings": { 242 "80/tcp": [ 243 { 244 "HostIp": "0.0.0.0", 245 "HostPort": "49153" 246 } 247 ] 248 }, 249 "Links": null, 250 "PublishAllPorts": false 251 } 252 } 253 254 Status Codes: 255 256 - **200** – no error 257 - **404** – no such container 258 - **500** – server error 259 260 ### List processes running inside a container 261 262 `GET /containers/(id)/top` 263 264 List processes running inside the container `id` 265 266 **Example request**: 267 268 GET /containers/4fa6e0f0c678/top HTTP/1.1 269 270 **Example response**: 271 272 HTTP/1.1 200 OK 273 Content-Type: application/json 274 275 { 276 "Titles": [ 277 "USER", 278 "PID", 279 "%CPU", 280 "%MEM", 281 "VSZ", 282 "RSS", 283 "TTY", 284 "STAT", 285 "START", 286 "TIME", 287 "COMMAND" 288 ], 289 "Processes": [ 290 ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], 291 ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] 292 ] 293 } 294 295 Query Parameters: 296 297 - **ps_args** – ps arguments to use (e.g., aux) 298 299 Status Codes: 300 301 - **200** – no error 302 - **404** – no such container 303 - **500** – server error 304 305 ### Get container logs 306 307 `GET /containers/(id)/logs` 308 309 Get stdout and stderr logs from the container ``id`` 310 311 **Example request**: 312 313 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1 HTTP/1.1 314 315 **Example response**: 316 317 HTTP/1.1 200 OK 318 Content-Type: application/vnd.docker.raw-stream 319 320 {{ STREAM }} 321 322 Query Parameters: 323 324 325 326 - **follow** – 1/True/true or 0/False/false, return stream. 327 Default false 328 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 329 stdout log. Default false 330 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 331 stderr log. Default false 332 - **timestamps** – 1/True/true or 0/False/false, if logs=true, prin 333 timestamps for every log line. Default false 334 335 Status Codes: 336 337 - **200** – no error 338 - **404** – no such container 339 - **500** – server error 340 341 ### Inspect changes on a container's filesystem 342 343 `GET /containers/(id)/changes` 344 345 Inspect changes on container `id`'s filesystem 346 347 **Example request**: 348 349 GET /containers/4fa6e0f0c678/changes HTTP/1.1 350 351 **Example response**: 352 353 HTTP/1.1 200 OK 354 Content-Type: application/json 355 356 [ 357 { 358 "Path": "/dev", 359 "Kind": 0 360 }, 361 { 362 "Path": "/dev/kmsg", 363 "Kind": 1 364 }, 365 { 366 "Path": "/test", 367 "Kind": 1 368 } 369 ] 370 371 Status Codes: 372 373 - **200** – no error 374 - **404** – no such container 375 - **500** – server error 376 377 ### Export a container 378 379 `GET /containers/(id)/export` 380 381 Export the contents of container `id` 382 383 **Example request**: 384 385 GET /containers/4fa6e0f0c678/export HTTP/1.1 386 387 **Example response**: 388 389 HTTP/1.1 200 OK 390 Content-Type: application/octet-stream 391 392 {{ TAR STREAM }} 393 394 Status Codes: 395 396 - **200** – no error 397 - **404** – no such container 398 - **500** – server error 399 400 ### Start a container 401 402 `POST /containers/(id)/start` 403 404 Start the container `id` 405 406 **Example request**: 407 408 POST /containers/(id)/start HTTP/1.1 409 Content-Type: application/json 410 411 { 412 "Binds":["/tmp:/tmp"], 413 "Links":["redis3:redis"], 414 "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], 415 "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, 416 "PublishAllPorts":false, 417 "Privileged":false, 418 "Dns": ["8.8.8.8"], 419 "VolumesFrom": ["parent", "other:ro"] 420 } 421 422 **Example response**: 423 424 HTTP/1.1 204 No Content 425 Content-Type: text/plain 426 427 Json Parameters: 428 429 430 431 - **hostConfig** – the container's host configuration (optional) 432 433 Status Codes: 434 435 - **204** – no error 436 - **404** – no such container 437 - **500** – server error 438 439 ### Stop a container 440 441 `POST /containers/(id)/stop` 442 443 Stop the container `id` 444 445 **Example request**: 446 447 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 448 449 **Example response**: 450 451 HTTP/1.1 204 No Content 452 453 Query Parameters: 454 455 - **t** – number of seconds to wait before killing the container 456 457 Status Codes: 458 459 - **204** – no error 460 - **404** – no such container 461 - **500** – server error 462 463 ### Restart a container 464 465 `POST /containers/(id)/restart` 466 467 Restart the container `id` 468 469 **Example request**: 470 471 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 472 473 **Example response**: 474 475 HTTP/1.1 204 No Content 476 477 Query Parameters: 478 479 - **t** – number of seconds to wait before killing the container 480 481 Status Codes: 482 483 - **204** – no error 484 - **404** – no such container 485 - **500** – server error 486 487 ### Kill a container 488 489 `POST /containers/(id)/kill` 490 491 Kill the container `id` 492 493 **Example request**: 494 495 POST /containers/e90e34656806/kill HTTP/1.1 496 497 **Example response**: 498 499 HTTP/1.1 204 No Content 500 501 Query Parameters 502 503 - **signal** - Signal to send to the container: integer or string like "SIGINT". 504 When not set, SIGKILL is assumed and the call will wait for the container to exit. 505 506 Status Codes: 507 508 - **204** – no error 509 - **404** – no such container 510 - **500** – server error 511 512 ### Pause a container 513 514 `POST /containers/(id)/pause` 515 516 Pause the container `id` 517 518 **Example request**: 519 520 POST /containers/e90e34656806/pause HTTP/1.1 521 522 **Example response**: 523 524 HTTP/1.1 204 No Content 525 526 Status Codes: 527 528 - **204** – no error 529 - **404** – no such container 530 - **500** – server error 531 532 ### Unpause a container 533 534 `POST /containers/(id)/unpause` 535 536 Unpause the container `id` 537 538 **Example request**: 539 540 POST /containers/e90e34656806/unpause HTTP/1.1 541 542 **Example response**: 543 544 HTTP/1.1 204 No Content 545 546 Status Codes: 547 548 - **204** – no error 549 - **404** – no such container 550 - **500** – server error 551 552 ### Attach to a container 553 554 `POST /containers/(id)/attach` 555 556 Attach to the container `id` 557 558 **Example request**: 559 560 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 561 562 **Example response**: 563 564 HTTP/1.1 200 OK 565 Content-Type: application/vnd.docker.raw-stream 566 567 {{ STREAM }} 568 569 Query Parameters: 570 571 - **logs** – 1/True/true or 0/False/false, return logs. Default false 572 - **stream** – 1/True/true or 0/False/false, return stream. Default false 573 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. 574 Default false 575 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 576 stdout log, if stream=true, attach to stdout. Default false 577 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 578 stderr log, if stream=true, attach to stderr. Default false 579 580 Status Codes: 581 582 - **200** – no error 583 - **400** – bad parameter 584 - **404** – no such container 585 - **500** – server error 586 587 **Stream details**: 588 589 When using the TTY setting is enabled in 590 [`POST /containers/create` 591 ](docker_remote_api_v1.9.md#create-a-container), 592 the stream is the raw data from the process PTY and client's stdin. 593 When the TTY is disabled, then the stream is multiplexed to separate 594 stdout and stderr. 595 596 The format is a **Header** and a **Payload** (frame). 597 598 **HEADER** 599 600 The header will contain the information on which stream write the 601 stream (stdout or stderr). It also contain the size of the 602 associated frame encoded on the last 4 bytes (uint32). 603 604 It is encoded on the first 8 bytes like this: 605 606 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 607 608 `STREAM_TYPE` can be: 609 610 - 0: stdin (will be written on stdout) 611 - 1: stdout 612 - 2: stderr 613 614 `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of 615 the uint32 size encoded as big endian. 616 617 **PAYLOAD** 618 619 The payload is the raw stream. 620 621 **IMPLEMENTATION** 622 623 The simplest way to implement the Attach protocol is the following: 624 625 1. Read 8 bytes 626 2. chose stdout or stderr depending on the first byte 627 3. Extract the frame size from the last 4 bytes 628 4. Read the extracted size and output it on the correct output 629 5. Goto 1 630 631 ### Attach to a container (websocket) 632 633 `GET /containers/(id)/attach/ws` 634 635 Attach to the container `id` via websocket 636 637 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 638 639 **Example request** 640 641 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 642 643 **Example response** 644 645 {{ STREAM }} 646 647 Query Parameters: 648 649 - **logs** – 1/True/true or 0/False/false, return logs. Default false 650 - **stream** – 1/True/true or 0/False/false, return stream. 651 Default false 652 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 653 to stdin. Default false 654 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 655 stdout log, if stream=true, attach to stdout. Default false 656 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 657 stderr log, if stream=true, attach to stderr. Default false 658 659 Status Codes: 660 661 - **200** – no error 662 - **400** – bad parameter 663 - **404** – no such container 664 - **500** – server error 665 666 ### Wait a container 667 668 `POST /containers/(id)/wait` 669 670 Block until container `id` stops, then returns the exit code 671 672 **Example request**: 673 674 POST /containers/16253994b7c4/wait HTTP/1.1 675 676 **Example response**: 677 678 HTTP/1.1 200 OK 679 Content-Type: application/json 680 681 {"StatusCode": 0} 682 683 Status Codes: 684 685 - **200** – no error 686 - **404** – no such container 687 - **500** – server error 688 689 ### Remove a container 690 691 `DELETE /containers/(id)` 692 693 Remove the container `id` from the filesystem 694 695 **Example request**: 696 697 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 698 699 **Example response**: 700 701 HTTP/1.1 204 No Content 702 703 Query Parameters: 704 705 - **v** – 1/True/true or 0/False/false, Remove the volumes 706 associated to the container. Default false 707 - **force** – 1/True/true or 0/False/false, Removes the container 708 even if it was running. Default false 709 710 Status Codes: 711 712 - **204** – no error 713 - **400** – bad parameter 714 - **404** – no such container 715 - **500** – server error 716 717 ### Copy files or folders from a container 718 719 `POST /containers/(id)/copy` 720 721 Copy files or folders of container `id` 722 723 **Example request**: 724 725 POST /containers/4fa6e0f0c678/copy HTTP/1.1 726 Content-Type: application/json 727 728 { 729 "Resource": "test.txt" 730 } 731 732 **Example response**: 733 734 HTTP/1.1 200 OK 735 Content-Type: application/octet-stream 736 737 {{ TAR STREAM }} 738 739 Status Codes: 740 741 - **200** – no error 742 - **404** – no such container 743 - **500** – server error 744 745 ## 2.2 Images 746 747 ### List Images 748 749 `GET /images/json` 750 751 **Example request**: 752 753 GET /images/json?all=0 HTTP/1.1 754 755 **Example response**: 756 757 HTTP/1.1 200 OK 758 Content-Type: application/json 759 760 [ 761 { 762 "RepoTags": [ 763 "ubuntu:12.04", 764 "ubuntu:precise", 765 "ubuntu:latest" 766 ], 767 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 768 "Created": 1365714795, 769 "Size": 131506275, 770 "VirtualSize": 131506275 771 }, 772 { 773 "RepoTags": [ 774 "ubuntu:12.10", 775 "ubuntu:quantal" 776 ], 777 "ParentId": "27cf784147099545", 778 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 779 "Created": 1364102658, 780 "Size": 24653, 781 "VirtualSize": 180116135 782 } 783 ] 784 785 786 Query Parameters: 787 788 789 790 - **all** – 1/True/true or 0/False/false, default false 791 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 792 - dangling=true 793 - **filter** - only return images with the specified name 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.md#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/json 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