github.com/daaku/docker@v1.5.0/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": "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 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":"ubuntu", 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": "ubuntu", 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 ### Attach to a container (websocket) 619 620 `GET /containers/(id)/attach/ws` 621 622 Attach to the container `id` via websocket 623 624 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 625 626 **Example request** 627 628 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 629 630 **Example response** 631 632 {{ STREAM }} 633 634 Query Parameters: 635 636 - **logs** – 1/True/true or 0/False/false, return logs. Default false 637 - **stream** – 1/True/true or 0/False/false, return stream. 638 Default false 639 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 640 to stdin. Default false 641 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 642 stdout log, if stream=true, attach to stdout. Default false 643 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 644 stderr log, if stream=true, attach to stderr. Default false 645 646 Status Codes: 647 648 - **200** – no error 649 - **400** – bad parameter 650 - **404** – no such container 651 - **500** – server error 652 653 ### Wait a container 654 655 `POST /containers/(id)/wait` 656 657 Block until container `id` stops, then returns the exit code 658 659 **Example request**: 660 661 POST /containers/16253994b7c4/wait HTTP/1.1 662 663 **Example response**: 664 665 HTTP/1.1 200 OK 666 Content-Type: application/json 667 668 {"StatusCode": 0} 669 670 Status Codes: 671 672 - **200** – no error 673 - **404** – no such container 674 - **500** – server error 675 676 ### Remove a container 677 678 `DELETE /containers/(id)` 679 680 Remove the container `id` from the filesystem 681 682 **Example request**: 683 684 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 685 686 **Example response**: 687 688 HTTP/1.1 204 No Content 689 690 Query Parameters: 691 692 - **v** – 1/True/true or 0/False/false, Remove the volumes 693 associated to the container. Default false 694 - **force** – 1/True/true or 0/False/false, Removes the container 695 even if it was running. Default false 696 697 Status Codes: 698 699 - **204** – no error 700 - **400** – bad parameter 701 - **404** – no such container 702 - **500** – server error 703 704 ### Copy files or folders from a container 705 706 `POST /containers/(id)/copy` 707 708 Copy files or folders of container `id` 709 710 **Example request**: 711 712 POST /containers/4fa6e0f0c678/copy HTTP/1.1 713 Content-Type: application/json 714 715 { 716 "Resource": "test.txt" 717 } 718 719 **Example response**: 720 721 HTTP/1.1 200 OK 722 Content-Type: application/octet-stream 723 724 {{ TAR STREAM }} 725 726 Status Codes: 727 728 - **200** – no error 729 - **404** – no such container 730 - **500** – server error 731 732 ## 2.2 Images 733 734 ### List Images 735 736 `GET /images/json` 737 738 **Example request**: 739 740 GET /images/json?all=0 HTTP/1.1 741 742 **Example response**: 743 744 HTTP/1.1 200 OK 745 Content-Type: application/json 746 747 [ 748 { 749 "RepoTags": [ 750 "ubuntu:12.04", 751 "ubuntu:precise", 752 "ubuntu:latest" 753 ], 754 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 755 "Created": 1365714795, 756 "Size": 131506275, 757 "VirtualSize": 131506275 758 }, 759 { 760 "RepoTags": [ 761 "ubuntu:12.10", 762 "ubuntu:quantal" 763 ], 764 "ParentId": "27cf784147099545", 765 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 766 "Created": 1364102658, 767 "Size": 24653, 768 "VirtualSize": 180116135 769 } 770 ] 771 772 773 Query Parameters: 774 775 - **all** – 1/True/true or 0/False/false, default false 776 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 777 - dangling=true 778 779 ### Create an image 780 781 `POST /images/create` 782 783 Create an image, either by pulling it from the registry or by importing it 784 785 **Example request**: 786 787 POST /images/create?fromImage=ubuntu HTTP/1.1 788 789 **Example response**: 790 791 HTTP/1.1 200 OK 792 Content-Type: application/json 793 794 {"status": "Pulling..."} 795 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 796 {"error": "Invalid..."} 797 ... 798 799 When using this endpoint to pull an image from the registry, the 800 `X-Registry-Auth` header can be used to include 801 a base64-encoded AuthConfig object. 802 803 Query Parameters: 804 805 - **fromImage** – name of the image to pull 806 - **fromSrc** – source to import, - means stdin 807 - **repo** – repository 808 - **tag** – tag 809 - **registry** – the registry to pull from 810 811 Request Headers: 812 813 - **X-Registry-Auth** – base64-encoded AuthConfig object 814 815 Status Codes: 816 817 - **200** – no error 818 - **500** – server error 819 820 821 822 ### Inspect an image 823 824 `GET /images/(name)/json` 825 826 Return low-level information on the image `name` 827 828 **Example request**: 829 830 GET /images/ubuntu/json HTTP/1.1 831 832 **Example response**: 833 834 HTTP/1.1 200 OK 835 Content-Type: application/json 836 837 { 838 "Created": "2013-03-23T22:24:18.818426-07:00", 839 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 840 "ContainerConfig": 841 { 842 "Hostname": "", 843 "User": "", 844 "Memory": 0, 845 "MemorySwap": 0, 846 "AttachStdin": false, 847 "AttachStdout": false, 848 "AttachStderr": false, 849 "PortSpecs": null, 850 "Tty": true, 851 "OpenStdin": true, 852 "StdinOnce": false, 853 "Env": null, 854 "Cmd": ["/bin/bash"], 855 "Dns": null, 856 "Image": "ubuntu", 857 "Volumes": null, 858 "VolumesFrom": "", 859 "WorkingDir": "" 860 }, 861 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 862 "Parent": "27cf784147099545", 863 "Size": 6824592 864 } 865 866 Status Codes: 867 868 - **200** – no error 869 - **404** – no such image 870 - **500** – server error 871 872 ### Get the history of an image 873 874 `GET /images/(name)/history` 875 876 Return the history of the image `name` 877 878 **Example request**: 879 880 GET /images/ubuntu/history HTTP/1.1 881 882 **Example response**: 883 884 HTTP/1.1 200 OK 885 Content-Type: application/json 886 887 [ 888 { 889 "Id": "b750fe79269d", 890 "Created": 1364102658, 891 "CreatedBy": "/bin/bash" 892 }, 893 { 894 "Id": "27cf78414709", 895 "Created": 1364068391, 896 "CreatedBy": "" 897 } 898 ] 899 900 Status Codes: 901 902 - **200** – no error 903 - **404** – no such image 904 - **500** – server error 905 906 ### Push an image on the registry 907 908 `POST /images/(name)/push` 909 910 Push the image `name` on the registry 911 912 **Example request**: 913 914 POST /images/test/push HTTP/1.1 915 916 **Example response**: 917 918 HTTP/1.1 200 OK 919 Content-Type: application/json 920 921 {"status": "Pushing..."} 922 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 923 {"error": "Invalid..."} 924 ... 925 926 If you wish to push an image on to a private registry, that image must already have been tagged 927 into a repository which references that registry host name and port. This repository name should 928 then be used in the URL. This mirrors the flow of the CLI. 929 930 **Example request**: 931 932 POST /images/registry.acme.com:5000/test/push HTTP/1.1 933 934 935 Query Parameters: 936 937 - **tag** – the tag to associate with the image on the registry, optional 938 939 Request Headers: 940 941 - **X-Registry-Auth** – include a base64-encoded AuthConfig object. 942 943 Status Codes: 944 945 - **200** – no error 946 - **404** – no such image 947 - **500** – server error 948 949 ### Tag an image into a repository 950 951 `POST /images/(name)/tag` 952 953 Tag the image `name` into a repository 954 955 **Example request**: 956 957 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 958 959 **Example response**: 960 961 HTTP/1.1 201 OK 962 963 Query Parameters: 964 965 - **repo** – The repository to tag in 966 - **force** – 1/True/true or 0/False/false, default false 967 - **tag** - The new tag name 968 969 Status Codes: 970 971 - **201** – no error 972 - **400** – bad parameter 973 - **404** – no such image 974 - **409** – conflict 975 - **500** – server error 976 977 ### Remove an image 978 979 `DELETE /images/(name)` 980 981 Remove the image `name` from the filesystem 982 983 **Example request**: 984 985 DELETE /images/test HTTP/1.1 986 987 **Example response**: 988 989 HTTP/1.1 200 OK 990 Content-type: application/json 991 992 [ 993 {"Untagged": "3e2f21a89f"}, 994 {"Deleted": "3e2f21a89f"}, 995 {"Deleted": "53b4f83ac9"} 996 ] 997 998 Query Parameters: 999 1000 - **force** – 1/True/true or 0/False/false, default false 1001 - **noprune** – 1/True/true or 0/False/false, default false 1002 1003 Status Codes: 1004 1005 - **200** – no error 1006 - **404** – no such image 1007 - **409** – conflict 1008 - **500** – server error 1009 1010 ### Search images 1011 1012 `GET /images/search` 1013 1014 Search for an image on [Docker Hub](https://hub.docker.com). 1015 1016 > **Note**: 1017 > The response keys have changed from API v1.6 to reflect the JSON 1018 > sent by the registry server to the docker daemon's request. 1019 1020 **Example request**: 1021 1022 GET /images/search?term=sshd HTTP/1.1 1023 1024 **Example response**: 1025 1026 HTTP/1.1 200 OK 1027 Content-Type: application/json 1028 1029 [ 1030 { 1031 "description": "", 1032 "is_official": false, 1033 "is_automated": false, 1034 "name": "wma55/u1210sshd", 1035 "star_count": 0 1036 }, 1037 { 1038 "description": "", 1039 "is_official": false, 1040 "is_automated": false, 1041 "name": "jdswinbank/sshd", 1042 "star_count": 0 1043 }, 1044 { 1045 "description": "", 1046 "is_official": false, 1047 "is_automated": false, 1048 "name": "vgauthier/sshd", 1049 "star_count": 0 1050 } 1051 ... 1052 ] 1053 1054 Query Parameters: 1055 1056 - **term** – term to search 1057 1058 Status Codes: 1059 1060 - **200** – no error 1061 - **500** – server error 1062 1063 ## 2.3 Misc 1064 1065 ### Build an image from Dockerfile via stdin 1066 1067 `POST /build` 1068 1069 Build an image from Dockerfile via stdin 1070 1071 **Example request**: 1072 1073 POST /build HTTP/1.1 1074 1075 {{ TAR STREAM }} 1076 1077 **Example response**: 1078 1079 HTTP/1.1 200 OK 1080 Content-Type: application/json 1081 1082 {"stream": "Step 1..."} 1083 {"stream": "..."} 1084 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1085 1086 The stream must be a tar archive compressed with one of the 1087 following algorithms: identity (no compression), gzip, bzip2, xz. 1088 1089 The archive must include a file called `Dockerfile` 1090 at its root. It may include any number of other files, 1091 which will be accessible in the build context (See the [*ADD build 1092 command*](/reference/builder/#dockerbuilder)). 1093 1094 Query Parameters: 1095 1096 - **t** – repository name (and optionally a tag) to be applied to 1097 the resulting image in case of success 1098 - **remote** – git or HTTP/HTTPS URI build source 1099 - **q** – suppress verbose build output 1100 - **nocache** – do not use the cache when building the image 1101 - **rm** - remove intermediate containers after a successful build (default behavior) 1102 - **forcerm** - always remove intermediate containers (includes rm) 1103 1104 Request Headers: 1105 1106 - **Content-type** – should be set to `"application/tar"`. 1107 - **X-Registry-Config** – base64-encoded ConfigFile objec 1108 1109 Status Codes: 1110 1111 - **200** – no error 1112 - **500** – server error 1113 1114 ### Check auth configuration 1115 1116 `POST /auth` 1117 1118 Get the default username and email 1119 1120 **Example request**: 1121 1122 POST /auth HTTP/1.1 1123 Content-Type: application/json 1124 1125 { 1126 "username":" hannibal", 1127 "password: "xxxx", 1128 "email": "hannibal@a-team.com", 1129 "serveraddress": "https://index.docker.io/v1/" 1130 } 1131 1132 **Example response**: 1133 1134 HTTP/1.1 200 OK 1135 1136 Status Codes: 1137 1138 - **200** – no error 1139 - **204** – no error 1140 - **500** – server error 1141 1142 ### Display system-wide information 1143 1144 `GET /info` 1145 1146 Display system-wide information 1147 1148 **Example request**: 1149 1150 GET /info HTTP/1.1 1151 1152 **Example response**: 1153 1154 HTTP/1.1 200 OK 1155 Content-Type: application/json 1156 1157 { 1158 "Containers": 11, 1159 "Images": 16, 1160 "Driver": "btrfs", 1161 "ExecutionDriver": "native-0.1", 1162 "KernelVersion": "3.12.0-1-amd64" 1163 "Debug": false, 1164 "NFd": 11, 1165 "NGoroutines": 21, 1166 "NEventsListener": 0, 1167 "InitPath": "/usr/bin/docker", 1168 "IndexServerAddress": ["https://index.docker.io/v1/"], 1169 "MemoryLimit": true, 1170 "SwapLimit": false, 1171 "IPv4Forwarding": true 1172 } 1173 1174 Status Codes: 1175 1176 - **200** – no error 1177 - **500** – server error 1178 1179 ### Show the docker version information 1180 1181 `GET /version` 1182 1183 Show the docker version information 1184 1185 **Example request**: 1186 1187 GET /version HTTP/1.1 1188 1189 **Example response**: 1190 1191 HTTP/1.1 200 OK 1192 Content-Type: application/json 1193 1194 { 1195 "ApiVersion": "1.12", 1196 "Version": "0.2.2", 1197 "GitCommit": "5a2a5cc+CHANGES", 1198 "GoVersion": "go1.0.3" 1199 } 1200 1201 Status Codes: 1202 1203 - **200** – no error 1204 - **500** – server error 1205 1206 ### Ping the docker server 1207 1208 `GET /_ping` 1209 1210 Ping the docker server 1211 1212 **Example request**: 1213 1214 GET /_ping HTTP/1.1 1215 1216 **Example response**: 1217 1218 HTTP/1.1 200 OK 1219 Content-Type: text/plain 1220 1221 OK 1222 1223 Status Codes: 1224 1225 - **200** - no error 1226 - **500** - server error 1227 1228 ### Create a new image from a container's changes 1229 1230 `POST /commit` 1231 1232 Create a new image from a container's changes 1233 1234 **Example request**: 1235 1236 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1237 Content-Type: application/json 1238 1239 { 1240 "Hostname": "", 1241 "Domainname": "", 1242 "User": "", 1243 "Memory": 0, 1244 "MemorySwap": 0, 1245 "CpuShares": 512, 1246 "Cpuset": "0,1", 1247 "AttachStdin": false, 1248 "AttachStdout": true, 1249 "AttachStderr": true, 1250 "PortSpecs": null, 1251 "Tty": false, 1252 "OpenStdin": false, 1253 "StdinOnce": false, 1254 "Env": null, 1255 "Cmd": [ 1256 "date" 1257 ], 1258 "Volumes": { 1259 "/tmp": {} 1260 }, 1261 "WorkingDir": "", 1262 "NetworkDisabled": false, 1263 "ExposedPorts": { 1264 "22/tcp": {} 1265 } 1266 } 1267 1268 **Example response**: 1269 1270 HTTP/1.1 201 Created 1271 Content-Type: application/vnd.docker.raw-stream 1272 1273 {"Id": "596069db4bf5"} 1274 1275 Json Parameters: 1276 1277 - **config** - the container's configuration 1278 1279 Query Parameters: 1280 1281 - **container** – source container 1282 - **repo** – repository 1283 - **tag** – tag 1284 - **comment** – commit message 1285 - **author** – author (e.g., "John Hannibal Smith 1286 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1287 1288 Status Codes: 1289 1290 - **201** – no error 1291 - **404** – no such container 1292 - **500** – server error 1293 1294 ### Monitor Docker's events 1295 1296 `GET /events` 1297 1298 Get container events from docker, either in real time via streaming, or via 1299 polling (using since). 1300 1301 Docker containers will report the following events: 1302 1303 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1304 1305 and Docker images will report: 1306 1307 untag, delete 1308 1309 **Example request**: 1310 1311 GET /events?since=1374067924 1312 1313 **Example response**: 1314 1315 HTTP/1.1 200 OK 1316 Content-Type: application/json 1317 1318 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1319 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1320 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1321 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1322 1323 Query Parameters: 1324 1325 - **since** – timestamp used for polling 1326 - **until** – timestamp used for polling 1327 1328 Status Codes: 1329 1330 - **200** – no error 1331 - **500** – server error 1332 1333 ### Get a tarball containing all images and tags in a repository 1334 1335 `GET /images/(name)/get` 1336 1337 Get a tarball containing all images and metadata for the repository 1338 specified by `name`. 1339 1340 See the [image tarball format](#image-tarball-format) for more details. 1341 1342 **Example request** 1343 1344 GET /images/ubuntu/get 1345 1346 **Example response**: 1347 1348 HTTP/1.1 200 OK 1349 Content-Type: application/x-tar 1350 1351 Binary data stream 1352 1353 Status Codes: 1354 1355 - **200** – no error 1356 - **500** – server error 1357 1358 ### Load a tarball with a set of images and tags into docker 1359 1360 `POST /images/load` 1361 1362 Load a set of images and tags into the docker repository. 1363 1364 See the [image tarball format](#image-tarball-format) for more details. 1365 1366 **Example request** 1367 1368 POST /images/load 1369 1370 Tarball in body 1371 1372 **Example response**: 1373 1374 HTTP/1.1 200 OK 1375 1376 Status Codes: 1377 1378 - **200** – no error 1379 - **500** – server error 1380 1381 ### Image tarball format 1382 1383 An image tarball contains one directory per image layer (named using its long ID), 1384 each containing three files: 1385 1386 1. `VERSION`: currently `1.0` - the file format version 1387 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1388 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1389 1390 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1391 for storing attribute changes and deletions. 1392 1393 If the tarball defines a repository, there will also be a `repositories` file at 1394 the root that contains a list of repository and tag names mapped to layer IDs. 1395 1396 ``` 1397 {"hello-world": 1398 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1399 } 1400 ``` 1401 1402 # 3. Going further 1403 1404 ## 3.1 Inside `docker run` 1405 1406 As an example, the `docker run` command line makes the following API calls: 1407 1408 - Create the container 1409 1410 - If the status code is 404, it means the image doesn't exist: 1411 - Try to pull it 1412 - Then retry to create the container 1413 1414 - Start the container 1415 1416 - If you are not in detached mode: 1417 - Attach to the container, using logs=1 (to have stdout and 1418 stderr from the container's start) and stream=1 1419 1420 - If in detached mode or only stdin is attached: 1421 - Display the container's id 1422 1423 ## 3.2 Hijacking 1424 1425 In this version of the API, /attach, uses hijacking to transport stdin, 1426 stdout and stderr on the same socket. This might change in the future. 1427 1428 ## 3.3 CORS Requests 1429 1430 To enable cross origin requests to the remote api add the flag 1431 "--api-enable-cors" when running docker in daemon mode. 1432 1433 $ docker -d -H="192.168.1.9:2375" --api-enable-cors