github.com/pritambaral/docker@v1.4.2-0.20150120174542-b2fe1b3dd952/docs/sources/reference/api/docker_remote_api_v1.7.md (about)

     1  page_title: Remote API v1.7
     2  page_description: API Documentation for Docker
     3  page_keywords: API, Docker, rcli, REST, documentation
     4  
     5  # Docker Remote API v1.7
     6  
     7  # 1. Brief introduction
     8  
     9   - The Remote API has replaced rcli
    10   - The daemon listens on `unix:///var/run/docker.sock` but you can bind
    11     Docker to another host/port or a Unix socket.
    12   - The API tends to be REST, but for some complex commands, like `attach`
    13     or `pull`, the HTTP connection is hijacked to transport `stdout, stdin`
    14     and `stderr`
    15  
    16  # 2. Endpoints
    17  
    18  ## 2.1 Containers
    19  
    20  ### List containers
    21  
    22  `GET /containers/json`
    23  
    24  List containers
    25  
    26  **Example request**:
    27  
    28          GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
    29  
    30  **Example response**:
    31  
    32          HTTP/1.1 200 OK
    33          Content-Type: application/json
    34  
    35          [
    36               {
    37                       "Id": "8dfafdbc3a40",
    38                       "Image": "base:latest",
    39                       "Command": "echo 1",
    40                       "Created": 1367854155,
    41                       "Status": "Exit 0",
    42                       "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
    43                       "SizeRw": 12288,
    44                       "SizeRootFs": 0
    45               },
    46               {
    47                       "Id": "9cd87474be90",
    48                       "Image": "base:latest",
    49                       "Command": "echo 222222",
    50                       "Created": 1367854155,
    51                       "Status": "Exit 0",
    52                       "Ports": [],
    53                       "SizeRw": 12288,
    54                       "SizeRootFs": 0
    55               },
    56               {
    57                       "Id": "3176a2479c92",
    58                       "Image": "base:latest",
    59                       "Command": "echo 3333333333333333",
    60                       "Created": 1367854154,
    61                       "Status": "Exit 0",
    62                       "Ports":[],
    63                       "SizeRw":12288,
    64                       "SizeRootFs":0
    65               },
    66               {
    67                       "Id": "4cb07b47f9fb",
    68                       "Image": "base:latest",
    69                       "Command": "echo 444444444444444444444444444444444",
    70                       "Created": 1367854152,
    71                       "Status": "Exit 0",
    72                       "Ports": [],
    73                       "SizeRw": 12288,
    74                       "SizeRootFs": 0
    75               }
    76          ]
    77  
    78  Query Parameters:
    79  
    80  -   **all** – 1/True/true or 0/False/false, Show all containers.
    81      Only running containers are shown by default (i.e., this defaults to false)
    82  -   **limit** – Show `limit` last created containers, include non-running ones.
    83  -   **since** – Show only containers created since Id, include non-running ones.
    84  -   **before** – Show only containers created before Id, include non-running ones.
    85  -   **size** – 1/True/true or 0/False/false, Show the containers sizes
    86  
    87  Status Codes:
    88  
    89  -   **200** – no error
    90  -   **400** – bad parameter
    91  -   **500** – server error
    92  
    93  ### Create a container
    94  
    95  `POST /containers/create`
    96  
    97  Create a container
    98  
    99  **Example request**:
   100  
   101          POST /containers/create HTTP/1.1
   102          Content-Type: application/json
   103  
   104          {
   105               "Hostname":"",
   106               "User":"",
   107               "Memory":0,
   108               "MemorySwap":0,
   109               "AttachStdin":false,
   110               "AttachStdout":true,
   111               "AttachStderr":true,
   112               "PortSpecs":null,
   113               "Tty":false,
   114               "OpenStdin":false,
   115               "StdinOnce":false,
   116               "Env":null,
   117               "Cmd":[
   118                       "date"
   119               ],
   120               "Dns":null,
   121               "Image":"base",
   122               "Volumes":{
   123                       "/tmp": {}
   124               },
   125               "VolumesFrom":"",
   126               "WorkingDir":"",
   127               "ExposedPorts":{
   128                       "22/tcp": {}
   129               }
   130          }
   131  
   132  **Example response**:
   133  
   134          HTTP/1.1 201 Created
   135          Content-Type: application/json
   136  
   137          {
   138               "Id":"e90e34656806"
   139               "Warnings":[]
   140          }
   141  
   142  Json Parameters:
   143  
   144  -   **config** – the container's configuration
   145  
   146  Status Codes:
   147  
   148  -   **201** – no error
   149  -   **404** – no such container
   150  -   **406** – impossible to attach (container not running)
   151  -   **500** – server error
   152  
   153  ### Inspect a container
   154  
   155  `GET /containers/(id)/json`
   156  
   157  Return low-level information on the container `id`
   158  
   159  
   160  **Example request**:
   161  
   162          GET /containers/4fa6e0f0c678/json HTTP/1.1
   163  
   164  **Example response**:
   165  
   166          HTTP/1.1 200 OK
   167          Content-Type: application/json
   168  
   169          {
   170                       "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
   171                       "Created": "2013-05-07T14:51:42.041847+02:00",
   172                       "Path": "date",
   173                       "Args": [],
   174                       "Config": {
   175                               "Hostname": "4fa6e0f0c678",
   176                               "User": "",
   177                               "Memory": 0,
   178                               "MemorySwap": 0,
   179                               "AttachStdin": false,
   180                               "AttachStdout": true,
   181                               "AttachStderr": true,
   182                               "PortSpecs": null,
   183                               "Tty": false,
   184                               "OpenStdin": false,
   185                               "StdinOnce": false,
   186                               "Env": null,
   187                               "Cmd": [
   188                                       "date"
   189                               ],
   190                               "Dns": null,
   191                               "Image": "base",
   192                               "Volumes": {},
   193                               "VolumesFrom": "",
   194                               "WorkingDir": ""
   195                       },
   196                       "State": {
   197                               "Running": false,
   198                               "Pid": 0,
   199                               "ExitCode": 0,
   200                               "StartedAt": "2013-05-07T14:51:42.087658+02:01360",
   201                               "Ghost": false
   202                       },
   203                       "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
   204                       "NetworkSettings": {
   205                               "IpAddress": "",
   206                               "IpPrefixLen": 0,
   207                               "Gateway": "",
   208                               "Bridge": "",
   209                               "PortMapping": null
   210                       },
   211                       "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker",
   212                       "ResolvConfPath": "/etc/resolv.conf",
   213                       "Volumes": {}
   214          }
   215  
   216  Status Codes:
   217  
   218  -   **200** – no error
   219  -   **404** – no such container
   220  -   **500** – server error
   221  
   222  ### List processes running inside a container
   223  
   224  `GET /containers/(id)/top`
   225  
   226  List processes running inside the container `id`
   227  
   228  **Example request**:
   229  
   230          GET /containers/4fa6e0f0c678/top HTTP/1.1
   231  
   232  **Example response**:
   233  
   234          HTTP/1.1 200 OK
   235          Content-Type: application/json
   236  
   237          {
   238               "Titles": [
   239                       "USER",
   240                       "PID",
   241                       "%CPU",
   242                       "%MEM",
   243                       "VSZ",
   244                       "RSS",
   245                       "TTY",
   246                       "STAT",
   247                       "START",
   248                       "TIME",
   249                       "COMMAND"
   250                       ],
   251               "Processes": [
   252                       ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
   253                       ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
   254               ]
   255          }
   256  
   257  Query Parameters:
   258  
   259  -   **ps_args** – ps arguments to use (e.g., aux)
   260  
   261  Status Codes:
   262  
   263  -   **200** – no error
   264  -   **404** – no such container
   265  -   **500** – server error
   266  
   267  ### Inspect changes on a container's filesystem
   268  
   269  `GET /containers/(id)/changes`
   270  
   271  Inspect changes on container `id`'s filesystem
   272  
   273  **Example request**:
   274  
   275          GET /containers/4fa6e0f0c678/changes HTTP/1.1
   276  
   277  **Example response**:
   278  
   279          HTTP/1.1 200 OK
   280          Content-Type: application/json
   281  
   282          [
   283               {
   284                       "Path": "/dev",
   285                       "Kind": 0
   286               },
   287               {
   288                       "Path": "/dev/kmsg",
   289                       "Kind": 1
   290               },
   291               {
   292                       "Path": "/test",
   293                       "Kind": 1
   294               }
   295          ]
   296  
   297  Status Codes:
   298  
   299  -   **200** – no error
   300  -   **404** – no such container
   301  -   **500** – server error
   302  
   303  ### Export a container
   304  
   305  `GET /containers/(id)/export`
   306  
   307  Export the contents of container `id`
   308  
   309  **Example request**:
   310  
   311          GET /containers/4fa6e0f0c678/export HTTP/1.1
   312  
   313  **Example response**:
   314  
   315          HTTP/1.1 200 OK
   316          Content-Type: application/octet-stream
   317  
   318          {{ TAR STREAM }}
   319  
   320  Status Codes:
   321  
   322  -   **200** – no error
   323  -   **404** – no such container
   324  -   **500** – server error
   325  
   326  ### Start a container
   327  
   328  `POST /containers/(id)/start`
   329  
   330  Start the container `id`
   331  
   332  **Example request**:
   333  
   334          POST /containers/(id)/start HTTP/1.1
   335          Content-Type: application/json
   336  
   337          {
   338               "Binds":["/tmp:/tmp"],
   339               "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}],
   340               "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] },
   341               "Privileged":false,
   342               "PublishAllPorts":false
   343          }
   344  
   345      Binds need to reference Volumes that were defined during container
   346      creation.
   347  
   348  **Example response**:
   349  
   350          HTTP/1.1 204 No Content
   351          Content-Type: text/plain
   352  
   353  Json Parameters:
   354  
   355  -   **hostConfig** – the container's host configuration (optional)
   356  
   357  Status Codes:
   358  
   359  -   **204** – no error
   360  -   **404** – no such container
   361  -   **500** – server error
   362  
   363  ### Stop a container
   364  
   365  `POST /containers/(id)/stop`
   366  
   367  Stop the container `id`
   368  
   369  **Example request**:
   370  
   371          POST /containers/e90e34656806/stop?t=5 HTTP/1.1
   372  
   373  **Example response**:
   374  
   375          HTTP/1.1 204 OK
   376  
   377  Query Parameters:
   378  
   379  -   **t** – number of seconds to wait before killing the container
   380  
   381  Status Codes:
   382  
   383  -   **204** – no error
   384  -   **404** – no such container
   385  -   **500** – server error
   386  
   387  ### Restart a container
   388  
   389  `POST /containers/(id)/restart`
   390  
   391  Restart the container `id`
   392  
   393  **Example request**:
   394  
   395          POST /containers/e90e34656806/restart?t=5 HTTP/1.1
   396  
   397  **Example response**:
   398  
   399          HTTP/1.1 204 No Content
   400  
   401  Query Parameters:
   402  
   403  -   **t** – number of seconds to wait before killing the container
   404  
   405  Status Codes:
   406  
   407  -   **204** – no error
   408  -   **404** – no such container
   409  -   **500** – server error
   410  
   411  ### Kill a container
   412  
   413  `POST /containers/(id)/kill`
   414  
   415  Kill the container `id`
   416  
   417  **Example request**:
   418  
   419          POST /containers/e90e34656806/kill HTTP/1.1
   420  
   421  **Example response**:
   422  
   423          HTTP/1.1 204 No Content
   424  
   425  Status Codes:
   426  
   427  -   **204** – no error
   428  -   **404** – no such container
   429  -   **500** – server error
   430  
   431  ### Attach to a container
   432  
   433  `POST /containers/(id)/attach`
   434  
   435  Attach to the container `id`
   436  
   437  **Example request**:
   438  
   439          POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
   440  
   441  **Example response**:
   442  
   443          HTTP/1.1 200 OK
   444          Content-Type: application/vnd.docker.raw-stream
   445  
   446          {{ STREAM }}
   447  
   448  Query Parameters:
   449  
   450  -   **logs** – 1/True/true or 0/False/false, return logs. Defaul
   451          false
   452  -   **stream** – 1/True/true or 0/False/false, return stream.
   453          Default false
   454  -   **stdin** – 1/True/true or 0/False/false, if stream=true, attach
   455          to stdin. Default false
   456  -   **stdout** – 1/True/true or 0/False/false, if logs=true, return
   457          stdout log, if stream=true, attach to stdout. Default false
   458  -   **stderr** – 1/True/true or 0/False/false, if logs=true, return
   459          stderr log, if stream=true, attach to stderr. Default false
   460  
   461  Status Codes:
   462  
   463  -   **200** – no error
   464  -   **400** – bad parameter
   465  -   **404** – no such container
   466  -   **500** – server error
   467  
   468      **Stream details**:
   469  
   470      When using the TTY setting is enabled in
   471      [`POST /containers/create`
   472      ](/reference/api/docker_remote_api_v1.7/#create-a-container),
   473      the stream is the raw data from the process PTY and client's stdin.
   474      When the TTY is disabled, then the stream is multiplexed to separate
   475      stdout and stderr.
   476  
   477      The format is a **Header** and a **Payload** (frame).
   478  
   479      **HEADER**
   480  
   481      The header will contain the information on which stream write the
   482      stream (stdout or stderr). It also contain the size of the
   483      associated frame encoded on the last 4 bytes (uint32).
   484  
   485      It is encoded on the first 8 bytes like this:
   486  
   487          header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
   488  
   489      `STREAM_TYPE` can be:
   490  
   491  -   0: stdin (will be written on stdout)
   492  -   1: stdout
   493  -   2: stderr
   494  
   495      `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of
   496      the uint32 size encoded as big endian.
   497  
   498      **PAYLOAD**
   499  
   500      The payload is the raw stream.
   501  
   502      **IMPLEMENTATION**
   503  
   504      The simplest way to implement the Attach protocol is the following:
   505  
   506      1.  Read 8 bytes
   507      2.  chose stdout or stderr depending on the first byte
   508      3.  Extract the frame size from the last 4 byets
   509      4.  Read the extracted size and output it on the correct output
   510      5.  Goto 1)
   511  
   512  ### Wait a container
   513  
   514  `POST /containers/(id)/wait`
   515  
   516  Block until container `id` stops, then returns the exit code
   517  
   518  **Example request**:
   519  
   520          POST /containers/16253994b7c4/wait HTTP/1.1
   521  
   522  **Example response**:
   523  
   524          HTTP/1.1 200 OK
   525          Content-Type: application/json
   526  
   527          {"StatusCode": 0}
   528  
   529  Status Codes:
   530  
   531  -   **200** – no error
   532  -   **404** – no such container
   533  -   **500** – server error
   534  
   535  ### Remove a container
   536  
   537  `DELETE /containers/(id)`
   538  
   539  Remove the container `id` from the filesystem
   540  
   541  **Example request**:
   542  
   543          DELETE /containers/16253994b7c4?v=1 HTTP/1.1
   544  
   545  **Example response**:
   546  
   547          HTTP/1.1 204 No Content
   548  
   549  Query Parameters:
   550  
   551  -   **v** – 1/True/true or 0/False/false, Remove the volumes
   552          associated to the container. Default false
   553  
   554  Status Codes:
   555  
   556  -   **204** – no error
   557  -   **400** – bad parameter
   558  -   **404** – no such container
   559  -   **500** – server error
   560  
   561  ### Copy files or folders from a container
   562  
   563  `POST /containers/(id)/copy`
   564  
   565  Copy files or folders of container `id`
   566  
   567  **Example request**:
   568  
   569          POST /containers/4fa6e0f0c678/copy HTTP/1.1
   570          Content-Type: application/json
   571  
   572          {
   573               "Resource": "test.txt"
   574          }
   575  
   576  **Example response**:
   577  
   578          HTTP/1.1 200 OK
   579          Content-Type: application/octet-stream
   580  
   581          {{ TAR STREAM }}
   582  
   583  Status Codes:
   584  
   585  -   **200** – no error
   586  -   **404** – no such container
   587  -   **500** – server error
   588  
   589  ## 2.2 Images
   590  
   591  ### List Images
   592  
   593  `GET /images/json`
   594  
   595  **Example request**:
   596  
   597          GET /images/json?all=0 HTTP/1.1
   598  
   599  **Example response**:
   600  
   601          HTTP/1.1 200 OK
   602          Content-Type: application/json
   603  
   604          [
   605            {
   606               "RepoTags": [
   607                 "ubuntu:12.04",
   608                 "ubuntu:precise",
   609                 "ubuntu:latest"
   610               ],
   611               "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
   612               "Created": 1365714795,
   613               "Size": 131506275,
   614               "VirtualSize": 131506275
   615            },
   616            {
   617               "RepoTags": [
   618                 "ubuntu:12.10",
   619                 "ubuntu:quantal"
   620               ],
   621               "ParentId": "27cf784147099545",
   622               "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
   623               "Created": 1364102658,
   624               "Size": 24653,
   625               "VirtualSize": 180116135
   626            }
   627          ]
   628  
   629  ### Create an image
   630  
   631  `POST /images/create`
   632  
   633  Create an image, either by pull it from the registry or by importing i
   634  
   635  **Example request**:
   636  
   637          POST /images/create?fromImage=base HTTP/1.1
   638  
   639  **Example response**:
   640  
   641          HTTP/1.1 200 OK
   642          Content-Type: application/json
   643  
   644          {"status":"Pulling..."}
   645          {"status":"Pulling", "progress":"1/? (n/a)"}
   646          {"error":"Invalid..."}
   647          ...
   648  
   649      When using this endpoint to pull an image from the registry, the
   650      `X-Registry-Auth` header can be used to include
   651      a base64-encoded AuthConfig object.
   652  
   653  Query Parameters:
   654  
   655  -   **fromImage** – name of the image to pull
   656  -   **fromSrc** – source to import, - means stdin
   657  -   **repo** – repository
   658  -   **tag** – tag
   659  -   **registry** – the registry to pull from
   660  
   661  Request Headers:
   662  
   663  -   **X-Registry-Auth** – base64-encoded AuthConfig object
   664  
   665  Status Codes:
   666  
   667  -   **200** – no error
   668  -   **500** – server error
   669  
   670  ### Insert a file in an image
   671  
   672  `POST /images/(name)/insert`
   673  
   674  Insert a file from `url` in the image `name` at `path`
   675  
   676  **Example request**:
   677  
   678          POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
   679  
   680  **Example response**:
   681  
   682          HTTP/1.1 200 OK
   683          Content-Type: application/json
   684  
   685          {"status":"Inserting..."}
   686          {"status":"Inserting", "progress":"1/? (n/a)"}
   687          {"error":"Invalid..."}
   688          ...
   689  
   690  Query Parameters:
   691  
   692  -	**url** – The url from where the file is taken
   693  -	**path** – The path where the file is stored
   694  
   695  Status Codes:
   696  
   697  -   **200** – no error
   698  -   **500** – server error
   699  
   700  ### Inspect an image
   701  
   702  `GET /images/(name)/json`
   703  
   704  Return low-level information on the image `name`
   705  
   706  **Example request**:
   707  
   708          GET /images/base/json HTTP/1.1
   709  
   710  **Example response**:
   711  
   712          HTTP/1.1 200 OK
   713          Content-Type: application/json
   714  
   715          {
   716               "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
   717               "parent":"27cf784147099545",
   718               "created":"2013-03-23T22:24:18.818426-07:00",
   719               "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
   720               "container_config":
   721                       {
   722                               "Hostname":"",
   723                               "User":"",
   724                               "Memory":0,
   725                               "MemorySwap":0,
   726                               "AttachStdin":false,
   727                               "AttachStdout":false,
   728                               "AttachStderr":false,
   729                               "PortSpecs":null,
   730                               "Tty":true,
   731                               "OpenStdin":true,
   732                               "StdinOnce":false,
   733                               "Env":null,
   734                               "Cmd": ["/bin/bash"],
   735                               "Dns":null,
   736                               "Image":"base",
   737                               "Volumes":null,
   738                               "VolumesFrom":"",
   739                               "WorkingDir":""
   740                       },
   741               "Size": 6824592
   742          }
   743  
   744  Status Codes:
   745  
   746  -   **200** – no error
   747  -   **404** – no such image
   748  -   **500** – server error
   749  
   750  ### Get the history of an image
   751  
   752  `GET /images/(name)/history`
   753  
   754  Return the history of the image `name`
   755  
   756  **Example request**:
   757  
   758          GET /images/base/history HTTP/1.1
   759  
   760  **Example response**:
   761  
   762          HTTP/1.1 200 OK
   763          Content-Type: application/json
   764  
   765          [
   766               {
   767                       "Id": "b750fe79269d",
   768                       "Created": 1364102658,
   769                       "CreatedBy": "/bin/bash"
   770               },
   771               {
   772                       "Id": "27cf78414709",
   773                       "Created": 1364068391,
   774                       "CreatedBy": ""
   775               }
   776          ]
   777  
   778  Status Codes:
   779  
   780  -   **200** – no error
   781  -   **404** – no such image
   782  -   **500** – server error
   783  
   784  ### Push an image on the registry
   785  
   786  `POST /images/(name)/push`
   787  
   788  Push the image `name` on the registry
   789  
   790  **Example request**:
   791  
   792          POST /images/test/push HTTP/1.1
   793  
   794  **Example response**:
   795  
   796          HTTP/1.1 200 OK
   797          Content-Type: application/json
   798  
   799          {"status":"Pushing..."}
   800          {"status":"Pushing", "progress":"1/? (n/a)"}
   801          {"error":"Invalid..."}
   802          ...
   803  
   804      Request Headers:
   805  
   806       
   807  
   808  -   **X-Registry-Auth** – include a base64-encoded AuthConfig
   809          object.
   810  
   811  Status Codes:
   812  
   813  -   **200** – no error
   814  -   **404** – no such image
   815  -   **500** – server error
   816  
   817  ### Tag an image into a repository
   818  
   819  `POST /images/(name)/tag`
   820  
   821  Tag the image `name` into a repository
   822  
   823  **Example request**:
   824  
   825          POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1
   826  
   827  **Example response**:
   828  
   829          HTTP/1.1 201 OK
   830  
   831  Query Parameters:
   832  
   833  -   **repo** – The repository to tag in
   834  -   **force** – 1/True/true or 0/False/false, default false
   835  -   **tag** - The new tag name
   836  
   837  Status Codes:
   838  
   839  -   **201** – no error
   840  -   **400** – bad parameter
   841  -   **404** – no such image
   842  -   **409** – conflict
   843  -   **500** – server error
   844  
   845  ### Remove an image
   846  
   847  `DELETE /images/(name)`
   848  
   849  Remove the image `name` from the filesystem
   850  
   851  **Example request**:
   852  
   853          DELETE /images/test HTTP/1.1
   854  
   855  **Example response**:
   856  
   857          HTTP/1.1 200 OK
   858          Content-type: application/json
   859  
   860          [
   861           {"Untagged": "3e2f21a89f"},
   862           {"Deleted": "3e2f21a89f"},
   863           {"Deleted": "53b4f83ac9"}
   864          ]
   865  
   866  Status Codes:
   867  
   868  -   **200** – no error
   869  -   **404** – no such image
   870  -   **409** – conflict
   871  -   **500** – server error
   872  
   873  ### Search images
   874  
   875  `GET /images/search`
   876  
   877  Search for an image on [Docker Hub](https://hub.docker.com).
   878  
   879  > **Note**:
   880  > The response keys have changed from API v1.6 to reflect the JSON
   881  > sent by the registry server to the docker daemon's request.
   882  
   883  **Example request**:
   884  
   885          GET /images/search?term=sshd HTTP/1.1
   886  
   887  **Example response**:
   888  
   889          HTTP/1.1 200 OK
   890          Content-Type: application/json
   891  
   892          [
   893                  {
   894                      "description": "",
   895                      "is_official": false,
   896                      "is_trusted": false,
   897                      "name": "wma55/u1210sshd",
   898                      "star_count": 0
   899                  },
   900                  {
   901                      "description": "",
   902                      "is_official": false,
   903                      "is_trusted": false,
   904                      "name": "jdswinbank/sshd",
   905                      "star_count": 0
   906                  },
   907                  {
   908                      "description": "",
   909                      "is_official": false,
   910                      "is_trusted": false,
   911                      "name": "vgauthier/sshd",
   912                      "star_count": 0
   913                  }
   914          ...
   915          ]
   916  
   917  Query Parameters:
   918  
   919  -   **term** – term to search
   920  
   921  Status Codes:
   922  
   923  -   **200** – no error
   924  -   **500** – server error
   925  
   926  ## 2.3 Misc
   927  
   928  ### Build an image from Dockerfile via stdin
   929  
   930  `POST /build`
   931  
   932  Build an image from Dockerfile via stdin
   933  
   934  **Example request**:
   935  
   936          POST /build HTTP/1.1
   937  
   938          {{ TAR STREAM }}
   939  
   940  **Example response**:
   941  
   942          HTTP/1.1 200 OK
   943          Content-Type: application/json
   944  
   945          {{ STREAM }}
   946  
   947      The stream must be a tar archive compressed with one of the
   948      following algorithms: identity (no compression), gzip, bzip2, xz.
   949  
   950      The archive must include a file called `Dockerfile`
   951      at its root. It may include any number of other files,
   952      which will be accessible in the build context (See the [*ADD build
   953      command*](/builder/#dockerbuilder)).
   954  
   955  Query Parameters:
   956  
   957  -   **t** – repository name (and optionally a tag) to be applied to
   958      the resulting image in case of success
   959  -   **q** – suppress verbose build output
   960  -   **nocache** – do not use the cache when building the image
   961  
   962      Request Headers:
   963  
   964       
   965  
   966  -   **Content-type** – should be set to
   967          `"application/tar"`.
   968  
   969  Status Codes:
   970  
   971  -   **200** – no error
   972  -   **500** – server error
   973  
   974  ### Check auth configuration
   975  
   976  `POST /auth`
   977  
   978  Get the default username and email
   979  
   980  **Example request**:
   981  
   982          POST /auth HTTP/1.1
   983          Content-Type: application/json
   984  
   985          {
   986               "username":" hannibal",
   987               "password: "xxxx",
   988               "email": "hannibal@a-team.com",
   989               "serveraddress": "https://index.docker.io/v1/"
   990          }
   991  
   992  **Example response**:
   993  
   994          HTTP/1.1 200 OK
   995          Content-Type: text/plain
   996  
   997  Status Codes:
   998  
   999  -   **200** – no error
  1000  -   **204** – no error
  1001  -   **500** – server error
  1002  
  1003  ### Display system-wide information
  1004  
  1005  `GET /info`
  1006  
  1007  Display system-wide information
  1008  
  1009  **Example request**:
  1010  
  1011          GET /info HTTP/1.1
  1012  
  1013  **Example response**:
  1014  
  1015          HTTP/1.1 200 OK
  1016          Content-Type: application/json
  1017  
  1018          {
  1019               "Containers":11,
  1020               "Images":16,
  1021               "Debug":false,
  1022               "NFd": 11,
  1023               "NGoroutines":21,
  1024               "MemoryLimit":true,
  1025               "SwapLimit":false,
  1026               "IPv4Forwarding":true
  1027          }
  1028  
  1029  Status Codes:
  1030  
  1031  -   **200** – no error
  1032  -   **500** – server error
  1033  
  1034  ### Show the docker version information
  1035  
  1036  `GET /version`
  1037  
  1038  Show the docker version information
  1039  
  1040  **Example request**:
  1041  
  1042          GET /version HTTP/1.1
  1043  
  1044  **Example response**:
  1045  
  1046          HTTP/1.1 200 OK
  1047          Content-Type: application/json
  1048  
  1049          {
  1050               "Version":"0.2.2",
  1051               "GitCommit":"5a2a5cc+CHANGES",
  1052               "GoVersion":"go1.0.3"
  1053          }
  1054  
  1055  Status Codes:
  1056  
  1057  -   **200** – no error
  1058  -   **500** – server error
  1059  
  1060  ### Create a new image from a container's changes
  1061  
  1062  `POST /commit`
  1063  
  1064  Create a new image from a container's changes
  1065  
  1066  **Example request**:
  1067  
  1068          POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
  1069  
  1070  **Example response**:
  1071  
  1072          HTTP/1.1 201 OK
  1073              Content-Type: application/vnd.docker.raw-stream
  1074  
  1075          {"Id": "596069db4bf5"}
  1076  
  1077  Query Parameters:
  1078  
  1079  -   **container** – source container
  1080  -   **repo** – repository
  1081  -   **tag** – tag
  1082  -   **m** – commit message
  1083  -   **author** – author (e.g., "John Hannibal Smith
  1084          <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
  1085  -   **run** – config automatically applied when the image is run.
  1086          (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
  1087  
  1088  Status Codes:
  1089  
  1090  -   **201** – no error
  1091  -   **404** – no such container
  1092  -   **500** – server error
  1093  
  1094  ### Monitor Docker's events
  1095  
  1096  `GET /events`
  1097  
  1098  Get events from docker, either in real time via streaming, or via
  1099  polling (using since).
  1100  
  1101  Docker containers will report the following events:
  1102  
  1103      create, destroy, die, export, kill, pause, restart, start, stop, unpause
  1104  
  1105  and Docker images will report:
  1106  
  1107      untag, delete
  1108  
  1109  **Example request**:
  1110  
  1111          GET /events?since=1374067924
  1112  
  1113  **Example response**:
  1114  
  1115          HTTP/1.1 200 OK
  1116          Content-Type: application/json
  1117  
  1118          {"status": "create", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924}
  1119          {"status": "start", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924}
  1120          {"status": "stop", "id": "dfdf82bd3881","from": "base:latest", "time":1374067966}
  1121          {"status": "destroy", "id": "dfdf82bd3881","from": "base:latest", "time":1374067970}
  1122  
  1123  Query Parameters:
  1124  
  1125  -   **since** – timestamp used for polling
  1126  
  1127  Status Codes:
  1128  
  1129  -   **200** – no error
  1130  -   **500** – server error
  1131  
  1132  ### Get a tarball containing all images and tags in a repository
  1133  
  1134  `GET /images/(name)/get`
  1135  
  1136  Get a tarball containing all images and metadata for the repository
  1137  specified by `name`.
  1138  
  1139  **Example request**
  1140  
  1141                 GET /images/ubuntu/get
  1142  
  1143  **Example response**:
  1144  
  1145             .. sourcecode:: http
  1146  
  1147                HTTP/1.1 200 OK
  1148          Content-Type: application/x-tar
  1149  
  1150          Binary data stream
  1151              :statuscode 200: no error
  1152              :statuscode 500: server error
  1153  
  1154  ### Load a tarball with a set of images and tags into docker
  1155  
  1156  `POST /images/load`
  1157  
  1158  Load a set of images and tags into the docker repository.
  1159  
  1160  **Example request**
  1161  
  1162              POST /images/load
  1163  
  1164            Tarball in body
  1165  
  1166          **Example response**:
  1167  
  1168          .. sourcecode:: http
  1169  
  1170             HTTP/1.1 200 OK
  1171  
  1172           :statuscode 200: no error
  1173           :statuscode 500: server error
  1174  
  1175  # 3. Going further
  1176  
  1177  ## 3.1 Inside `docker run`
  1178  
  1179  Here are the steps of `docker run` :
  1180  
  1181  -   Create the container
  1182  
  1183  -   If the status code is 404, it means the image doesn't exist:
  1184          -   Try to pull it
  1185          -   Then retry to create the container
  1186  
  1187  -   Start the container
  1188  
  1189  -   If you are not in detached mode:
  1190          -   Attach to the container, using logs=1 (to have stdout and
  1191              stderr from the container's start) and stream=1
  1192  
  1193  -   If in detached mode or only stdin is attached:
  1194          -   Display the container's id
  1195  
  1196  ## 3.2 Hijacking
  1197  
  1198  In this version of the API, /attach, uses hijacking to transport stdin,
  1199  stdout and stderr on the same socket. This might change in the future.
  1200  
  1201  ## 3.3 CORS Requests
  1202  
  1203  To enable cross origin requests to the remote api add the flag
  1204  "--api-enable-cors" when running docker in daemon mode.
  1205  
  1206      $ docker -d -H="192.168.1.9:2375" --api-enable-cors