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