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