moby--moby/docs/sources/api/docker_remote_api_v1.5.rst

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

:orphan:

======================
Docker Remote API v1.5
======================

.. contents:: Table of Contents

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":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
        "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,
      "Privileged": false,
      "Tty":false,
      "OpenStdin":false,
      "StdinOnce":false,
      "Env":null,
      "Cmd":[
        "date"
      ],
      "Dns":null,
      "Image":"ubuntu",
      "Volumes":{},
      "VolumesFrom":"",
      "WorkingDir":""
    }

  **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": "",
        "WorkingDir":""
      },
      "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

    {
      "Titles":[
        "USER",
        "PID",
        "%CPU",
        "%MEM",
        "VSZ",
        "RSS",
        "TTY",
        "STAT",
        "START",
        "TIME",
        "COMMAND"
      ],
      "Processes":[
        ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
        ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
      ]
    }

  :query ps_args: ps arguments to use (eg. aux)
  :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"],
      "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}]
    }

  **Example response**:

  .. sourcecode:: http

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

  :jsonparam hostConfig: the container's host configuration (optional)
  :statuscode 204: 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

Copy files or folders from a container
**************************************

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

  Copy files or folders of container ``id``

  **Example request**:

  .. sourcecode:: http

    POST /containers/4fa6e0f0c678/copy HTTP/1.1
    Content-Type: application/json

    {
      "Resource":"test.txt"
    }

  **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

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..."}
    ...

  When using this endpoint to pull an image from the registry,
  the ``X-Registry-Auth`` header can be used to include a
  base64-encoded AuthConfig object.

  :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":"",
          "WorkingDir":""
        },
      "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

  **Example response**:

  .. sourcecode:: http

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

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

  The ``X-Registry-Auth`` header can be used to include a
  base64-encoded AuthConfig object.

  :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
  :query nocache: do not use the cache when building the image
  :query rm: remove intermediate containers after a successful build
  :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":"hannibal@a-team.com",
      "serveraddress":"https://index.docker.io/v1/"
    }

  **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,
      "IPv4Forwarding":true
    }

  :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 <hannibal@a-team.com>")
    :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

    POST /events?since=1374067924

  **Example response**:

  .. sourcecode:: http

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

    {"status":"create","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924}
    {"status":"start","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067924}
    {"status":"stop","id":"dfdf82bd3881","from":"ubuntu:latest","time":1374067966}
    {"status":"destroy","id":"dfdf82bd3881","from":"ubuntu:latest","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.

.. code-block:: bash

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