github.com/eikeon/docker@v1.5.0-rc4/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 byets 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 - **q** – suppress verbose build output 1049 - **nocache** – do not use the cache when building the image 1050 - **rm** - remove intermediate containers after a successful build 1051 1052 Request Headers: 1053 1054 - **Content-type** – should be set to `"application/tar"`. 1055 - **X-Registry-Config** – base64-encoded ConfigFile objec 1056 1057 Status Codes: 1058 1059 - **200** – no error 1060 - **500** – server error 1061 1062 ### Check auth configuration 1063 1064 `POST /auth` 1065 1066 Get the default username and email 1067 1068 **Example request**: 1069 1070 POST /auth HTTP/1.1 1071 Content-Type: application/json 1072 1073 { 1074 "username":" hannibal", 1075 "password: "xxxx", 1076 "email": "hannibal@a-team.com", 1077 "serveraddress": "https://index.docker.io/v1/" 1078 } 1079 1080 **Example response**: 1081 1082 HTTP/1.1 200 OK 1083 1084 Status Codes: 1085 1086 - **200** – no error 1087 - **204** – no error 1088 - **500** – server error 1089 1090 ### Display system-wide information 1091 1092 `GET /info` 1093 1094 Display system-wide information 1095 1096 **Example request**: 1097 1098 GET /info HTTP/1.1 1099 1100 **Example response**: 1101 1102 HTTP/1.1 200 OK 1103 Content-Type: application/json 1104 1105 { 1106 "Containers": 11, 1107 "Images": 16, 1108 "Driver": "btrfs", 1109 "ExecutionDriver": "native-0.1", 1110 "KernelVersion": "3.12.0-1-amd64" 1111 "Debug": false, 1112 "NFd": 11, 1113 "NGoroutines": 21, 1114 "NEventsListener": 0, 1115 "InitPath": "/usr/bin/docker", 1116 "IndexServerAddress": ["https://index.docker.io/v1/"], 1117 "MemoryLimit": true, 1118 "SwapLimit": false, 1119 "IPv4Forwarding": true 1120 } 1121 1122 Status Codes: 1123 1124 - **200** – no error 1125 - **500** – server error 1126 1127 ### Show the docker version information 1128 1129 `GET /version` 1130 1131 Show the docker version information 1132 1133 **Example request**: 1134 1135 GET /version HTTP/1.1 1136 1137 **Example response**: 1138 1139 HTTP/1.1 200 OK 1140 Content-Type: application/json 1141 1142 { 1143 "Version":"0.2.2", 1144 "GitCommit":"5a2a5cc+CHANGES", 1145 "GoVersion":"go1.0.3" 1146 } 1147 1148 Status Codes: 1149 1150 - **200** – no error 1151 - **500** – server error 1152 1153 ### Ping the docker server 1154 1155 `GET /_ping` 1156 1157 Ping the docker server 1158 1159 **Example request**: 1160 1161 GET /_ping HTTP/1.1 1162 1163 **Example response**: 1164 1165 HTTP/1.1 200 OK 1166 Content-Type: text/plain 1167 1168 OK 1169 1170 Status Codes: 1171 1172 - **200** - no error 1173 - **500** - server error 1174 1175 ### Create a new image from a container's changes 1176 1177 `POST /commit` 1178 1179 Create a new image from a container's changes 1180 1181 **Example request**: 1182 1183 POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 1184 Content-Type: application/json 1185 1186 { 1187 "Hostname":"", 1188 "User":"", 1189 "Memory":0, 1190 "MemorySwap":0, 1191 "AttachStdin":false, 1192 "AttachStdout":true, 1193 "AttachStderr":true, 1194 "PortSpecs":null, 1195 "Tty":false, 1196 "OpenStdin":false, 1197 "StdinOnce":false, 1198 "Env":null, 1199 "Cmd":[ 1200 "date" 1201 ], 1202 "Volumes":{ 1203 "/tmp": {} 1204 }, 1205 "WorkingDir":"", 1206 "DisableNetwork": false, 1207 "ExposedPorts":{ 1208 "22/tcp": {} 1209 } 1210 } 1211 1212 **Example response**: 1213 1214 HTTP/1.1 201 Created 1215 Content-Type: application/vnd.docker.raw-stream 1216 1217 {"Id": "596069db4bf5"} 1218 1219 Json Parameters: 1220 1221 - **config** - the container's configuration 1222 1223 Query Parameters: 1224 1225 - **container** – source container 1226 - **repo** – repository 1227 - **tag** – tag 1228 - **m** – commit message 1229 - **author** – author (e.g., "John Hannibal Smith 1230 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1231 1232 Status Codes: 1233 1234 - **201** – no error 1235 - **404** – no such container 1236 - **500** – server error 1237 1238 ### Monitor Docker's events 1239 1240 `GET /events` 1241 1242 Get container events from docker, either in real time via streaming, or via 1243 polling (using since). 1244 1245 Docker containers will report the following events: 1246 1247 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1248 1249 and Docker images will report: 1250 1251 untag, delete 1252 1253 **Example request**: 1254 1255 GET /events?since=1374067924 1256 1257 **Example response**: 1258 1259 HTTP/1.1 200 OK 1260 Content-Type: application/json 1261 1262 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1263 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1264 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1265 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1266 1267 Query Parameters: 1268 1269 - **since** – timestamp used for polling 1270 - **until** – timestamp used for polling 1271 1272 Status Codes: 1273 1274 - **200** – no error 1275 - **500** – server error 1276 1277 ### Get a tarball containing all images and tags in a repository 1278 1279 `GET /images/(name)/get` 1280 1281 Get a tarball containing all images and metadata for the repository 1282 specified by `name`. 1283 1284 See the [image tarball format](#image-tarball-format) for more details. 1285 1286 **Example request** 1287 1288 GET /images/ubuntu/get 1289 1290 **Example response**: 1291 1292 HTTP/1.1 200 OK 1293 Content-Type: application/x-tar 1294 1295 Binary data stream 1296 1297 Status Codes: 1298 1299 - **200** – no error 1300 - **500** – server error 1301 1302 ### Load a tarball with a set of images and tags into docker 1303 1304 `POST /images/load` 1305 1306 Load a set of images and tags into the docker repository. 1307 1308 See the [image tarball format](#image-tarball-format) for more details. 1309 1310 **Example request** 1311 1312 POST /images/load 1313 1314 Tarball in body 1315 1316 **Example response**: 1317 1318 HTTP/1.1 200 OK 1319 1320 Status Codes: 1321 1322 - **200** – no error 1323 - **500** – server error 1324 1325 ### Image tarball format 1326 1327 An image tarball contains one directory per image layer (named using its long ID), 1328 each containing three files: 1329 1330 1. `VERSION`: currently `1.0` - the file format version 1331 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1332 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1333 1334 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1335 for storing attribute changes and deletions. 1336 1337 If the tarball defines a repository, there will also be a `repositories` file at 1338 the root that contains a list of repository and tag names mapped to layer IDs. 1339 1340 ``` 1341 {"hello-world": 1342 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1343 } 1344 ``` 1345 1346 # 3. Going further 1347 1348 ## 3.1 Inside `docker run` 1349 1350 As an example, the `docker run` command line makes the following API calls: 1351 1352 - Create the container 1353 1354 - If the status code is 404, it means the image doesn't exist: 1355 - Try to pull it 1356 - Then retry to create the container 1357 1358 - Start the container 1359 1360 - If you are not in detached mode: 1361 - Attach to the container, using logs=1 (to have stdout and 1362 stderr from the container's start) and stream=1 1363 1364 - If in detached mode or only stdin is attached: 1365 - Display the container's id 1366 1367 ## 3.2 Hijacking 1368 1369 In this version of the API, /attach, uses hijacking to transport stdin, 1370 stdout and stderr on the same socket. This might change in the future. 1371 1372 ## 3.3 CORS Requests 1373 1374 To enable cross origin requests to the remote api add the flag 1375 "--api-enable-cors" when running docker in daemon mode. 1376 1377 $ docker -d -H="192.168.1.9:2375" --api-enable-cors