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