github.com/daaku/docker@v1.5.0/docs/sources/reference/api/docker-io_api.md (about)

     1  page_title: Docker Hub API
     2  page_description: API Documentation for the Docker Hub API
     3  page_keywords: API, Docker, index, REST, documentation, Docker Hub, registry
     4  
     5  # Docker Hub API
     6  
     7  - This is the REST API for [Docker Hub](https://hub.docker.com).
     8  - Authorization is done with basic auth over SSL
     9  - Not all commands require authentication, only those noted as such.
    10  
    11  # Repositories
    12  
    13  ## User Repository
    14  
    15  ### Create a user repository
    16  
    17  `PUT /v1/repositories/(namespace)/(repo_name)/`
    18  
    19  Create a user repository with the given `namespace` and `repo_name`.
    20  
    21  **Example Request**:
    22  
    23          PUT /v1/repositories/foo/bar/ HTTP/1.1
    24          Host: index.docker.io
    25          Accept: application/json
    26          Content-Type: application/json
    27          Authorization: Basic akmklmasadalkm==
    28          X-Docker-Token: true
    29  
    30          [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]
    31  
    32  Parameters:
    33  
    34  - **namespace** – the namespace for the repo
    35  - **repo_name** – the name for the repo
    36  
    37  **Example Response**:
    38  
    39          HTTP/1.1 200
    40          Vary: Accept
    41          Content-Type: application/json
    42          WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=write
    43          X-Docker-Token: signature=123abc,repository="foo/bar",access=write
    44          X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
    45  
    46          ""
    47  
    48  Status Codes:
    49  
    50  - **200** – Created
    51  - **400** – Errors (invalid json, missing or invalid fields, etc)
    52  - **401** – Unauthorized
    53  - **403** – Account is not Active
    54  
    55  ### Delete a user repository
    56  
    57  `DELETE /v1/repositories/(namespace)/(repo_name)/`
    58  
    59  Delete a user repository with the given `namespace` and `repo_name`.
    60  
    61  **Example Request**:
    62  
    63          DELETE /v1/repositories/foo/bar/ HTTP/1.1
    64          Host: index.docker.io
    65          Accept: application/json
    66          Content-Type: application/json
    67          Authorization: Basic akmklmasadalkm==
    68          X-Docker-Token: true
    69  
    70          ""
    71  
    72  Parameters:
    73  
    74  - **namespace** – the namespace for the repo
    75  - **repo_name** – the name for the repo
    76  
    77  **Example Response**:
    78  
    79          HTTP/1.1 202
    80          Vary: Accept
    81          Content-Type: application/json
    82          WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=delete
    83          X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
    84          X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
    85  
    86          ""
    87  
    88  Status Codes:
    89  
    90  - **200** – Deleted
    91  - **202** – Accepted
    92  - **400** – Errors (invalid json, missing or invalid fields, etc)
    93  - **401** – Unauthorized
    94  - **403** – Account is not Active
    95  
    96  ## Library Repository
    97  
    98  ### Create a library repository
    99  
   100  `PUT /v1/repositories/(repo_name)/`
   101  
   102  Create a library repository with the given `repo_name`.
   103  This is a restricted feature only available to docker admins.
   104  
   105  > When namespace is missing, it is assumed to be `library`
   106  
   107  
   108  **Example Request**:
   109  
   110          PUT /v1/repositories/foobar/ HTTP/1.1
   111          Host: index.docker.io
   112          Accept: application/json
   113          Content-Type: application/json
   114          Authorization: Basic akmklmasadalkm==
   115          X-Docker-Token: true
   116  
   117          [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]
   118  
   119  Parameters:
   120  
   121  - **repo_name** – the library name for the repo
   122  
   123  **Example Response**:
   124  
   125          HTTP/1.1 200
   126          Vary: Accept
   127          Content-Type: application/json
   128          WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=write
   129          X-Docker-Token: signature=123abc,repository="foo/bar",access=write
   130          X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
   131  
   132          ""
   133  
   134  Status Codes:
   135  
   136  - **200** – Created
   137  - **400** – Errors (invalid json, missing or invalid fields, etc)
   138  - **401** – Unauthorized
   139  - **403** – Account is not Active
   140  
   141  ### Delete a library repository
   142  
   143  `DELETE /v1/repositories/(repo_name)/`
   144  
   145  Delete a library repository with the given `repo_name`.
   146  This is a restricted feature only available to docker admins.
   147  
   148  > When namespace is missing, it is assumed to be `library`
   149  
   150  
   151  **Example Request**:
   152  
   153          DELETE /v1/repositories/foobar/ HTTP/1.1
   154          Host: index.docker.io
   155          Accept: application/json
   156          Content-Type: application/json
   157          Authorization: Basic akmklmasadalkm==
   158          X-Docker-Token: true
   159  
   160          ""
   161  
   162  Parameters:
   163  
   164  - **repo_name** – the library name for the repo
   165  
   166  **Example Response**:
   167  
   168          HTTP/1.1 202
   169          Vary: Accept
   170          Content-Type: application/json
   171          WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=delete
   172          X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
   173          X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]
   174  
   175          ""
   176  
   177  Status Codes:
   178  
   179  - **200** – Deleted
   180  - **202** – Accepted
   181  - **400** – Errors (invalid json, missing or invalid fields, etc)
   182  - **401** – Unauthorized
   183  - **403** – Account is not Active
   184  
   185  # Repository Images
   186  
   187  ## User Repository Images
   188  
   189  ### Update user repository images
   190  
   191  `PUT /v1/repositories/(namespace)/(repo_name)/images`
   192  
   193  Update the images for a user repo.
   194  
   195  **Example Request**:
   196  
   197          PUT /v1/repositories/foo/bar/images HTTP/1.1
   198          Host: index.docker.io
   199          Accept: application/json
   200          Content-Type: application/json
   201          Authorization: Basic akmklmasadalkm==
   202  
   203          [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
   204          "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]
   205  
   206  Parameters:
   207  
   208  - **namespace** – the namespace for the repo
   209  - **repo_name** – the name for the repo
   210  
   211  **Example Response**:
   212  
   213          HTTP/1.1 204
   214          Vary: Accept
   215          Content-Type: application/json
   216  
   217          ""
   218  
   219  Status Codes:
   220  
   221  - **204** – Created
   222  - **400** – Errors (invalid json, missing or invalid fields, etc)
   223  - **401** – Unauthorized
   224  - **403** – Account is not Active or permission denied
   225  
   226  ### List user repository images
   227  
   228  `GET /v1/repositories/(namespace)/(repo_name)/images`
   229  
   230  Get the images for a user repo.
   231  
   232  **Example Request**:
   233  
   234          GET /v1/repositories/foo/bar/images HTTP/1.1
   235          Host: index.docker.io
   236          Accept: application/json
   237  
   238  Parameters:
   239  
   240  - **namespace** – the namespace for the repo
   241  - **repo_name** – the name for the repo
   242  
   243  **Example Response**:
   244  
   245          HTTP/1.1 200
   246          Vary: Accept
   247          Content-Type: application/json
   248  
   249          [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
   250          "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
   251          {"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
   252          "checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]
   253  
   254  Status Codes:
   255  
   256  - **200** – OK
   257  - **404** – Not found
   258  
   259  ## Library Repository Images
   260  
   261  ### Update library repository images
   262  
   263  `PUT /v1/repositories/(repo_name)/images`
   264  
   265  Update the images for a library repo.
   266  
   267  **Example Request**:
   268  
   269          PUT /v1/repositories/foobar/images HTTP/1.1
   270          Host: index.docker.io
   271          Accept: application/json
   272          Content-Type: application/json
   273          Authorization: Basic akmklmasadalkm==
   274  
   275          [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
   276          "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]
   277  
   278  Parameters:
   279  
   280  - **repo_name** – the library name for the repo
   281  
   282  **Example Response**:
   283  
   284          HTTP/1.1 204
   285          Vary: Accept
   286          Content-Type: application/json
   287  
   288          ""
   289  
   290  Status Codes:
   291  
   292  - **204** – Created
   293  - **400** – Errors (invalid json, missing or invalid fields, etc)
   294  - **401** – Unauthorized
   295  - **403** – Account is not Active or permission denied
   296  
   297  ### List library repository images
   298  
   299  `GET /v1/repositories/(repo_name)/images`
   300  
   301  Get the images for a library repo.
   302  
   303  **Example Request**:
   304  
   305          GET /v1/repositories/foobar/images HTTP/1.1
   306          Host: index.docker.io
   307          Accept: application/json
   308  
   309  Parameters:
   310  
   311  - **repo_name** – the library name for the repo
   312  
   313  **Example Response**:
   314  
   315          HTTP/1.1 200
   316          Vary: Accept
   317          Content-Type: application/json
   318  
   319          [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
   320          "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
   321          {"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
   322          "checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]
   323  
   324  Status Codes:
   325  
   326  - **200** – OK
   327  - **404** – Not found
   328  
   329  # Repository Authorization
   330  
   331  ## Library Repository
   332  
   333  ### Authorize a token for a library
   334  
   335  `PUT /v1/repositories/(repo_name)/auth`
   336  
   337  Authorize a token for a library repo
   338  
   339  **Example Request**:
   340  
   341          PUT /v1/repositories/foobar/auth HTTP/1.1
   342          Host: index.docker.io
   343          Accept: application/json
   344          Authorization: Token signature=123abc,repository="library/foobar",access=write
   345  
   346  Parameters:
   347  
   348  - **repo_name** – the library name for the repo
   349  
   350  **Example Response**:
   351  
   352          HTTP/1.1 200
   353          Vary: Accept
   354          Content-Type: application/json
   355  
   356          "OK"
   357  
   358  Status Codes:
   359  
   360  - **200** – OK
   361  - **403** – Permission denied
   362  - **404** – Not found
   363  
   364  ## User Repository
   365  
   366  ### Authorize a token for a user repository
   367  
   368  `PUT /v1/repositories/(namespace)/(repo_name)/auth`
   369  
   370  Authorize a token for a user repo
   371  
   372  **Example Request**:
   373  
   374          PUT /v1/repositories/foo/bar/auth HTTP/1.1
   375          Host: index.docker.io
   376          Accept: application/json
   377          Authorization: Token signature=123abc,repository="foo/bar",access=write
   378  
   379  Parameters:
   380  
   381  - **namespace** – the namespace for the repo
   382  - **repo_name** – the name for the repo
   383  
   384  **Example Response**:
   385  
   386          HTTP/1.1 200
   387          Vary: Accept
   388          Content-Type: application/json
   389  
   390          "OK"
   391  
   392  Status Codes:
   393  
   394  - **200** – OK
   395  - **403** – Permission denied
   396  - **404** – Not found
   397  
   398  ## Users
   399  
   400  ### User Login
   401  
   402  `GET /v1/users/`
   403  
   404  If you want to check your login, you can try this endpoint
   405  
   406  **Example Request**:
   407  
   408          GET /v1/users/ HTTP/1.1
   409          Host: index.docker.io
   410          Accept: application/json
   411          Authorization: Basic akmklmasadalkm==
   412  
   413  **Example Response**:
   414  
   415          HTTP/1.1 200 OK
   416          Vary: Accept
   417          Content-Type: application/json
   418  
   419          OK
   420  
   421  Status Codes:
   422  
   423  - **200** – no error
   424  - **401** – Unauthorized
   425  - **403** – Account is not Active
   426  
   427  ### User Register
   428  
   429  `POST /v1/users/`
   430  
   431  Registering a new account.
   432  
   433  **Example request**:
   434  
   435          POST /v1/users/ HTTP/1.1
   436          Host: index.docker.io
   437          Accept: application/json
   438          Content-Type: application/json
   439  
   440          {"email": "sam@docker.com",
   441           "password": "toto42",
   442           "username": "foobar"}
   443  
   444  Json Parameters:
   445  
   446  - **email** – valid email address, that needs to be confirmed
   447  - **username** – min 4 character, max 30 characters, must match
   448          the regular expression [a-z0-9_].
   449  - **password** – min 5 characters
   450  
   451  **Example Response**:
   452  
   453          HTTP/1.1 201 OK
   454          Vary: Accept
   455          Content-Type: application/json
   456  
   457          "User Created"
   458  
   459  Status Codes:
   460  
   461  - **201** – User Created
   462  - **400** – Errors (invalid json, missing or invalid fields, etc)
   463  
   464  ### Update User
   465  
   466  `PUT /v1/users/(username)/`
   467  
   468  Change a password or email address for given user. If you pass in an
   469  email, it will add it to your account, it will not remove the old
   470  one. Passwords will be updated.
   471  
   472  It is up to the client to verify that that password that is sent is
   473  the one that they want. Common approach is to have them type it
   474  twice.
   475  
   476  **Example Request**:
   477  
   478          PUT /v1/users/fakeuser/ HTTP/1.1
   479          Host: index.docker.io
   480          Accept: application/json
   481          Content-Type: application/json
   482          Authorization: Basic akmklmasadalkm==
   483  
   484          {"email": "sam@docker.com",
   485           "password": "toto42"}
   486  
   487  Parameters:
   488  
   489  - **username** – username for the person you want to update
   490  
   491  **Example Response**:
   492  
   493          HTTP/1.1 204
   494          Vary: Accept
   495          Content-Type: application/json
   496  
   497          ""
   498  
   499  Status Codes:
   500  
   501  - **204** – User Updated
   502  - **400** – Errors (invalid json, missing or invalid fields, etc)
   503  - **401** – Unauthorized
   504  - **403** – Account is not Active
   505  - **404** – User not found