github.com/eikeon/docker@v1.5.0-rc4/docs/sources/reference/api/docker_remote_api_v1.12.md (about) 1 page_title: Remote API v1.12 2 page_description: API Documentation for Docker 3 page_keywords: API, Docker, rcli, REST, documentation 4 5 # Docker Remote API v1.12 6 7 ## 1. Brief introduction 8 9 - The Remote API has replaced `rcli`. 10 - The daemon listens on `unix:///var/run/docker.sock` but you can 11 [Bind Docker to another host/port or a Unix socket]( 12 /articles/basics/#bind-docker-to-another-hostport-or-a-unix-socket). 13 - The API tends to be REST, but for some complex commands, like `attach` 14 or `pull`, the HTTP connection is hijacked to transport `STDOUT`, 15 `STDIN` and `STDERR`. 16 17 # 2. Endpoints 18 19 ## 2.1 Containers 20 21 ### List containers 22 23 `GET /containers/json` 24 25 List containers 26 27 **Example request**: 28 29 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 30 31 **Example response**: 32 33 HTTP/1.1 200 OK 34 Content-Type: application/json 35 36 [ 37 { 38 "Id": "8dfafdbc3a40", 39 "Image": "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 defaul 83 - **limit** – Show `limit` last created 84 containers, include non-running ones. 85 - **since** – Show only containers created since Id, include 86 non-running ones. 87 - **before** – Show only containers created before Id, include 88 non-running ones. 89 - **size** – 1/True/true or 0/False/false, Show the containers 90 sizes 91 - **filters** – a JSON encoded value of the filters (a map[string][]string) 92 to process on the images list. 93 94 Status Codes: 95 96 - **200** – no error 97 - **400** – bad parameter 98 - **500** – server error 99 100 ### Create a container 101 102 `POST /containers/create` 103 104 Create a container 105 106 **Example request**: 107 108 POST /containers/create HTTP/1.1 109 Content-Type: application/json 110 111 { 112 "Hostname":"", 113 "Domainname": "", 114 "User":"", 115 "Memory":0, 116 "MemorySwap":0, 117 "CpuShares": 512, 118 "Cpuset": "0,1", 119 "AttachStdin":false, 120 "AttachStdout":true, 121 "AttachStderr":true, 122 "PortSpecs":null, 123 "Tty":false, 124 "OpenStdin":false, 125 "StdinOnce":false, 126 "Env":null, 127 "Cmd":[ 128 "date" 129 ], 130 "Image":"ubuntu", 131 "Volumes":{ 132 "/tmp": {} 133 }, 134 "WorkingDir":"", 135 "NetworkDisabled": false, 136 "ExposedPorts":{ 137 "22/tcp": {} 138 } 139 } 140 141 **Example response**: 142 143 HTTP/1.1 201 Created 144 Content-Type: application/json 145 146 { 147 "Id":"e90e34656806" 148 "Warnings":[] 149 } 150 151 Json Parameters: 152 153 - **config** – the container's configuration 154 155 Query Parameters: 156 157 158 159 - **name** – Assign the specified name to the container. Mus 160 match `/?[a-zA-Z0-9_-]+`. 161 162 Status Codes: 163 164 - **201** – no error 165 - **404** – no such container 166 - **406** – impossible to attach (container not running) 167 - **500** – server error 168 169 ### Inspect a container 170 171 `GET /containers/(id)/json` 172 173 Return low-level information on the container `id` 174 175 176 **Example request**: 177 178 GET /containers/4fa6e0f0c678/json HTTP/1.1 179 180 **Example response**: 181 182 HTTP/1.1 200 OK 183 Content-Type: application/json 184 185 { 186 "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", 187 "Created": "2013-05-07T14:51:42.041847+02:00", 188 "Path": "date", 189 "Args": [], 190 "Config": { 191 "Hostname": "4fa6e0f0c678", 192 "User": "", 193 "Memory": 0, 194 "MemorySwap": 0, 195 "AttachStdin": false, 196 "AttachStdout": true, 197 "AttachStderr": true, 198 "PortSpecs": null, 199 "Tty": false, 200 "OpenStdin": false, 201 "StdinOnce": false, 202 "Env": null, 203 "Cmd": [ 204 "date" 205 ], 206 "Dns": null, 207 "Image": "ubuntu", 208 "Volumes": {}, 209 "VolumesFrom": "", 210 "WorkingDir": "" 211 }, 212 "State": { 213 "Running": false, 214 "Pid": 0, 215 "ExitCode": 0, 216 "StartedAt": "2013-05-07T14:51:42.087658+02:01360", 217 "Ghost": false 218 }, 219 "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 220 "NetworkSettings": { 221 "IpAddress": "", 222 "IpPrefixLen": 0, 223 "Gateway": "", 224 "Bridge": "", 225 "PortMapping": null 226 }, 227 "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", 228 "ResolvConfPath": "/etc/resolv.conf", 229 "Volumes": {}, 230 "HostConfig": { 231 "Binds": null, 232 "ContainerIDFile": "", 233 "LxcConf": [], 234 "Privileged": false, 235 "PortBindings": { 236 "80/tcp": [ 237 { 238 "HostIp": "0.0.0.0", 239 "HostPort": "49153" 240 } 241 ] 242 }, 243 "Links": null, 244 "PublishAllPorts": false 245 } 246 } 247 248 Status Codes: 249 250 - **200** – no error 251 - **404** – no such container 252 - **500** – server error 253 254 ### List processes running inside a container 255 256 `GET /containers/(id)/top` 257 258 List processes running inside the container `id` 259 260 **Example request**: 261 262 GET /containers/4fa6e0f0c678/top HTTP/1.1 263 264 **Example response**: 265 266 HTTP/1.1 200 OK 267 Content-Type: application/json 268 269 { 270 "Titles": [ 271 "USER", 272 "PID", 273 "%CPU", 274 "%MEM", 275 "VSZ", 276 "RSS", 277 "TTY", 278 "STAT", 279 "START", 280 "TIME", 281 "COMMAND" 282 ], 283 "Processes": [ 284 ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], 285 ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] 286 ] 287 } 288 289 Query Parameters: 290 291 - **ps_args** – ps arguments to use (e.g., aux) 292 293 Status Codes: 294 295 - **200** – no error 296 - **404** – no such container 297 - **500** – server error 298 299 ### Get container logs 300 301 `GET /containers/(id)/logs` 302 303 Get stdout and stderr logs from the container ``id`` 304 305 **Example request**: 306 307 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1 HTTP/1.1 308 309 **Example response**: 310 311 HTTP/1.1 200 OK 312 Content-Type: application/vnd.docker.raw-stream 313 314 {{ STREAM }} 315 316 Query Parameters: 317 318 319 320 - **follow** – 1/True/true or 0/False/false, return stream. 321 Default false 322 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 323 stdout log. Default false 324 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 325 stderr log. Default false 326 - **timestamps** – 1/True/true or 0/False/false, if logs=true, prin 327 timestamps for every log line. Default false 328 329 Status Codes: 330 331 - **200** – no error 332 - **404** – no such container 333 - **500** – server error 334 335 ### Inspect changes on a container's filesystem 336 337 `GET /containers/(id)/changes` 338 339 Inspect changes on container `id`'s filesystem 340 341 **Example request**: 342 343 GET /containers/4fa6e0f0c678/changes HTTP/1.1 344 345 **Example response**: 346 347 HTTP/1.1 200 OK 348 Content-Type: application/json 349 350 [ 351 { 352 "Path": "/dev", 353 "Kind": 0 354 }, 355 { 356 "Path": "/dev/kmsg", 357 "Kind": 1 358 }, 359 { 360 "Path": "/test", 361 "Kind": 1 362 } 363 ] 364 365 Status Codes: 366 367 - **200** – no error 368 - **404** – no such container 369 - **500** – server error 370 371 ### Export a container 372 373 `GET /containers/(id)/export` 374 375 Export the contents of container `id` 376 377 **Example request**: 378 379 GET /containers/4fa6e0f0c678/export HTTP/1.1 380 381 **Example response**: 382 383 HTTP/1.1 200 OK 384 Content-Type: application/octet-stream 385 386 {{ TAR STREAM }} 387 388 Status Codes: 389 390 - **200** – no error 391 - **404** – no such container 392 - **500** – server error 393 394 ### Start a container 395 396 `POST /containers/(id)/start` 397 398 Start the container `id` 399 400 **Example request**: 401 402 POST /containers/(id)/start HTTP/1.1 403 Content-Type: application/json 404 405 { 406 "Binds":["/tmp:/tmp"], 407 "Links":["redis3:redis"], 408 "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], 409 "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, 410 "PublishAllPorts":false, 411 "Privileged":false, 412 "Dns": ["8.8.8.8"], 413 "VolumesFrom": ["parent", "other:ro"] 414 } 415 416 **Example response**: 417 418 HTTP/1.1 204 No Content 419 Content-Type: text/plain 420 421 Json Parameters: 422 423 424 425 - **hostConfig** – the container's host configuration (optional) 426 427 Status Codes: 428 429 - **204** – no error 430 - **404** – no such container 431 - **500** – server error 432 433 ### Stop a container 434 435 `POST /containers/(id)/stop` 436 437 Stop the container `id` 438 439 **Example request**: 440 441 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 442 443 **Example response**: 444 445 HTTP/1.1 204 No Content 446 447 Query Parameters: 448 449 - **t** – number of seconds to wait before killing the container 450 451 Status Codes: 452 453 - **204** – no error 454 - **404** – no such container 455 - **500** – server error 456 457 ### Restart a container 458 459 `POST /containers/(id)/restart` 460 461 Restart the container `id` 462 463 **Example request**: 464 465 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 466 467 **Example response**: 468 469 HTTP/1.1 204 No Content 470 471 Query Parameters: 472 473 - **t** – number of seconds to wait before killing the container 474 475 Status Codes: 476 477 - **204** – no error 478 - **404** – no such container 479 - **500** – server error 480 481 ### Kill a container 482 483 `POST /containers/(id)/kill` 484 485 Kill the container `id` 486 487 **Example request**: 488 489 POST /containers/e90e34656806/kill HTTP/1.1 490 491 **Example response**: 492 493 HTTP/1.1 204 No Content 494 495 Query Parameters 496 497 - **signal** - Signal to send to the container: integer or string like "SIGINT". 498 When not set, SIGKILL is assumed and the call will wait for the container to exit. 499 500 Status Codes: 501 502 - **204** – no error 503 - **404** – no such container 504 - **500** – server error 505 506 ### Pause a container 507 508 `POST /containers/(id)/pause` 509 510 Pause the container `id` 511 512 **Example request**: 513 514 POST /containers/e90e34656806/pause HTTP/1.1 515 516 **Example response**: 517 518 HTTP/1.1 204 No Content 519 520 Status Codes: 521 522 - **204** – no error 523 - **404** – no such container 524 - **500** – server error 525 526 ### Unpause a container 527 528 `POST /containers/(id)/unpause` 529 530 Unpause the container `id` 531 532 **Example request**: 533 534 POST /containers/e90e34656806/unpause HTTP/1.1 535 536 **Example response**: 537 538 HTTP/1.1 204 No Content 539 540 Status Codes: 541 542 - **204** – no error 543 - **404** – no such container 544 - **500** – server error 545 546 ### Attach to a container 547 548 `POST /containers/(id)/attach` 549 550 Attach to the container `id` 551 552 **Example request**: 553 554 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 555 556 **Example response**: 557 558 HTTP/1.1 200 OK 559 Content-Type: application/vnd.docker.raw-stream 560 561 {{ STREAM }} 562 563 Query Parameters: 564 565 - **logs** – 1/True/true or 0/False/false, return logs. Default false 566 - **stream** – 1/True/true or 0/False/false, return stream. Default false 567 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. 568 Default false 569 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 570 stdout log, if stream=true, attach to stdout. Default false 571 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 572 stderr log, if stream=true, attach to stderr. Default false 573 574 Status Codes: 575 576 - **200** – no error 577 - **400** – bad parameter 578 - **404** – no such container 579 - **500** – server error 580 581 **Stream details**: 582 583 When using the TTY setting is enabled in 584 [`POST /containers/create` 585 ](/reference/api/docker_remote_api_v1.9/#create-a-container "POST /containers/create"), 586 the stream is the raw data from the process PTY and client's stdin. 587 When the TTY is disabled, then the stream is multiplexed to separate 588 stdout and stderr. 589 590 The format is a **Header** and a **Payload** (frame). 591 592 **HEADER** 593 594 The header will contain the information on which stream write the 595 stream (stdout or stderr). It also contain the size of the 596 associated frame encoded on the last 4 bytes (uint32). 597 598 It is encoded on the first 8 bytes like this: 599 600 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 601 602 `STREAM_TYPE` can be: 603 604 - 0: stdin (will be written on stdout) 605 - 1: stdout 606 - 2: stderr 607 608 `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of 609 the uint32 size encoded as big endian. 610 611 **PAYLOAD** 612 613 The payload is the raw stream. 614 615 **IMPLEMENTATION** 616 617 The simplest way to implement the Attach protocol is the following: 618 619 1. Read 8 bytes 620 2. chose stdout or stderr depending on the first byte 621 3. Extract the frame size from the last 4 byets 622 4. Read the extracted size and output it on the correct output 623 5. Goto 1 624 625 ### Attach to a container (websocket) 626 627 `GET /containers/(id)/attach/ws` 628 629 Attach to the container `id` via websocket 630 631 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 632 633 **Example request** 634 635 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 636 637 **Example response** 638 639 {{ STREAM }} 640 641 Query Parameters: 642 643 - **logs** – 1/True/true or 0/False/false, return logs. Default false 644 - **stream** – 1/True/true or 0/False/false, return stream. 645 Default false 646 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 647 to stdin. Default false 648 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 649 stdout log, if stream=true, attach to stdout. Default false 650 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 651 stderr log, if stream=true, attach to stderr. Default false 652 653 Status Codes: 654 655 - **200** – no error 656 - **400** – bad parameter 657 - **404** – no such container 658 - **500** – server error 659 660 ### Wait a container 661 662 `POST /containers/(id)/wait` 663 664 Block until container `id` stops, then returns the exit code 665 666 **Example request**: 667 668 POST /containers/16253994b7c4/wait HTTP/1.1 669 670 **Example response**: 671 672 HTTP/1.1 200 OK 673 Content-Type: application/json 674 675 {"StatusCode": 0} 676 677 Status Codes: 678 679 - **200** – no error 680 - **404** – no such container 681 - **500** – server error 682 683 ### Remove a container 684 685 `DELETE /containers/(id)` 686 687 Remove the container `id` from the filesystem 688 689 **Example request**: 690 691 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 692 693 **Example response**: 694 695 HTTP/1.1 204 No Content 696 697 Query Parameters: 698 699 - **v** – 1/True/true or 0/False/false, Remove the volumes 700 associated to the container. Default false 701 - **force** – 1/True/true or 0/False/false, Removes the container 702 even if it was running. Default false 703 704 Status Codes: 705 706 - **204** – no error 707 - **400** – bad parameter 708 - **404** – no such container 709 - **500** – server error 710 711 ### Copy files or folders from a container 712 713 `POST /containers/(id)/copy` 714 715 Copy files or folders of container `id` 716 717 **Example request**: 718 719 POST /containers/4fa6e0f0c678/copy HTTP/1.1 720 Content-Type: application/json 721 722 { 723 "Resource": "test.txt" 724 } 725 726 **Example response**: 727 728 HTTP/1.1 200 OK 729 Content-Type: application/octet-stream 730 731 {{ TAR STREAM }} 732 733 Status Codes: 734 735 - **200** – no error 736 - **404** – no such container 737 - **500** – server error 738 739 ## 2.2 Images 740 741 ### List Images 742 743 `GET /images/json` 744 745 **Example request**: 746 747 GET /images/json?all=0 HTTP/1.1 748 749 **Example response**: 750 751 HTTP/1.1 200 OK 752 Content-Type: application/json 753 754 [ 755 { 756 "RepoTags": [ 757 "ubuntu:12.04", 758 "ubuntu:precise", 759 "ubuntu:latest" 760 ], 761 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 762 "Created": 1365714795, 763 "Size": 131506275, 764 "VirtualSize": 131506275 765 }, 766 { 767 "RepoTags": [ 768 "ubuntu:12.10", 769 "ubuntu:quantal" 770 ], 771 "ParentId": "27cf784147099545", 772 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 773 "Created": 1364102658, 774 "Size": 24653, 775 "VirtualSize": 180116135 776 } 777 ] 778 779 780 Query Parameters: 781 782 783 784 - **all** – 1/True/true or 0/False/false, default false 785 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 786 - dangling=true 787 788 789 790 ### Create an image 791 792 `POST /images/create` 793 794 Create an image, either by pull it from the registry or by importing i 795 796 **Example request**: 797 798 POST /images/create?fromImage=ubuntu HTTP/1.1 799 800 **Example response**: 801 802 HTTP/1.1 200 OK 803 Content-Type: application/json 804 805 {"status": "Pulling..."} 806 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 807 {"error": "Invalid..."} 808 ... 809 810 When using this endpoint to pull an image from the registry, the 811 `X-Registry-Auth` header can be used to include 812 a base64-encoded AuthConfig object. 813 814 Query Parameters: 815 816 - **fromImage** – name of the image to pull 817 - **fromSrc** – source to import, - means stdin 818 - **repo** – repository 819 - **tag** – tag 820 - **registry** – the registry to pull from 821 822 Request Headers: 823 824 - **X-Registry-Auth** – base64-encoded AuthConfig object 825 826 Status Codes: 827 828 - **200** – no error 829 - **500** – server error 830 831 832 833 ### Inspect an image 834 835 `GET /images/(name)/json` 836 837 Return low-level information on the image `name` 838 839 **Example request**: 840 841 GET /images/ubuntu/json HTTP/1.1 842 843 **Example response**: 844 845 HTTP/1.1 200 OK 846 Content-Type: application/json 847 848 { 849 "Created": "2013-03-23T22:24:18.818426-07:00", 850 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 851 "ContainerConfig": 852 { 853 "Hostname": "", 854 "User": "", 855 "Memory": 0, 856 "MemorySwap": 0, 857 "AttachStdin": false, 858 "AttachStdout": false, 859 "AttachStderr": false, 860 "PortSpecs": null, 861 "Tty": true, 862 "OpenStdin": true, 863 "StdinOnce": false, 864 "Env": null, 865 "Cmd": ["/bin/bash"], 866 "Dns": null, 867 "Image": "ubuntu", 868 "Volumes": null, 869 "VolumesFrom": "", 870 "WorkingDir": "" 871 }, 872 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 873 "Parent": "27cf784147099545", 874 "Size": 6824592 875 } 876 877 Status Codes: 878 879 - **200** – no error 880 - **404** – no such image 881 - **500** – server error 882 883 ### Get the history of an image 884 885 `GET /images/(name)/history` 886 887 Return the history of the image `name` 888 889 **Example request**: 890 891 GET /images/ubuntu/history HTTP/1.1 892 893 **Example response**: 894 895 HTTP/1.1 200 OK 896 Content-Type: application/json 897 898 [ 899 { 900 "Id": "b750fe79269d", 901 "Created": 1364102658, 902 "CreatedBy": "/bin/bash" 903 }, 904 { 905 "Id": "27cf78414709", 906 "Created": 1364068391, 907 "CreatedBy": "" 908 } 909 ] 910 911 Status Codes: 912 913 - **200** – no error 914 - **404** – no such image 915 - **500** – server error 916 917 ### Push an image on the registry 918 919 `POST /images/(name)/push` 920 921 Push the image `name` on the registry 922 923 **Example request**: 924 925 POST /images/test/push HTTP/1.1 926 927 **Example response**: 928 929 HTTP/1.1 200 OK 930 Content-Type: application/json 931 932 {"status": "Pushing..."} 933 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 934 {"error": "Invalid..."} 935 ... 936 937 If you wish to push an image on to a private registry, that image must already have been tagged 938 into a repository which references that registry host name and port. This repository name should 939 then be used in the URL. This mirrors the flow of the CLI. 940 941 **Example request**: 942 943 POST /images/registry.acme.com:5000/test/push HTTP/1.1 944 945 946 Query Parameters: 947 948 - **tag** – the tag to associate with the image on the registry, optional 949 950 Request Headers: 951 952 - **X-Registry-Auth** – include a base64-encoded AuthConfig object. 953 954 Status Codes: 955 956 - **200** – no error 957 - **404** – no such image 958 - **500** – server error 959 960 ### Tag an image into a repository 961 962 `POST /images/(name)/tag` 963 964 Tag the image `name` into a repository 965 966 **Example request**: 967 968 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 969 970 **Example response**: 971 972 HTTP/1.1 201 OK 973 974 Query Parameters: 975 976 - **repo** – The repository to tag in 977 - **force** – 1/True/true or 0/False/false, default false 978 - **tag** - The new tag name 979 980 Status Codes: 981 982 - **201** – no error 983 - **400** – bad parameter 984 - **404** – no such image 985 - **409** – conflict 986 - **500** – server error 987 988 ### Remove an image 989 990 `DELETE /images/(name)` 991 992 Remove the image `name` from the filesystem 993 994 **Example request**: 995 996 DELETE /images/test HTTP/1.1 997 998 **Example response**: 999 1000 HTTP/1.1 200 OK 1001 Content-type: application/json 1002 1003 [ 1004 {"Untagged": "3e2f21a89f"}, 1005 {"Deleted": "3e2f21a89f"}, 1006 {"Deleted": "53b4f83ac9"} 1007 ] 1008 1009 Query Parameters: 1010 1011 - **force** – 1/True/true or 0/False/false, default false 1012 - **noprune** – 1/True/true or 0/False/false, default false 1013 1014 Status Codes: 1015 1016 - **200** – no error 1017 - **404** – no such image 1018 - **409** – conflict 1019 - **500** – server error 1020 1021 ### Search images 1022 1023 `GET /images/search` 1024 1025 Search for an image on [Docker Hub](https://hub.docker.com). 1026 1027 > **Note**: 1028 > The response keys have changed from API v1.6 to reflect the JSON 1029 > sent by the registry server to the docker daemon's request. 1030 1031 **Example request**: 1032 1033 GET /images/search?term=sshd HTTP/1.1 1034 1035 **Example response**: 1036 1037 HTTP/1.1 200 OK 1038 Content-Type: application/json 1039 1040 [ 1041 { 1042 "description": "", 1043 "is_official": false, 1044 "is_automated": false, 1045 "name": "wma55/u1210sshd", 1046 "star_count": 0 1047 }, 1048 { 1049 "description": "", 1050 "is_official": false, 1051 "is_automated": false, 1052 "name": "jdswinbank/sshd", 1053 "star_count": 0 1054 }, 1055 { 1056 "description": "", 1057 "is_official": false, 1058 "is_automated": false, 1059 "name": "vgauthier/sshd", 1060 "star_count": 0 1061 } 1062 ... 1063 ] 1064 1065 Query Parameters: 1066 1067 - **term** – term to search 1068 1069 Status Codes: 1070 1071 - **200** – no error 1072 - **500** – server error 1073 1074 ## 2.3 Misc 1075 1076 ### Build an image from Dockerfile via stdin 1077 1078 `POST /build` 1079 1080 Build an image from Dockerfile via stdin 1081 1082 **Example request**: 1083 1084 POST /build HTTP/1.1 1085 1086 {{ TAR STREAM }} 1087 1088 **Example response**: 1089 1090 HTTP/1.1 200 OK 1091 Content-Type: application/json 1092 1093 {"stream": "Step 1..."} 1094 {"stream": "..."} 1095 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1096 1097 The stream must be a tar archive compressed with one of the 1098 following algorithms: identity (no compression), gzip, bzip2, xz. 1099 1100 The archive must include a file called `Dockerfile` 1101 at its root. It may include any number of other files, 1102 which will be accessible in the build context (See the [*ADD build 1103 command*](/reference/builder/#dockerbuilder)). 1104 1105 Query Parameters: 1106 1107 - **t** – repository name (and optionally a tag) to be applied to 1108 the resulting image in case of success 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