moby/docs/sources/reference/api/docker_remote_api.md

page_title: Remote API page_description: API Documentation for Docker page_keywords: API, Docker, rcli, REST, documentation

Docker Remote API

1. Brief introduction

• The Remote API is replacing rcli
• By default the Docker daemon listens on unix:///var/run/docker.sock and the client must have root access to interact with the daemon
• If a group named docker exists on your system, docker will apply ownership of the socket to the group
• The API tends to be REST, but for some complex commands, like attach or pull, the HTTP connection is hijacked to transport stdout stdin and stderr
• Since API version 1.2, the auth configuration is now handled client side, so the client has to send the authConfig as POST in /images/(name)/push
• authConfig, set as the X-Registry-Auth header, is currently a Base64 encoded (json) string with credentials: {'username': string, 'password': string, 'email': string, 'serveraddress' : string}

2. Versions

The current version of the API is 1.11

Calling /images/<name>/insert is the same as calling /v1.11/images/<name>/insert

You can still call an old version of the api using /v1.11/images/<name>/insert

v1.11

Full Documentation

Docker Remote API v1.11

What’s new

GET /events : New! You can now use the -until parameter

to close connection after timestamp.

v1.10

Full Documentation

Docker Remote API v1.10

What’s new

DELETE /images/(name) : New! You can now use the force parameter to force delete of an

image, even if it’s tagged in multiple repositories. **New!** You
can now use the noprune parameter to prevent the deletion of parent
images

DELETE /containers/(id) : New! You can now use the force paramter to force delete a

container, even if it is currently running

v1.9

Full Documentation

Docker Remote API v1.9

What’s new

POST /build : New! This endpoint now takes a serialized ConfigFile which it

uses to resolve the proper registry auth credentials for pulling the
base image. Clients which previously implemented the version
accepting an AuthConfig object must be updated.

v1.8

Full Documentation

What’s new

POST /build : New! This endpoint now returns build status as json stream. In

case of a build error, it returns the exit status of the failed
command.

GET /containers/(id)/json : New! This endpoint now returns the host config for the

container.

POST /images/create :

POST /images/(name)/insert :

POST /images/(name)/push : New! progressDetail object was added in the JSON. It’s now

possible to get the current value and the total of the progress
without having to parse the string.

v1.7

Full Documentation

What’s new

GET /images/json : The format of the json returned from this uri changed. Instead of an

entry for each repo/tag on an image, each image is only represented
once, with a nested attribute indicating the repo/tags that apply to
that image.

Instead of:

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      {
        "VirtualSize": 131506275,
        "Size": 131506275,
        "Created": 1365714795,
        "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
        "Tag": "12.04",
        "Repository": "ubuntu"
      },
      {
        "VirtualSize": 131506275,
        "Size": 131506275,
        "Created": 1365714795,
        "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
        "Tag": "latest",
        "Repository": "ubuntu"
      },
      {
        "VirtualSize": 131506275,
        "Size": 131506275,
        "Created": 1365714795,
        "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
        "Tag": "precise",
        "Repository": "ubuntu"
      },
      {
        "VirtualSize": 180116135,
        "Size": 24653,
        "Created": 1364102658,
        "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
        "Tag": "12.10",
        "Repository": "ubuntu"
      },
      {
        "VirtualSize": 180116135,
        "Size": 24653,
        "Created": 1364102658,
        "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
        "Tag": "quantal",
        "Repository": "ubuntu"
      }
    ]

The returned json looks like this:

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      {
         "RepoTags": [
           "ubuntu:12.04",
           "ubuntu:precise",
           "ubuntu:latest"
         ],
         "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
         "Created": 1365714795,
         "Size": 131506275,
         "VirtualSize": 131506275
      },
      {
         "RepoTags": [
           "ubuntu:12.10",
           "ubuntu:quantal"
         ],
         "ParentId": "27cf784147099545",
         "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
         "Created": 1364102658,
         "Size": 24653,
         "VirtualSize": 180116135
      }
    ]

GET /images/viz : This URI no longer exists. The images --viz

output is now generated in the client, using the
`/images/json` data.

v1.6

Full Documentation

What’s new

POST /containers/(id)/attach : New! You can now split stderr from stdout. This is done by

prefixing a header to each transmition. See
[`POST /containers/(id)/attach`

](../docker_remote_api_v1.9/#post--containers-(id)-attach "POST /containers/(id)/attach").

The WebSocket attach is unchanged. Note that attach calls on the
previous API version didn’t change. Stdout and stderr are merged.

v1.5

Full Documentation

What’s new

POST /images/create : New! You can now pass registry credentials (via an AuthConfig

object) through the X-Registry-Auth header

POST /images/(name)/push : New! The AuthConfig object now needs to be passed through the

X-Registry-Auth header

GET /containers/json : New! The format of the Ports entry has been changed to a list of

dicts each containing PublicPort, PrivatePort and Type describing a
port mapping.

v1.4

Full Documentation

What’s new

POST /images/create : New! When pulling a repo, all images are now downloaded in

parallel.

GET /containers/(id)/top : New! You can now use ps args with docker top, like docker top

\<container\_id\> aux

GET /events: : New! Image’s name added in the events

v1.3

docker v0.5.0 51f6c4a

Full Documentation

What’s new

GET /containers/(id)/top : List the processes running inside a container.

GET /events: : New! Monitor docker’s events via streaming or via polling

Builder (/build):

• Simplify the upload of the build context
• Simply stream a tarball instead of multipart upload with 4 intermediary buffers
• Simpler, less memory usage, less disk usage and faster

Warning

The /build improvements are not reverse-compatible. Pre 1.3 clients will break on /build.

List containers (/containers/json):

• You can use size=1 to get the size of the containers

Start containers (/containers/<id>/start):

• You can now pass host-specific configuration (e.g. bind mounts) in the POST body for start calls

v1.2

docker v0.4.2 2e7649b

Full Documentation

What’s new

The auth configuration is now handled by the client.

The client should send it’s authConfig as POST on each call of /images/(name)/push

GET /auth : Deprecated.

POST /auth : Only checks the configuration but doesn’t store it on the server

Deleting an image is now improved, will only untag the image if it
has children and remove all the untagged parents if has any.

POST /images/<name>/delete : Now returns a JSON structure with the list of images

deleted/untagged.

v1.1

docker v0.4.0 a8ae398

Full Documentation

What’s new

POST /images/create :

POST /images/(name)/insert :

POST /images/(name)/push : Uses json stream instead of HTML hijack, it looks like this:

>     HTTP/1.1 200 OK
>     Content-Type: application/json
>
>     {"status":"Pushing..."}
>     {"status":"Pushing", "progress":"1/? (n/a)"}
>     {"error":"Invalid..."}
>     ...

v1.0

docker v0.3.4 8d73740

Full Documentation

What’s new

Initial version