github.com/jogo/docker@v1.7.0-rc1/docs/sources/reference/api/docker_remote_api.md (about) 1 page_title: Remote API 2 page_description: API Documentation for Docker 3 page_keywords: API, Docker, rcli, REST, documentation 4 5 # Docker Remote API 6 7 - By default the Docker daemon listens on `unix:///var/run/docker.sock` 8 and the client must have `root` access to interact with the daemon. 9 - If the Docker daemon is set to use an encrypted TCP socket (`--tls`, 10 or `--tlsverify`) as with Boot2Docker 1.3.0, then you need to add extra 11 parameters to `curl` or `wget` when making test API requests: 12 `curl --insecure --cert ~/.docker/cert.pem --key ~/.docker/key.pem https://boot2docker:2376/images/json` 13 or 14 `wget --no-check-certificate --certificate=$DOCKER_CERT_PATH/cert.pem --private-key=$DOCKER_CERT_PATH/key.pem https://boot2docker:2376/images/json -O - -q` 15 - If a group named `docker` exists on your system, docker will apply 16 ownership of the socket to the group. 17 - The API tends to be REST, but for some complex commands, like attach 18 or pull, the HTTP connection is hijacked to transport STDOUT, STDIN, 19 and STDERR. 20 - Since API version 1.2, the auth configuration is now handled client 21 side, so the client has to send the `authConfig` as a `POST` in `/images/(name)/push`. 22 - authConfig, set as the `X-Registry-Auth` header, is currently a Base64 23 encoded (JSON) string with the following structure: 24 `{"username": "string", "password": "string", "email": "string", 25 "serveraddress" : "string", "auth": ""}`. Notice that `auth` is to be left 26 empty, `serveraddress` is a domain/ip without protocol, and that double 27 quotes (instead of single ones) are required. 28 - The Remote API uses an open schema model. In this model, unknown 29 properties in incoming messages will be ignored. 30 Client applications need to take this into account to ensure 31 they will not break when talking to newer Docker daemons. 32 33 The current version of the API is v1.19 34 35 Calling `/info` is the same as calling 36 `/v1.19/info`. 37 38 You can still call an old version of the API using 39 `/v1.18/info`. 40 41 ## Docker Events 42 43 The following diagram depicts the container states accessible through the API. 44 45 ![States](../images/event_state.png) 46 47 Some container-related events are not affected by container state, so they are not included in this diagram. These events are: 48 49 * **export** emitted by `docker export` 50 * **exec_create** emitted by `docker exec` 51 * **exec_start** emitted by `docker exec` after **exec_create** 52 53 Running `docker rmi` emits an **untag** event when removing an image name. The `rmi` command may also emit **delete** events when images are deleted by ID directly or by deleting the last tag referring to the image. 54 55 > **Acknowledgement**: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post [Docker Events Explained](http://gliderlabs.com/blog/2015/04/14/docker-events-explained/). 56 57 ## v1.19 58 59 ### Full documentation 60 61 [*Docker Remote API v1.19*](/reference/api/docker_remote_api_v1.19/) 62 63 ### What's new 64 65 **New!** 66 When the daemon detects a version mismatch with the client, usually when 67 the client is newer than the daemon, an HTTP 400 is now returned instead 68 of a 404. 69 70 `GET /containers/(id)/stats` 71 72 **New!** 73 You can now supply a `stream` bool to get only one set of stats and 74 disconnect 75 76 `GET /containers(id)/logs` 77 78 **New!** 79 80 This endpoint now accepts a `since` timestamp parameter. 81 82 `GET /info` 83 84 **New!** 85 86 The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and `SwapLimit` 87 are now returned as boolean instead of as an int. 88 89 In addition, the end point now returns the new boolean fields 90 `CpuCfsPeriod`, `CpuCfsQuota`, and `OomKillDisable`. 91 92 ## v1.18 93 94 ### Full documentation 95 96 [*Docker Remote API v1.18*](/reference/api/docker_remote_api_v1.18/) 97 98 ### What's new 99 100 `GET /version` 101 102 **New!** 103 This endpoint now returns `Os`, `Arch` and `KernelVersion`. 104 105 `POST /containers/create` 106 `POST /containers/(id)/start` 107 108 **New!** 109 You can set ulimit settings to be used within the container. 110 111 `GET /info` 112 113 **New!** 114 This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`. 115 116 `GET /images/json` 117 118 **New!** 119 Added a `RepoDigests` field to include image digest information. 120 121 `POST /build` 122 123 **New!** 124 Builds can now set resource constraints for all containers created for the build. 125 126 **New!** 127 (`CgroupParent`) can be passed in the host config to setup container cgroups under a specific cgroup. 128 129 `POST /build` 130 131 **New!** 132 Closing the HTTP request will now cause the build to be canceled. 133 134 `POST /containers/(id)/exec` 135 136 **New!** 137 Add `Warnings` field to response. 138 139 ## v1.17 140 141 ### Full documentation 142 143 [*Docker Remote API v1.17*](/reference/api/docker_remote_api_v1.17/) 144 145 ### What's new 146 147 The build supports `LABEL` command. Use this to add metadata 148 to an image. For example you could add data describing the content of an image. 149 150 `LABEL "com.example.vendor"="ACME Incorporated"` 151 152 **New!** 153 `POST /containers/(id)/attach` and `POST /exec/(id)/start` 154 155 **New!** 156 Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers. 157 158 `POST /containers/create` 159 160 **New!** 161 You can set labels on container create describing the container. 162 163 `GET /containers/json` 164 165 **New!** 166 The endpoint returns the labels associated with the containers (`Labels`). 167 168 `GET /containers/(id)/json` 169 170 **New!** 171 This endpoint now returns the list current execs associated with the container (`ExecIDs`). 172 This endpoint now returns the container labels (`Config.Labels`). 173 174 `POST /containers/(id)/rename` 175 176 **New!** 177 New endpoint to rename a container `id` to a new name. 178 179 `POST /containers/create` 180 `POST /containers/(id)/start` 181 182 **New!** 183 (`ReadonlyRootfs`) can be passed in the host config to mount the container's 184 root filesystem as read only. 185 186 `GET /containers/(id)/stats` 187 188 **New!** 189 This endpoint returns a live stream of a container's resource usage statistics. 190 191 `GET /images/json` 192 193 **New!** 194 This endpoint now returns the labels associated with each image (`Labels`). 195 196 197 ## v1.16 198 199 ### Full documentation 200 201 [*Docker Remote API v1.16*](/reference/api/docker_remote_api_v1.16/) 202 203 ### What's new 204 205 `GET /info` 206 207 **New!** 208 `info` now returns the number of CPUs available on the machine (`NCPU`), 209 total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and 210 a list of daemon labels (`Labels`). 211 212 `POST /containers/create` 213 214 **New!** 215 You can set the new container's MAC address explicitly. 216 217 **New!** 218 Volumes are now initialized when the container is created. 219 220 `POST /containers/(id)/copy` 221 222 **New!** 223 You can now copy data which is contained in a volume. 224 225 ## v1.15 226 227 ### Full documentation 228 229 [*Docker Remote API v1.15*](/reference/api/docker_remote_api_v1.15/) 230 231 ### What's new 232 233 `POST /containers/create` 234 235 **New!** 236 It is now possible to set a container's HostConfig when creating a container. 237 Previously this was only available when starting a container. 238 239 ## v1.14 240 241 ### Full documentation 242 243 [*Docker Remote API v1.14*](/reference/api/docker_remote_api_v1.14/) 244 245 ### What's new 246 247 `DELETE /containers/(id)` 248 249 **New!** 250 When using `force`, the container will be immediately killed with SIGKILL. 251 252 `POST /containers/(id)/start` 253 254 **New!** 255 The `hostConfig` option now accepts the field `CapAdd`, which specifies a list of capabilities 256 to add, and the field `CapDrop`, which specifies a list of capabilities to drop. 257 258 `POST /images/create` 259 260 **New!** 261 The `fromImage` and `repo` parameters now supports the `repo:tag` format. 262 Consequently, the `tag` parameter is now obsolete. Using the new format and 263 the `tag` parameter at the same time will return an error. 264 265 ## v1.13 266 267 ### Full documentation 268 269 [*Docker Remote API v1.13*](/reference/api/docker_remote_api_v1.13/) 270 271 ### What's new 272 273 `GET /containers/(name)/json` 274 275 **New!** 276 The `HostConfig.Links` field is now filled correctly 277 278 **New!** 279 `Sockets` parameter added to the `/info` endpoint listing all the sockets the 280 daemon is configured to listen on. 281 282 `POST /containers/(name)/start` 283 `POST /containers/(name)/stop` 284 285 **New!** 286 `start` and `stop` will now return 304 if the container's status is not modified 287 288 `POST /commit` 289 290 **New!** 291 Added a `pause` parameter (default `true`) to pause the container during commit 292 293 ## v1.12 294 295 ### Full documentation 296 297 [*Docker Remote API v1.12*](/reference/api/docker_remote_api_v1.12/) 298 299 ### What's new 300 301 `POST /build` 302 303 **New!** 304 Build now has support for the `forcerm` parameter to always remove containers 305 306 `GET /containers/(name)/json` 307 `GET /images/(name)/json` 308 309 **New!** 310 All the JSON keys are now in CamelCase 311 312 **New!** 313 Trusted builds are now Automated Builds - `is_trusted` is now `is_automated`. 314 315 **Removed Insert Endpoint** 316 The `insert` endpoint has been removed. 317 318 ## v1.11 319 320 ### Full documentation 321 322 [*Docker Remote API v1.11*](/reference/api/docker_remote_api_v1.11/) 323 324 ### What's new 325 326 `GET /_ping` 327 328 **New!** 329 You can now ping the server via the `_ping` endpoint. 330 331 `GET /events` 332 333 **New!** 334 You can now use the `-until` parameter to close connection 335 after timestamp. 336 337 `GET /containers/(id)/logs` 338 339 This url is preferred method for getting container logs now. 340 341 ## v1.10 342 343 ### Full documentation 344 345 [*Docker Remote API v1.10*](/reference/api/docker_remote_api_v1.10/) 346 347 ### What's new 348 349 `DELETE /images/(name)` 350 351 **New!** 352 You can now use the force parameter to force delete of an 353 image, even if it's tagged in multiple repositories. **New!** 354 You 355 can now use the noprune parameter to prevent the deletion of parent 356 images 357 358 `DELETE /containers/(id)` 359 360 **New!** 361 You can now use the force parameter to force delete a 362 container, even if it is currently running 363 364 ## v1.9 365 366 ### Full documentation 367 368 [*Docker Remote API v1.9*](/reference/api/docker_remote_api_v1.9/) 369 370 ### What's new 371 372 `POST /build` 373 374 **New!** 375 This endpoint now takes a serialized ConfigFile which it 376 uses to resolve the proper registry auth credentials for pulling the 377 base image. Clients which previously implemented the version 378 accepting an AuthConfig object must be updated. 379 380 ## v1.8 381 382 ### Full documentation 383 384 [*Docker Remote API v1.8*](/reference/api/docker_remote_api_v1.8/) 385 386 ### What's new 387 388 `POST /build` 389 390 **New!** 391 This endpoint now returns build status as json stream. In 392 case of a build error, it returns the exit status of the failed 393 command. 394 395 `GET /containers/(id)/json` 396 397 **New!** 398 This endpoint now returns the host config for the 399 container. 400 401 `POST /images/create` 402 403 `POST /images/(name)/insert` 404 405 `POST /images/(name)/push` 406 407 **New!** 408 progressDetail object was added in the JSON. It's now 409 possible to get the current value and the total of the progress 410 without having to parse the string. 411 412 ## v1.7 413 414 ### Full documentation 415 416 [*Docker Remote API v1.7*](/reference/api/docker_remote_api_v1.7/) 417 418 ### What's new 419 420 `GET /images/json` 421 422 The format of the json returned from this uri changed. Instead of an 423 entry for each repo/tag on an image, each image is only represented 424 once, with a nested attribute indicating the repo/tags that apply to 425 that image. 426 427 Instead of: 428 429 HTTP/1.1 200 OK 430 Content-Type: application/json 431 432 [ 433 { 434 "VirtualSize": 131506275, 435 "Size": 131506275, 436 "Created": 1365714795, 437 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 438 "Tag": "12.04", 439 "Repository": "ubuntu" 440 }, 441 { 442 "VirtualSize": 131506275, 443 "Size": 131506275, 444 "Created": 1365714795, 445 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 446 "Tag": "latest", 447 "Repository": "ubuntu" 448 }, 449 { 450 "VirtualSize": 131506275, 451 "Size": 131506275, 452 "Created": 1365714795, 453 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 454 "Tag": "precise", 455 "Repository": "ubuntu" 456 }, 457 { 458 "VirtualSize": 180116135, 459 "Size": 24653, 460 "Created": 1364102658, 461 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 462 "Tag": "12.10", 463 "Repository": "ubuntu" 464 }, 465 { 466 "VirtualSize": 180116135, 467 "Size": 24653, 468 "Created": 1364102658, 469 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 470 "Tag": "quantal", 471 "Repository": "ubuntu" 472 } 473 ] 474 475 The returned json looks like this: 476 477 HTTP/1.1 200 OK 478 Content-Type: application/json 479 480 [ 481 { 482 "RepoTags": [ 483 "ubuntu:12.04", 484 "ubuntu:precise", 485 "ubuntu:latest" 486 ], 487 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 488 "Created": 1365714795, 489 "Size": 131506275, 490 "VirtualSize": 131506275 491 }, 492 { 493 "RepoTags": [ 494 "ubuntu:12.10", 495 "ubuntu:quantal" 496 ], 497 "ParentId": "27cf784147099545", 498 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 499 "Created": 1364102658, 500 "Size": 24653, 501 "VirtualSize": 180116135 502 } 503 ] 504 505 `GET /images/viz` 506 507 This URI no longer exists. The `images --viz` 508 output is now generated in the client, using the 509 `/images/json` data. 510 511 ## v1.6 512 513 ### Full documentation 514 515 [*Docker Remote API v1.6*](/reference/api/docker_remote_api_v1.6/) 516 517 ### What's new 518 519 `POST /containers/(id)/attach` 520 521 **New!** 522 You can now split stderr from stdout. This is done by 523 prefixing a header to each transmission. See 524 [`POST /containers/(id)/attach`]( 525 /reference/api/docker_remote_api_v1.9/#attach-to-a-container "POST /containers/(id)/attach"). 526 The WebSocket attach is unchanged. Note that attach calls on the 527 previous API version didn't change. Stdout and stderr are merged. 528 529 ## v1.5 530 531 ### Full documentation 532 533 [*Docker Remote API v1.5*](/reference/api/docker_remote_api_v1.5/) 534 535 ### What's new 536 537 `POST /images/create` 538 539 **New!** 540 You can now pass registry credentials (via an AuthConfig 541 object) through the X-Registry-Auth header 542 543 `POST /images/(name)/push` 544 545 **New!** 546 The AuthConfig object now needs to be passed through the 547 X-Registry-Auth header 548 549 `GET /containers/json` 550 551 **New!** 552 The format of the Ports entry has been changed to a list of 553 dicts each containing PublicPort, PrivatePort and Type describing a 554 port mapping. 555 556 ## v1.4 557 558 ### Full documentation 559 560 [*Docker Remote API v1.4*](/reference/api/docker_remote_api_v1.4/) 561 562 ### What's new 563 564 `POST /images/create` 565 566 **New!** 567 When pulling a repo, all images are now downloaded in parallel. 568 569 `GET /containers/(id)/top` 570 571 **New!** 572 You can now use ps args with docker top, like docker top 573 <container_id> aux 574 575 `GET /events` 576 577 **New!** 578 Image's name added in the events 579 580 ## v1.3 581 582 docker v0.5.0 583 [51f6c4a](https://github.com/docker/docker/commit/51f6c4a7372450d164c61e0054daf0223ddbd909) 584 585 ### Full documentation 586 587 [*Docker Remote API v1.3*](/reference/api/docker_remote_api_v1.3/) 588 589 ### What's new 590 591 `GET /containers/(id)/top` 592 593 List the processes running inside a container. 594 595 `GET /events` 596 597 **New!** 598 Monitor docker's events via streaming or via polling 599 600 Builder (/build): 601 602 - Simplify the upload of the build context 603 - Simply stream a tarball instead of multipart upload with 4 604 intermediary buffers 605 - Simpler, less memory usage, less disk usage and faster 606 607 > **Warning**: 608 > The /build improvements are not reverse-compatible. Pre 1.3 clients will 609 > break on /build. 610 611 List containers (/containers/json): 612 613 - You can use size=1 to get the size of the containers 614 615 Start containers (/containers/<id>/start): 616 617 - You can now pass host-specific configuration (e.g., bind mounts) in 618 the POST body for start calls 619 620 ## v1.2 621 622 docker v0.4.2 623 [2e7649b](https://github.com/docker/docker/commit/2e7649beda7c820793bd46766cbc2cfeace7b168) 624 625 ### Full documentation 626 627 [*Docker Remote API v1.2*](/reference/api/docker_remote_api_v1.2/) 628 629 ### What's new 630 631 The auth configuration is now handled by the client. 632 633 The client should send it's authConfig as POST on each call of 634 `/images/(name)/push` 635 636 `GET /auth` 637 638 **Deprecated.** 639 640 `POST /auth` 641 642 Only checks the configuration but doesn't store it on the server 643 644 Deleting an image is now improved, will only untag the image if it 645 has children and remove all the untagged parents if has any. 646 647 `POST /images/<name>/delete` 648 649 Now returns a JSON structure with the list of images 650 deleted/untagged. 651 652 ## v1.1 653 654 docker v0.4.0 655 [a8ae398](https://github.com/docker/docker/commit/a8ae398bf52e97148ee7bd0d5868de2e15bd297f) 656 657 ### Full documentation 658 659 [*Docker Remote API v1.1*](/reference/api/docker_remote_api_v1.1/) 660 661 ### What's new 662 663 `POST /images/create` 664 665 `POST /images/(name)/insert` 666 667 `POST /images/(name)/push` 668 669 Uses json stream instead of HTML hijack, it looks like this: 670 671 HTTP/1.1 200 OK 672 Content-Type: application/json 673 674 {"status":"Pushing..."} 675 {"status":"Pushing", "progress":"1/? (n/a)"} 676 {"error":"Invalid..."} 677 ... 678 679 ## v1.0 680 681 docker v0.3.4 682 [8d73740](https://github.com/docker/docker/commit/8d73740343778651c09160cde9661f5f387b36f4) 683 684 ### Full documentation 685 686 [*Docker Remote API v1.0*](/reference/api/docker_remote_api_v1.0/) 687 688 ### What's new 689 690 Initial version