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