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