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