docker_remote_api_v1.3.rst

orphan:
title:	Remote API v1.3
description:	API Documentation for Docker
keywords:	API, Docker, rcli, REST, documentation

Docker Remote API v1.3

Table of Contents

• Docker Remote API v1.3
  • 1. Brief introduction
  • 2. Endpoints
    • 2.1 Containers
      • List containers
      • Create a container
      • Inspect a container
      • List processes running inside a container
      • Inspect changes on a container's filesystem
      • Export a container
      • Start a container
      • Stop a container
      • Restart a container
      • Kill a container
      • Attach to a container
      • Wait a container
      • Remove a container
    • 2.2 Images
      • List Images
      • Create an image
      • Insert a file in an image
      • Inspect an image
      • Get the history of an image
      • Push an image on the registry
      • Tag an image into a repository
      • Remove an image
      • Search images
    • 2.3 Misc
      • Build an image from Dockerfile via stdin
      • Check auth configuration
      • Display system-wide information
      • Show the docker version information
      • Create a new image from a container's changes
      • Monitor Docker's events
  • 3. Going further
    • 3.1 Inside 'docker run'
    • 3.2 Hijacking
    • 3.3 CORS Requests

1. Brief introduction

• The Remote API is replacing rcli
• Default port in the docker daemon is 4243
• 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

2. Endpoints

2.1 Containers

List containers

.. http:get:: /containers/json

        List containers

        **Example request**:

        .. sourcecode:: http

           GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           [
                {
                        "Id": "8dfafdbc3a40",
                        "Image": "ubuntu:latest",
                        "Command": "echo 1",
                        "Created": 1367854155,
                        "Status": "Exit 0",
                        "Ports":"",
                        "SizeRw":12288,
                        "SizeRootFs":0
                },
                {
                        "Id": "9cd87474be90",
                        "Image": "ubuntu:latest",
                        "Command": "echo 222222",
                        "Created": 1367854155,
                        "Status": "Exit 0",
                        "Ports":"",
                        "SizeRw":12288,
                        "SizeRootFs":0
                },
                {
                        "Id": "3176a2479c92",
                        "Image": "centos:latest",
                        "Command": "echo 3333333333333333",
                        "Created": 1367854154,
                        "Status": "Exit 0",
                        "Ports":"",
                        "SizeRw":12288,
                        "SizeRootFs":0
                },
                {
                        "Id": "4cb07b47f9fb",
                        "Image": "fedora:latest",
                        "Command": "echo 444444444444444444444444444444444",
                        "Created": 1367854152,
                        "Status": "Exit 0",
                        "Ports":"",
                        "SizeRw":12288,
                        "SizeRootFs":0
                }
           ]

        :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
        :query limit: Show ``limit`` last created containers, include non-running ones.
        :query since: Show only containers created since Id, include non-running ones.
        :query before: Show only containers created before Id, include non-running ones.
        :query size: 1/True/true or 0/False/false, Show the containers sizes
        :statuscode 200: no error
        :statuscode 400: bad parameter
        :statuscode 500: server error

Create a container

.. http:post:: /containers/create

        Create a container

        **Example request**:

        .. sourcecode:: http

           POST /containers/create HTTP/1.1
           Content-Type: application/json

           {
                "Hostname":"",
                "User":"",
                "Memory":0,
                "MemorySwap":0,
                "AttachStdin":false,
                "AttachStdout":true,
                "AttachStderr":true,
                "PortSpecs":null,
                "Tty":false,
                "OpenStdin":false,
                "StdinOnce":false,
                "Env":null,
                "Cmd":[
                        "date"
                ],
                "Dns":null,
                "Image":"ubuntu",
                "Volumes":{},
                "VolumesFrom":""
           }

        **Example response**:

        .. sourcecode:: http

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

           {
                "Id":"e90e34656806"
                "Warnings":[]
           }

        :jsonparam config: the container's configuration
        :statuscode 201: no error
        :statuscode 404: no such container
        :statuscode 406: impossible to attach (container not running)
        :statuscode 500: server error

