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