github.com/daaku/docker@v1.5.0/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 - **remote** – git or HTTP/HTTPS URI build source 1110 - **q** – suppress verbose build output 1111 - **nocache** – do not use the cache when building the image 1112 - **rm** - remove intermediate containers after a successful build (default behavior) 1113 - **forcerm** - always remove intermediate containers (includes rm) 1114 1115 Request Headers: 1116 1117 - **Content-type** – should be set to `"application/tar"`. 1118 - **X-Registry-Config** – base64-encoded ConfigFile objec 1119 1120 Status Codes: 1121 1122 - **200** – no error 1123 - **500** – server error 1124 1125 ### Check auth configuration 1126 1127 `POST /auth` 1128 1129 Get the default username and email 1130 1131 **Example request**: 1132 1133 POST /auth HTTP/1.1 1134 Content-Type: application/json 1135 1136 { 1137 "username":" hannibal", 1138 "password: "xxxx", 1139 "email": "hannibal@a-team.com", 1140 "serveraddress": "https://index.docker.io/v1/" 1141 } 1142 1143 **Example response**: 1144 1145 HTTP/1.1 200 OK 1146 1147 Status Codes: 1148 1149 - **200** – no error 1150 - **204** – no error 1151 - **500** – server error 1152 1153 ### Display system-wide information 1154 1155 `GET /info` 1156 1157 Display system-wide information 1158 1159 **Example request**: 1160 1161 GET /info HTTP/1.1 1162 1163 **Example response**: 1164 1165 HTTP/1.1 200 OK 1166 Content-Type: application/json 1167 1168 { 1169 "Containers": 11, 1170 "Images": 16, 1171 "Driver": "btrfs", 1172 "ExecutionDriver": "native-0.1", 1173 "KernelVersion": "3.12.0-1-amd64" 1174 "Debug": false, 1175 "NFd": 11, 1176 "NGoroutines": 21, 1177 "NEventsListener": 0, 1178 "InitPath": "/usr/bin/docker", 1179 "IndexServerAddress": ["https://index.docker.io/v1/"], 1180 "MemoryLimit": true, 1181 "SwapLimit": false, 1182 "IPv4Forwarding": true 1183 } 1184 1185 Status Codes: 1186 1187 - **200** – no error 1188 - **500** – server error 1189 1190 ### Show the docker version information 1191 1192 `GET /version` 1193 1194 Show the docker version information 1195 1196 **Example request**: 1197 1198 GET /version HTTP/1.1 1199 1200 **Example response**: 1201 1202 HTTP/1.1 200 OK 1203 Content-Type: application/json 1204 1205 { 1206 "ApiVersion": "1.12", 1207 "Version": "0.2.2", 1208 "GitCommit": "5a2a5cc+CHANGES", 1209 "GoVersion": "go1.0.3" 1210 } 1211 1212 Status Codes: 1213 1214 - **200** – no error 1215 - **500** – server error 1216 1217 ### Ping the docker server 1218 1219 `GET /_ping` 1220 1221 Ping the docker server 1222 1223 **Example request**: 1224 1225 GET /_ping HTTP/1.1 1226 1227 **Example response**: 1228 1229 HTTP/1.1 200 OK 1230 Content-Type: text/plain 1231 1232 OK 1233 1234 Status Codes: 1235 1236 - **200** - no error 1237 - **500** - server error 1238 1239 ### Create a new image from a container's changes 1240 1241 `POST /commit` 1242 1243 Create a new image from a container's changes 1244 1245 **Example request**: 1246 1247 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1248 Content-Type: application/json 1249 1250 { 1251 "Hostname": "", 1252 "Domainname": "", 1253 "User": "", 1254 "Memory": 0, 1255 "MemorySwap": 0, 1256 "CpuShares": 512, 1257 "Cpuset": "0,1", 1258 "AttachStdin": false, 1259 "AttachStdout": true, 1260 "AttachStderr": true, 1261 "PortSpecs": null, 1262 "Tty": false, 1263 "OpenStdin": false, 1264 "StdinOnce": false, 1265 "Env": null, 1266 "Cmd": [ 1267 "date" 1268 ], 1269 "Volumes": { 1270 "/tmp": {} 1271 }, 1272 "WorkingDir": "", 1273 "NetworkDisabled": false, 1274 "ExposedPorts": { 1275 "22/tcp": {} 1276 } 1277 } 1278 1279 **Example response**: 1280 1281 HTTP/1.1 201 Created 1282 Content-Type: application/vnd.docker.raw-stream 1283 1284 {"Id": "596069db4bf5"} 1285 1286 Json Parameters: 1287 1288 - **config** - the container's configuration 1289 1290 Query Parameters: 1291 1292 - **container** – source container 1293 - **repo** – repository 1294 - **tag** – tag 1295 - **comment** – commit message 1296 - **author** – author (e.g., "John Hannibal Smith 1297 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1298 1299 Status Codes: 1300 1301 - **201** – no error 1302 - **404** – no such container 1303 - **500** – server error 1304 1305 ### Monitor Docker's events 1306 1307 `GET /events` 1308 1309 Get container events from docker, either in real time via streaming, or via 1310 polling (using since). 1311 1312 Docker containers will report the following events: 1313 1314 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1315 1316 and Docker images will report: 1317 1318 untag, delete 1319 1320 **Example request**: 1321 1322 GET /events?since=1374067924 1323 1324 **Example response**: 1325 1326 HTTP/1.1 200 OK 1327 Content-Type: application/json 1328 1329 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1330 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1331 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1332 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1333 1334 Query Parameters: 1335 1336 - **since** – timestamp used for polling 1337 - **until** – timestamp used for polling 1338 1339 Status Codes: 1340 1341 - **200** – no error 1342 - **500** – server error 1343 1344 ### Get a tarball containing all images and tags in a repository 1345 1346 `GET /images/(name)/get` 1347 1348 Get a tarball containing all images and metadata for the repository 1349 specified by `name`. 1350 1351 See the [image tarball format](#image-tarball-format) for more details. 1352 1353 **Example request** 1354 1355 GET /images/ubuntu/get 1356 1357 **Example response**: 1358 1359 HTTP/1.1 200 OK 1360 Content-Type: application/x-tar 1361 1362 Binary data stream 1363 1364 Status Codes: 1365 1366 - **200** – no error 1367 - **500** – server error 1368 1369 ### Load a tarball with a set of images and tags into docker 1370 1371 `POST /images/load` 1372 1373 Load a set of images and tags into the docker repository. 1374 See the [image tarball format](#image-tarball-format) for more details. 1375 1376 **Example request** 1377 1378 POST /images/load 1379 1380 Tarball in body 1381 1382 **Example response**: 1383 1384 HTTP/1.1 200 OK 1385 1386 Status Codes: 1387 1388 - **200** – no error 1389 - **500** – server error 1390 1391 ### Image tarball format 1392 1393 An image tarball contains one directory per image layer (named using its long ID), 1394 each containing three files: 1395 1396 1. `VERSION`: currently `1.0` - the file format version 1397 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1398 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1399 1400 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1401 for storing attribute changes and deletions. 1402 1403 If the tarball defines a repository, there will also be a `repositories` file at 1404 the root that contains a list of repository and tag names mapped to layer IDs. 1405 1406 ``` 1407 {"hello-world": 1408 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1409 } 1410 ``` 1411 1412 # 3. Going further 1413 1414 ## 3.1 Inside `docker run` 1415 1416 As an example, the `docker run` command line makes the following API calls: 1417 1418 - Create the container 1419 1420 - If the status code is 404, it means the image doesn't exist: 1421 - Try to pull it 1422 - Then retry to create the container 1423 1424 - Start the container 1425 1426 - If you are not in detached mode: 1427 - Attach to the container, using logs=1 (to have stdout and 1428 stderr from the container's start) and stream=1 1429 1430 - If in detached mode or only stdin is attached: 1431 - Display the container's id 1432 1433 ## 3.2 Hijacking 1434 1435 In this version of the API, /attach, uses hijacking to transport stdin, 1436 stdout and stderr on the same socket. This might change in the future. 1437 1438 ## 3.3 CORS Requests 1439 1440 To enable cross origin requests to the remote api add the flag 1441 "--api-enable-cors" when running docker in daemon mode. 1442 1443 $ docker -d -H="192.168.1.9:2375" --api-enable-cors