Inspect a container

.. http:get:: /containers/(id)/json

        Return low-level information on the container ``id``

        **Example request**:

        .. sourcecode:: http

           GET /containers/4fa6e0f0c678/json HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {
                        "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
                        "Created": "2013-05-07T14:51:42.041847+02:00",
                        "Path": "date",
                        "Args": [],
                        "Config": {
                                "Hostname": "4fa6e0f0c678",
                                "User": "",
                                "Memory": 0,
                                "MemorySwap": 0,
                                "AttachStdin": false,
                                "AttachStdout": true,
                                "AttachStderr": true,
                                "PortSpecs": null,
                                "Tty": false,
                                "OpenStdin": false,
                                "StdinOnce": false,
                                "Env": null,
                                "Cmd": [
                                        "date"
                                ],
                                "Dns": null,
                                "Image": "ubuntu",
                                "Volumes": {},
                                "VolumesFrom": ""
                        },
                        "State": {
                                "Running": false,
                                "Pid": 0,
                                "ExitCode": 0,
                                "StartedAt": "2013-05-07T14:51:42.087658+02:01360",
                                "Ghost": false
                        },
                        "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
                        "NetworkSettings": {
                                "IpAddress": "",
                                "IpPrefixLen": 0,
                                "Gateway": "",
                                "Bridge": "",
                                "PortMapping": null
                        },
                        "SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker",
                        "ResolvConfPath": "/etc/resolv.conf",
                        "Volumes": {}
           }

        :statuscode 200: no error
        :statuscode 404: no such container
        :statuscode 500: server error

List processes running inside a container

.. http:get:: /containers/(id)/top

        List processes running inside the container ``id``

        **Example request**:

        .. sourcecode:: http

           GET /containers/4fa6e0f0c678/top HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           [
                {
                 "PID":"11935",
                 "Tty":"pts/2",
                 "Time":"00:00:00",
                 "Cmd":"sh"
                },
                {
                 "PID":"12140",
                 "Tty":"pts/2",
                 "Time":"00:00:00",
                 "Cmd":"sleep"
                }
           ]

        :statuscode 200: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Inspect changes on a container's filesystem

.. http:get:: /containers/(id)/changes

        Inspect changes on container ``id`` 's filesystem

        **Example request**:

        .. sourcecode:: http

           GET /containers/4fa6e0f0c678/changes HTTP/1.1


        **Example response**:

        .. sourcecode:: http

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

           [
                {
                        "Path":"/dev",
                        "Kind":0
                },
                {
                        "Path":"/dev/kmsg",
                        "Kind":1
                },
                {
                        "Path":"/test",
                        "Kind":1
                }
           ]

        :statuscode 200: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Export a container

.. http:get:: /containers/(id)/export

        Export the contents of container ``id``

        **Example request**:

        .. sourcecode:: http

           GET /containers/4fa6e0f0c678/export HTTP/1.1


        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 200 OK
           Content-Type: application/octet-stream

           {{ STREAM }}

        :statuscode 200: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Start a container

.. http:post:: /containers/(id)/start

        Start the container ``id``

        **Example request**:

        .. sourcecode:: http

           POST /containers/(id)/start HTTP/1.1
           Content-Type: application/json

           {
                "Binds":["/tmp:/tmp"]
           }

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 204 No Content
           Content-Type: text/plain

        :jsonparam hostConfig: the container's host configuration (optional)
        :statuscode 200: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Stop a container

.. http:post:: /containers/(id)/stop

        Stop the container ``id``

        **Example request**:

        .. sourcecode:: http

           POST /containers/e90e34656806/stop?t=5 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 204 OK

        :query t: number of seconds to wait before killing the container
        :statuscode 204: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Restart a container

.. http:post:: /containers/(id)/restart

        Restart the container ``id``

        **Example request**:

        .. sourcecode:: http

           POST /containers/e90e34656806/restart?t=5 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 204 OK

        :query t: number of seconds to wait before killing the container
        :statuscode 204: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Kill a container

