page_title: Docker Hub API page_description: API Documentation for the Docker Hub API page_keywords: API, Docker, index, REST, documentation, Docker Hub, registry

Docker Hub API

This is the REST API for Docker Hub.
Authorization is done with basic auth over SSL
Not all commands require authentication, only those noted as such.

Repositories

User Repository

Create a user repository

PUT /v1/repositories/(namespace)/(repo_name)/

Create a user repository with the given namespace and repo_name.

Example Request:

    PUT /v1/repositories/foo/bar/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==
    X-Docker-Token: true

    [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]

Parameters:

namespace – the namespace for the repo
repo_name – the name for the repo

Example Response:

    HTTP/1.1 200
    Vary: Accept
    Content-Type: application/json
    WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=write
    X-Docker-Token: signature=123abc,repository="foo/bar",access=write
    X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

    ""

Status Codes:

200 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active

Delete a user repository

DELETE /v1/repositories/(namespace)/(repo_name)/

Delete a user repository with the given namespace and repo_name.

Example Request:

    DELETE /v1/repositories/foo/bar/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==
    X-Docker-Token: true

    ""

Parameters:

namespace – the namespace for the repo
repo_name – the name for the repo

Example Response:

    HTTP/1.1 202
    Vary: Accept
    Content-Type: application/json
    WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=delete
    X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
    X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

    ""

Status Codes:

200 – Deleted
202 – Accepted
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active

Library Repository

Create a library repository

PUT /v1/repositories/(repo_name)/

Create a library repository with the given repo_name. This is a restricted feature only available to docker admins.

When namespace is missing, it is assumed to be library

Example Request:

    PUT /v1/repositories/foobar/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==
    X-Docker-Token: true

    [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]

Parameters:

repo_name – the library name for the repo

Example Response:

    HTTP/1.1 200
    Vary: Accept
    Content-Type: application/json
    WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=write
    X-Docker-Token: signature=123abc,repository="foo/bar",access=write
    X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

    ""

Status Codes:

200 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active

Delete a library repository

DELETE /v1/repositories/(repo_name)/

Delete a library repository with the given repo_name. This is a restricted feature only available to docker admins.

When namespace is missing, it is assumed to be library

Example Request:

    DELETE /v1/repositories/foobar/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==
    X-Docker-Token: true

    ""

Parameters:

repo_name – the library name for the repo

Example Response:

    HTTP/1.1 202
    Vary: Accept
    Content-Type: application/json
    WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=delete
    X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
    X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

    ""

Status Codes:

200 – Deleted
202 – Accepted
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active

Repository Images

User Repository Images

Update user repository images

PUT /v1/repositories/(namespace)/(repo_name)/images

Update the images for a user repo.

Example Request:

    PUT /v1/repositories/foo/bar/images HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==

    [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
    "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]

Parameters:

namespace – the namespace for the repo
repo_name – the name for the repo

Example Response:

    HTTP/1.1 204
    Vary: Accept
    Content-Type: application/json

    ""

Status Codes:

204 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active or permission denied

List user repository images

GET /v1/repositories/(namespace)/(repo_name)/images

Get the images for a user repo.

Example Request:

    GET /v1/repositories/foo/bar/images HTTP/1.1
    Host: index.docker.io
    Accept: application/json

Parameters:

namespace – the namespace for the repo
repo_name – the name for the repo

Example Response:

    HTTP/1.1 200
    Vary: Accept
    Content-Type: application/json

    [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
    "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
    {"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
    "checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]

Status Codes:

200 – OK
404 – Not found

Library Repository Images

Update library repository images

PUT /v1/repositories/(repo_name)/images

Update the images for a library repo.

Example Request:

    PUT /v1/repositories/foobar/images HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==

    [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
    "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]

Parameters:

repo_name – the library name for the repo

Example Response:

    HTTP/1.1 204
    Vary: Accept
    Content-Type: application/json

    ""

Status Codes:

204 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active or permission denied

List library repository images

GET /v1/repositories/(repo_name)/images

Get the images for a library repo.

Example Request:

    GET /v1/repositories/foobar/images HTTP/1.1
    Host: index.docker.io
    Accept: application/json

Parameters:

repo_name – the library name for the repo

Example Response:

    HTTP/1.1 200
    Vary: Accept
    Content-Type: application/json

    [{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
    "checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
    {"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
    "checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]

Status Codes:

200 – OK
404 – Not found

Repository Authorization

Library Repository

Authorize a token for a library

PUT /v1/repositories/(repo_name)/auth

Authorize a token for a library repo

Example Request:

    PUT /v1/repositories/foobar/auth HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Authorization: Token signature=123abc,repository="library/foobar",access=write

Parameters:

repo_name – the library name for the repo

Example Response:

    HTTP/1.1 200
    Vary: Accept
    Content-Type: application/json

    "OK"

Status Codes:

200 – OK
403 – Permission denied
404 – Not found

User Repository

Authorize a token for a user repository

PUT /v1/repositories/(namespace)/(repo_name)/auth

Authorize a token for a user repo

Example Request:

    PUT /v1/repositories/foo/bar/auth HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Authorization: Token signature=123abc,repository="foo/bar",access=write

Parameters:

namespace – the namespace for the repo
repo_name – the name for the repo

Example Response:

    HTTP/1.1 200
    Vary: Accept
    Content-Type: application/json

    "OK"

Status Codes:

200 – OK
403 – Permission denied
404 – Not found

Users

User Login

GET /v1/users/

If you want to check your login, you can try this endpoint

Example Request:

    GET /v1/users/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Authorization: Basic akmklmasadalkm==

Example Response:

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

    OK

Status Codes:

200 – no error
401 – Unauthorized
403 – Account is not Active

User Register

POST /v1/users/

Registering a new account.

Example request:

    POST /v1/users/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json

    {"email": "sam@docker.com",
     "password": "toto42",
     "username": "foobar"}

Json Parameters:

email – valid email address, that needs to be confirmed
username – min 4 character, max 30 characters, must match the regular expression [a-z0-9_].
password – min 5 characters

Example Response:

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

    "User Created"

Status Codes:

201 – User Created
400 – Errors (invalid json, missing or invalid fields, etc)

Update User

PUT /v1/users/(username)/

Change a password or email address for given user. If you pass in an email, it will add it to your account, it will not remove the old one. Passwords will be updated.

It is up to the client to verify that that password that is sent is the one that they want. Common approach is to have them type it twice.

Example Request:

    PUT /v1/users/fakeuser/ HTTP/1.1
    Host: index.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Basic akmklmasadalkm==

    {"email": "sam@docker.com",
     "password": "toto42"}

Parameters:

username – username for the person you want to update

Example Response:

    HTTP/1.1 204
    Vary: Accept
    Content-Type: application/json

    ""

Status Codes:

204 – User Updated
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Account is not Active
404 – User not found

docker-io_api.md 12 KB History Raw

Docker Hub API

Repositories

User Repository

Create a user repository

Delete a user repository

Library Repository

Create a library repository

Delete a library repository

Repository Images

User Repository Images

Update user repository images

List user repository images

Library Repository Images

Update library repository images

List library repository images

Repository Authorization

Library Repository

Authorize a token for a library

User Repository

Authorize a token for a user repository

Users

User Login

User Register

Update User

docker-io_api.md 12 KB

History Raw