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