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