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