page_title: Remote API v1.5 page_description: API Documentation for Docker page_keywords: API, Docker, rcli, REST, documentation # Docker Remote API v1.5 # 1. Brief introduction - The Remote API is replacing rcli - Default port in the docker daemon is 2375 - 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 `GET /containers/json` List containers **Example request**: GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 **Example response**: 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 Parameters:   - **all** – 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default - **limit** – Show `limit` last created containers, include non-running ones. - **since** – Show only containers created since Id, include non-running ones. - **before** – Show only containers created before Id, include non-running ones. - **size** – 1/True/true or 0/False/false, Show the containers sizes Status Codes: - **200** – no error - **400** – bad parameter - **500** – server error ### Create a container `POST /containers/create` Create a container **Example request**: 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**: HTTP/1.1 201 OK Content-Type: application/json { "Id":"e90e34656806" "Warnings":[] } Json Parameters:   - **config** – the container's configuration Status Codes: - **201** – no error - **404** – no such container - **406** – impossible to attach (container not running) - **500** – server error ### Inspect a container `GET /containers/(id)/json` Return low-level information on the container `id` **Example request**: GET /containers/4fa6e0f0c678/json HTTP/1.1 **Example response**: 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": {} } Status Codes: - **200** – no error - **404** – no such container - **500** – server error ### List processes running inside a container `GET /containers/(id)/top` List processes running inside the container `id` **Example request**: GET /containers/4fa6e0f0c678/top HTTP/1.1 **Example response**: 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 Parameters:   - **ps_args** – ps arguments to use (eg. aux) Status Codes: - **200** – no error - **404** – no such container - **500** – server error ### Inspect changes on a container's filesystem `GET /containers/(id)/changes` Inspect changes on container `id`'s filesystem **Example request**: GET /containers/4fa6e0f0c678/changes HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/json [ { "Path":"/dev", "Kind":0 }, { "Path":"/dev/kmsg", "Kind":1 }, { "Path":"/test", "Kind":1 } ] Status Codes: - **200** – no error - **404** – no such container - **500** – server error ### Export a container `GET /containers/(id)/export` Export the contents of container `id` **Example request**: GET /containers/4fa6e0f0c678/export HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/octet-stream {{ STREAM }} Status Codes: - **200** – no error - **404** – no such container - **500** – server error ### Start a container `POST /containers/(id)/start` Start the container `id` **Example request**: POST /containers/(id)/start HTTP/1.1 Content-Type: application/json { "Binds":["/tmp:/tmp"], "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}] } **Example response**: HTTP/1.1 204 No Content Content-Type: text/plain Json Parameters:   - **hostConfig** – the container's host configuration (optional) Status Codes: - **204** – no error - **404** – no such container - **500** – server error ### Stop a container `POST /containers/(id)/stop` Stop the container `id` **Example request**: POST /containers/e90e34656806/stop?t=5 HTTP/1.1 **Example response**: HTTP/1.1 204 OK Query Parameters:   - **t** – number of seconds to wait before killing the container Status Codes: - **204** – no error - **404** – no such container - **500** – server error ### Restart a container `POST /containers/(id)/restart` Restart the container `id` **Example request**: POST /containers/e90e34656806/restart?t=5 HTTP/1.1 **Example response**: HTTP/1.1 204 OK Query Parameters:   - **t** – number of seconds to wait before killing the container Status Codes: - **204** – no error - **404** – no such container - **500** – server error ### Kill a container `POST /containers/(id)/kill` Kill the container `id` **Example request**: POST /containers/e90e34656806/kill HTTP/1.1 **Example response**: HTTP/1.1 204 OK Status Codes: - **204** – no error - **404** – no such container - **500** – server error ### Attach to a container `POST /containers/(id)/attach` Attach to the container `id` **Example request**: POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/vnd.docker.raw-stream {{ STREAM }} Query Parameters:   - **logs** – 1/True/true or 0/False/false, return logs. Default false - **stream** – 1/True/true or 0/False/false, return stream. Default false - **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false - **stdout** – 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false - **stderr** – 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false Status Codes: - **200** – no error - **400** – bad parameter - **404** – no such container - **500** – server error ### Wait a container `POST /containers/(id)/wait` Block until container `id` stops, then returns the exit code **Example request**: POST /containers/16253994b7c4/wait HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/json {"StatusCode":0} Status Codes: - **200** – no error - **404** – no such container - **500** – server error ### Remove a container `DELETE /containers/(id)` Remove the container `id` from the filesystem **Example request**: DELETE /containers/16253994b7c4?v=1 HTTP/1.1 **Example response**: HTTP/1.1 204 OK Query Parameters:   - **v** – 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false Status Codes: - **204** – no error - **400** – bad parameter - **404** – no such container - **500** – server error ### Copy files or folders from a container `POST /containers/(id)/copy` Copy files or folders of container `id` **Example request**: POST /containers/4fa6e0f0c678/copy HTTP/1.1 Content-Type: application/json { "Resource":"test.txt" } **Example response**: HTTP/1.1 200 OK Content-Type: application/octet-stream {{ STREAM }} Status Codes: - **200** – no error - **404** – no such container - **500** – server error ## 2.2 Images ### List Images `GET /images/(format)` List images `format` could be json or viz (json default) **Example request**: GET /images/json?all=0 HTTP/1.1 **Example response**: 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**: GET /images/viz HTTP/1.1 **Example response**: 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 Parameters:   - **all** – 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default Status Codes: - **200** – no error - **400** – bad parameter - **500** – server error ### Create an image `POST /images/create` Create an image, either by pull it from the registry or by importing it **Example request**: POST /images/create?fromImage=ubuntu HTTP/1.1 **Example response**: 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 Parameters:   - **fromImage** – name of the image to pull - **fromSrc** – source to import, - means stdin - **repo** – repository - **tag** – tag - **registry** – the registry to pull from Status Codes: - **200** – no error - **500** – server error ### Insert a file in an image `POST /images/(name)/insert` Insert a file from `url` in the image `name` at `path` **Example request**: POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/json {"status":"Inserting..."} {"status":"Inserting", "progress":"1/? (n/a)"} {"error":"Invalid..."} ... Status Codes: - **200** – no error - **500** – server error ### Inspect an image `GET /images/(name)/json` Return low-level information on the image `name` **Example request**: GET /images/centos/json HTTP/1.1 **Example response**: 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 } Status Codes: - **200** – no error - **404** – no such image - **500** – server error ### Get the history of an image `GET /images/(name)/history` Return the history of the image `name` **Example request**: GET /images/fedora/history HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/json [ { "Id":"b750fe79269d", "Created":1364102658, "CreatedBy":"/bin/bash" }, { "Id":"27cf78414709", "Created":1364068391, "CreatedBy":"" } ] Status Codes: - **200** – no error - **404** – no such image - **500** – server error ### Push an image on the registry `POST /images/(name)/push` Push the image `name` on the registry **Example request**: POST /images/test/push HTTP/1.1 **Example response**: 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 Parameters:   - **registry** – the registry you wan to push, optional Status Codes: - **200** – no error - **404** – no such image - **500** – server error ### Tag an image into a repository `POST /images/(name)/tag` Tag the image `name` into a repository **Example request**: POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1 **Example response**: HTTP/1.1 201 OK Query Parameters:   - **repo** – The repository to tag in - **force** – 1/True/true or 0/False/false, default false Status Codes: - **201** – no error - **400** – bad parameter - **404** – no such image - **409** – conflict - **500** – server error ### Remove an image `DELETE /images/(name)` Remove the image `name` from the filesystem **Example request**: DELETE /images/test HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-type: application/json [ {"Untagged":"3e2f21a89f"}, {"Deleted":"3e2f21a89f"}, {"Deleted":"53b4f83ac9"} ] Status Codes: - **200** – no error - **404** – no such image - **409** – conflict - **500** – server error ### Search images `GET /images/search` Search for an image on [Docker Hub](https://hub.docker.com) **Example request**: GET /images/search?term=sshd HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/json [ { "Name":"cespare/sshd", "Description":"" }, { "Name":"johnfuller/sshd", "Description":"" }, { "Name":"dhrp/mongodb-sshd", "Description":"" } ] Query Parameters:   - **term** – term to search Status Codes: - **200** – no error - **500** – server error ## 2.3 Misc ### Build an image from Dockerfile via stdin `POST /build` Build an image from Dockerfile via stdin **Example request**: POST /build HTTP/1.1 {{ STREAM }} **Example response**: 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 Parameters:   - **t** – repository name (and optionally a tag) to be applied to the resulting image in case of success - **q** – suppress verbose build output - **nocache** – do not use the cache when building the image - **rm** – remove intermediate containers after a successful build Status Codes: - **200** – no error - **500** – server error ### Check auth configuration `POST /auth` Get the default username and email **Example request**: 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**: HTTP/1.1 200 OK Status Codes: - **200** – no error - **204** – no error - **500** – server error ### Display system-wide information `GET /info` Display system-wide information **Example request**: GET /info HTTP/1.1 **Example response**: 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 } Status Codes: - **200** – no error - **500** – server error ### Show the docker version information `GET /version` Show the docker version information **Example request**: GET /version HTTP/1.1 **Example response**: HTTP/1.1 200 OK Content-Type: application/json { "Version":"0.2.2", "GitCommit":"5a2a5cc+CHANGES", "GoVersion":"go1.0.3" } Status Codes: - **200** – no error - **500** – server error ### Create a new image from a container's changes `POST /commit` Create a new image from a container's changes **Example request**: POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 Content-Type: application/json { "Cmd": ["cat", "/world"], "PortSpecs":["22"] } **Example response**: HTTP/1.1 201 OK Content-Type: application/vnd.docker.raw-stream {"Id":"596069db4bf5"} Query Parameters:   - **container** – source container - **repo** – repository - **tag** – tag - **m** – commit message - **author** – author (eg. "John Hannibal Smith <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") Status Codes: - **201** – no error - **404** – no such container - **500** – server error ### Monitor Docker's events `GET /events` Get events from docker, either in real time via streaming, or via polling (using since) **Example request**: GET /events?since=1374067924 **Example response**: 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 Parameters:   - **since** – timestamp used for polling Status Codes: - **200** – no error - **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:2375" --api-enable-cors