page_title: Registry API page_description: API Documentation for Docker Registry page_keywords: API, Docker, index, registry, REST, documentation
We expect that there will be multiple registries out there. To help to grasp the context, here are some examples of registries:
Note: Mirror registries and private registries which do not use the Index don't even need to run the registry code. They can be implemented by any kind of transport implementing HTTP GET and PUT. Read-only registries can be powered by a simple static HTTP server.
Note: The latter implies that while HTTP is the protocol of choice for a registry, multiple schemes are possible (and in some cases, trivial):
- HTTP with GET (and PUT for read-write registries);
- local mount point;
- remote docker addressed through SSH.
The latter would only require two new commands in docker, e.g. registryget
and registryput
, wrapping access to the local filesystem (and optionally doing consistency checks). Authentication and authorization are then delegated to SSH (e.g. with public keys).
GET /v1/images/(image_id)/layer
Get image layer for a given image_id
**Example Request**: GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Authorization: Token signature=123abc,repository="foo/bar",access=read Parameters: - **image_id** – the id for the layer you want to get **Example Response**: HTTP/1.1 200 Vary: Accept X-Docker-Registry-Version: 0.6.0 Cookie: (Cookie provided by the Registry) {layer binary data stream} Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Image not found
PUT /v1/images/(image_id)/layer
Put image layer for a given image_id
**Example Request**: PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/layer HTTP/1.1 Host: registry-1.docker.io Transfer-Encoding: chunked Authorization: Token signature=123abc,repository="foo/bar",access=write {layer binary data stream} Parameters: - **image_id** – the id for the layer you want to get **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "" Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Image not found
PUT /v1/images/(image_id)/json
Put image for a given image_id
**Example Request**: PUT /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) { id: "088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c", parent: "aeee6396d62273d180a49c96c62e45438d87c7da4a5cf5d2be6bee4e21bc226f", created: "2013-04-30T17:46:10.843673+03:00", container: "8305672a76cc5e3d168f97221106ced35a76ec7ddbb03209b0f0d96bf74f6ef7", container_config: { Hostname: "host-test", User: "", Memory: 0, MemorySwap: 0, AttachStdin: false, AttachStdout: false, AttachStderr: false, PortSpecs: null, Tty: false, OpenStdin: false, StdinOnce: false, Env: null, Cmd: [ "/bin/bash", "-c", "apt-get -q -yy -f install libevent-dev" ], Dns: null, Image: "imagename/blah", Volumes: { }, VolumesFrom: "" }, docker_version: "0.1.7" } Parameters: - **image_id** – the id for the layer you want to get **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "" Status Codes: - **200** – OK - **401** – Requires authorization
GET /v1/images/(image_id)/json
Get image for a given image_id
**Example Request**: GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/json HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) Parameters: - **image_id** – the id for the layer you want to get **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 X-Docker-Size: 456789 X-Docker-Checksum: b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087 { id: "088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c", parent: "aeee6396d62273d180a49c96c62e45438d87c7da4a5cf5d2be6bee4e21bc226f", created: "2013-04-30T17:46:10.843673+03:00", container: "8305672a76cc5e3d168f97221106ced35a76ec7ddbb03209b0f0d96bf74f6ef7", container_config: { Hostname: "host-test", User: "", Memory: 0, MemorySwap: 0, AttachStdin: false, AttachStdout: false, AttachStderr: false, PortSpecs: null, Tty: false, OpenStdin: false, StdinOnce: false, Env: null, Cmd: [ "/bin/bash", "-c", "apt-get -q -yy -f install libevent-dev" ], Dns: null, Image: "imagename/blah", Volumes: { }, VolumesFrom: "" }, docker_version: "0.1.7" } Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Image not found
GET /v1/images/(image_id)/ancestry
Get ancestry for an image given an image_id
**Example Request**: GET /v1/images/088b4505aa3adc3d35e79c031fa126b403200f02f51920fbd9b7c503e87c7a2c/ancestry HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) Parameters: - **image_id** – the id for the layer you want to get **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 ["088b4502f51920fbd9b7c503e87c7a2c05aa3adc3d35e79c031fa126b403200f", "aeee63968d87c7da4a5cf5d2be6bee4e21bc226fd62273d180a49c96c62e4543", "bfa4c5326bc764280b0863b46a4b20d940bc1897ef9c1dfec060604bdc383280", "6ab5893c6927c15a15665191f2c6cf751f5056d8b95ceee32e43c5e8a3648544"] Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Image not found
GET /v1/repositories/(namespace)/(repository)/tags
Get all of the tags for the given repo.
**Example Request**: GET /v1/repositories/foo/bar/tags HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json X-Docker-Registry-Version: 0.6.0 Cookie: (Cookie provided by the Registry) Parameters: - **namespace** – namespace for the repo - **repository** – name for the repo **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 { "latest": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f", "0.1.1": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087" } Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Repository not found
`GET /v1/repositories/(namespace)/(repository)/tags/(tag*):
Get a tag for the given repo.
**Example Request**: GET /v1/repositories/foo/bar/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json X-Docker-Registry-Version: 0.6.0 Cookie: (Cookie provided by the Registry) Parameters: - **namespace** – namespace for the repo - **repository** – name for the repo - **tag** – name of tag you want to get **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f" Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Tag not found
`DELETE /v1/repositories/(namespace)/(repository)/tags/(tag*):
Delete the tag for the repo
**Example Request**: DELETE /v1/repositories/foo/bar/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) Parameters: - **namespace** – namespace for the repo - **repository** – name for the repo - **tag** – name of tag you want to delete **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "" Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Tag not found
`PUT /v1/repositories/(namespace)/(repository)/tags/(tag*):
Put a tag for the given repo.
**Example Request**: PUT /v1/repositories/foo/bar/tags/latest HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f" Parameters: - **namespace** – namespace for the repo - **repository** – name for the repo - **tag** – name of tag you want to add **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "" Status Codes: - **200** – OK - **400** – Invalid data - **401** – Requires authorization - **404** – Image not found
DELETE /v1/repositories/(namespace)/(repository)/
Delete a repository
**Example Request**: DELETE /v1/repositories/foo/bar/ HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json Cookie: (Cookie provided by the Registry) "" Parameters: - **namespace** – namespace for the repo - **repository** – name for the repo **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "" Status Codes: - **200** – OK - **401** – Requires authorization - **404** – Repository not found
GET /v1/_ping
Check status of the registry. This endpoint is also used to determine if the registry supports SSL.
**Example Request**: GET /v1/_ping HTTP/1.1 Host: registry-1.docker.io Accept: application/json Content-Type: application/json "" **Example Response**: HTTP/1.1 200 Vary: Accept Content-Type: application/json X-Docker-Registry-Version: 0.6.0 "" Status Codes: - **200** – OK
This is where we describe the authorization process, including the tokens and cookies.
TODO: add more info.