.. http:post:: /containers/(id)/kill

        Kill the container ``id``

        **Example request**:

        .. sourcecode:: http

           POST /containers/e90e34656806/kill HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 204 OK

        :statuscode 204: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Attach to a container

.. http:post:: /containers/(id)/attach

        Attach to the container ``id``

        **Example request**:

        .. sourcecode:: http

           POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 200 OK
           Content-Type: application/vnd.docker.raw-stream

           {{ STREAM }}

        :query logs: 1/True/true or 0/False/false, return logs. Default false
        :query stream: 1/True/true or 0/False/false, return stream. Default false
        :query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false
        :query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false
        :query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false
        :statuscode 200: no error
        :statuscode 400: bad parameter
        :statuscode 404: no such container
        :statuscode 500: server error

Wait a container

.. http:post:: /containers/(id)/wait

        Block until container ``id`` stops, then returns the exit code

        **Example request**:

        .. sourcecode:: http

           POST /containers/16253994b7c4/wait HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {"StatusCode":0}

        :statuscode 200: no error
        :statuscode 404: no such container
        :statuscode 500: server error

Remove a container

.. http:delete:: /containers/(id)

        Remove the container ``id`` from the filesystem

        **Example request**:

        .. sourcecode:: http

           DELETE /containers/16253994b7c4?v=1 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 204 OK

        :query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false
        :statuscode 204: no error
        :statuscode 400: bad parameter
        :statuscode 404: no such container
        :statuscode 500: server error

2.2 Images

List Images

.. http:get:: /images/(format)

        List images ``format`` could be json or viz (json default)

        **Example request**:

        .. sourcecode:: http

           GET /images/json?all=0 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           [
                {
                        "Repository":"ubuntu",
                        "Tag":"precise",
                        "Id":"b750fe79269d",
                        "Created":1364102658,
                        "Size":24653,
                        "VirtualSize":180116135
                },
                {
                        "Repository":"ubuntu",
                        "Tag":"12.04",
                        "Id":"b750fe79269d",
                        "Created":1364102658,
                        "Size":24653,
                        "VirtualSize":180116135
                }
           ]


        **Example request**:

        .. sourcecode:: http

           GET /images/viz HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 200 OK
           Content-Type: text/plain

           digraph docker {
           "d82cbacda43a" -> "074be284591f"
           "1496068ca813" -> "08306dc45919"
           "08306dc45919" -> "0e7893146ac2"
           "b750fe79269d" -> "1496068ca813"
           base -> "27cf78414709" [style=invis]
           "f71189fff3de" -> "9a33b36209ed"
           "27cf78414709" -> "b750fe79269d"
           "0e7893146ac2" -> "d6434d954665"
           "d6434d954665" -> "d82cbacda43a"
           base -> "e9aa60c60128" [style=invis]
           "074be284591f" -> "f71189fff3de"
           "b750fe79269d" [label="b750fe79269d\nubuntu",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
           "e9aa60c60128" [label="e9aa60c60128\ncentos",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
           "9a33b36209ed" [label="9a33b36209ed\nfedora",shape=box,fillcolor="paleturquoise",style="filled,rounded"];
           base [style=invisible]
           }

        :query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
        :statuscode 200: no error
        :statuscode 400: bad parameter
        :statuscode 500: server error

Create an image

.. http:post:: /images/create

        Create an image, either by pull it from the registry or by importing it

        **Example request**:

        .. sourcecode:: http

           POST /images/create?fromImage=ubuntu HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {"status":"Pulling..."}
           {"status":"Pulling", "progress":"1/? (n/a)"}
           {"error":"Invalid..."}
           ...

        :query fromImage: name of the image to pull
        :query fromSrc: source to import, - means stdin
        :query repo: repository
        :query tag: tag
        :query registry: the registry to pull from
        :statuscode 200: no error
        :statuscode 500: server error

Insert a file in an image

.. http:post:: /images/(name)/insert

        Insert a file from ``url`` in the image ``name`` at ``path``

        **Example request**:

        .. sourcecode:: http

           POST /images/test/insert?path=/usr&url=myurl HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {"status":"Inserting..."}
           {"status":"Inserting", "progress":"1/? (n/a)"}
           {"error":"Invalid..."}
           ...

        :statuscode 200: no error
        :statuscode 500: server error

Inspect an image

.. http:get:: /images/(name)/json

        Return low-level information on the image ``name``

        **Example request**:

        .. sourcecode:: http

           GET /images/centos/json HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {
                "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
                "parent":"27cf784147099545",
                "created":"2013-03-23T22:24:18.818426-07:00",
                "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
                "container_config":
                        {
                                "Hostname":"",
                                "User":"",
                                "Memory":0,
                                "MemorySwap":0,
                                "AttachStdin":false,
                                "AttachStdout":false,
                                "AttachStderr":false,
                                "PortSpecs":null,
                                "Tty":true,
                                "OpenStdin":true,
                                "StdinOnce":false,
                                "Env":null,
                                "Cmd": ["/bin/bash"]
                                ,"Dns":null,
                                "Image":"centos",
                                "Volumes":null,
                                "VolumesFrom":""
                        },
                "Size": 6824592
           }

        :statuscode 200: no error
        :statuscode 404: no such image
        :statuscode 500: server error

Get the history of an image

.. http:get:: /images/(name)/history

        Return the history of the image ``name``

        **Example request**:

        .. sourcecode:: http

           GET /images/fedora/history HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           [
                {
                        "Id":"b750fe79269d",
                        "Created":1364102658,
                        "CreatedBy":"/bin/bash"
                },
                {
                        "Id":"27cf78414709",
                        "Created":1364068391,
                        "CreatedBy":""
                }
           ]

        :statuscode 200: no error
        :statuscode 404: no such image
        :statuscode 500: server error

Push an image on the registry

.. http:post:: /images/(name)/push

        Push the image ``name`` on the registry

         **Example request**:

         .. sourcecode:: http

            POST /images/test/push HTTP/1.1
            {{ authConfig }}

         **Example response**:

        .. sourcecode:: http

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

           {"status":"Pushing..."}
           {"status":"Pushing", "progress":"1/? (n/a)"}
           {"error":"Invalid..."}
           ...

        :query registry: the registry you wan to push, optional
        :statuscode 200: no error
        :statuscode 404: no such image
        :statuscode 500: server error

Tag an image into a repository

.. http:post:: /images/(name)/tag

        Tag the image ``name`` into a repository

        **Example request**:

        .. sourcecode:: http

           POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 200 OK

        :query repo: The repository to tag in
        :query force: 1/True/true or 0/False/false, default false
        :statuscode 200: no error
        :statuscode 400: bad parameter
        :statuscode 404: no such image
        :statuscode 409: conflict
        :statuscode 500: server error

Remove an image

.. http:delete:: /images/(name)

        Remove the image ``name`` from the filesystem

        **Example request**:

        .. sourcecode:: http

           DELETE /images/test HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           [
            {"Untagged":"3e2f21a89f"},
            {"Deleted":"3e2f21a89f"},
            {"Deleted":"53b4f83ac9"}
           ]

        :statuscode 200: no error
        :statuscode 404: no such image
        :statuscode 409: conflict
        :statuscode 500: server error

Search images

.. http:get:: /images/search

        Search for an image in the docker index

        **Example request**:

        .. sourcecode:: http

           GET /images/search?term=sshd HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           [
                {
                        "Name":"cespare/sshd",
                        "Description":""
                },
                {
                        "Name":"johnfuller/sshd",
                        "Description":""
                },
                {
                        "Name":"dhrp/mongodb-sshd",
                        "Description":""
                }
           ]

           :query term: term to search
           :statuscode 200: no error
           :statuscode 500: server error

2.3 Misc

Build an image from Dockerfile via stdin

.. http:post:: /build

        Build an image from Dockerfile via stdin

        **Example request**:

        .. sourcecode:: http

           POST /build HTTP/1.1

           {{ STREAM }}

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 200 OK

           {{ STREAM }}


        The stream must be a tar archive compressed with one of the following algorithms:
        identity (no compression), gzip, bzip2, xz. The archive must include a file called
        `Dockerfile` at its root. It may include any number of other files, which will be
        accessible in the build context (See the ADD build command).

        The Content-type header should be set to "application/tar".

        :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
        :query q: suppress verbose build output
        :statuscode 200: no error
        :statuscode 500: server error

Check auth configuration

.. http:post:: /auth

        Get the default username and email

        **Example request**:

        .. sourcecode:: http

           POST /auth HTTP/1.1
           Content-Type: application/json

           {
                "username":"hannibal",
                "password:"xxxx",
                "email":"[email protected]"
           }

        **Example response**:

        .. sourcecode:: http

           HTTP/1.1 200 OK

        :statuscode 200: no error
        :statuscode 204: no error
        :statuscode 500: server error

Display system-wide information

.. http:get:: /info

        Display system-wide information

        **Example request**:

        .. sourcecode:: http

           GET /info HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {
                "Containers":11,
                "Images":16,
                "Debug":false,
                "NFd": 11,
                "NGoroutines":21,
                "MemoryLimit":true,
                "SwapLimit":false,
                "EventsListeners":"0",
                "LXCVersion":"0.7.5",
                "KernelVersion":"3.8.0-19-generic"
           }

        :statuscode 200: no error
        :statuscode 500: server error

Show the docker version information

.. http:get:: /version

        Show the docker version information

        **Example request**:

        .. sourcecode:: http

           GET /version HTTP/1.1

        **Example response**:

        .. sourcecode:: http

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

           {
                "Version":"0.2.2",
                "GitCommit":"5a2a5cc+CHANGES",
                "GoVersion":"go1.0.3"
           }

        :statuscode 200: no error
        :statuscode 500: server error

Create a new image from a container's changes

.. http:post:: /commit

    Create a new image from a container's changes

    **Example request**:

    .. sourcecode:: http

       POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
       Content-Type: application/json

       {
           "Cmd": ["cat", "/world"],
           "PortSpecs":["22"]
       }

    **Example response**:

    .. sourcecode:: http

       HTTP/1.1 201 OK
           Content-Type: application/vnd.docker.raw-stream

       {"Id":"596069db4bf5"}

    :query container: source container
    :query repo: repository
    :query tag: tag
    :query m: commit message
    :query author: author (eg. "John Hannibal Smith <[email protected]>")
    :statuscode 201: no error
    :statuscode 404: no such container
    :statuscode 500: server error

Monitor Docker's events

.. http:get:: /events

        Get events from docker, either in real time via streaming, or via polling (using `since`)

        **Example request**:

        .. sourcecode:: http

           GET /events?since=1374067924

        **Example response**:

        .. sourcecode:: http

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

           {"status":"create","id":"dfdf82bd3881","time":1374067924}
           {"status":"start","id":"dfdf82bd3881","time":1374067924}
           {"status":"stop","id":"dfdf82bd3881","time":1374067966}
           {"status":"destroy","id":"dfdf82bd3881","time":1374067970}

        :query since: timestamp used for polling
        :statuscode 200: no error
        :statuscode 500: server error

3. Going further

3.1 Inside 'docker run'

Here are the steps of 'docker run' :

• Create the container

• If the status code is 404, it means the image doesn't exists:

  • Try to pull it
  • Then retry to create the container

• Start the container

• If you are not in detached mode:

  • Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1

• If in detached mode or only stdin is attached:

  • Display the container's id

3.2 Hijacking

In this version of the API, /attach, uses hijacking to transport stdin, stdout and stderr on the same socket. This might change in the future.

3.3 CORS Requests

To enable cross origin requests to the remote api add the flag "-api-enable-cors" when running docker in daemon mode.

docker -d -H="192.168.1.9:4243" -api-enable-cors