When the manifest is in hand, the client must verify the signature to ensure
the names and layers are valid. Once confirmed, the client will then use the
digests to download the individual layers. Layers are stored in as blobs in
the V2 registry API, keyed by their digest.
#### Pulling an Image Manifest
The image manifest can be fetched with the following url:
```
GET /v2/<name>/manifests/<reference>
```
The `name` and `reference` parameter identify the image and are required. The
reference may include a tag or digest.
The client should include an Accept header indicating which manifest content
types it supports. For more details on the manifest formats and their content
types, see [manifest-v2-1.md](manifest-v2-1.md) and
[manifest-v2-2.md](manifest-v2-2.md). In a successful response, the Content-Type
header will indicate which manifest type is being returned.
A `404 Not Found` response will be returned if the image is unknown to the
registry. If the image exists and the response is successful, the image
manifest will be returned, with the following format (see
[docker/docker#8093](https://github.com/docker/docker/issues/8093) for details):
{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": <digest>
},
...
]
],
"history": <v1images>,
"signature": <JWS>
}
The client should verify the returned manifest signature for authenticity
before fetching layers.
##### Existing Manifests
The image manifest can be checked for existence with the following url:
```
HEAD /v2/<name>/manifests/<reference>
```
The `name` and `reference` parameter identify the image and are required. The
reference may include a tag or digest.
A `404 Not Found` response will be returned if the image is unknown to the
registry. If the image exists and the response is successful the response will
be as follows:
```
200 OK
Content-Length: <lengthofmanifest>
Docker-Content-Digest: <digest>
```
#### Pulling a Layer
Layers are stored in the blob portion of the registry, keyed by digest.
Pulling a layer is carried out by a standard http request. The URL is as
follows:
GET /v2/<name>/blobs/<digest>
Access to a layer will be gated by the `name` of the repository but is
identified uniquely in the registry by `digest`.
This endpoint may issue a 307 (302 for <HTTP1.1)redirecttoanotherservice
for downloading the layer and clients should be prepared to handle redirects.
This endpoint should support aggressive HTTP caching for image layers. Support
for Etags, modification dates and other cache control headers should be
included. To allow for incremental downloads, `Range` requests should be
supported, as well.
### Pushing An Image
Pushing an image works in the opposite order as a pull. After assembling the
image manifest, the client must first push the individual layers. When the
layers are fully pushed into the registry, the client should upload the signed
manifest.
The details of each step of the process are covered in the following sections.
#### Pushing a Layer
All layer uploads use two steps to manage the upload process. The first step
starts the upload in the registry service, returning a url to carry out the
second step. The second step uses the upload url to transfer the actual data.
Uploads are started with a POST request which returns a url that can be used
to push data and check upload status.
The `Location` header will be used to communicate the upload location after
each request. While it won't change in the this specification, clients should
use the most recent value returned by the API.
##### Starting An Upload
To begin the process, a POST request should be issued in the following format:
```
POST /v2/<name>/blobs/uploads/
```
The parameters of this request are the image namespace under which the layer
will be linked. Responses to this request are covered below.
##### Existing Layers
The existence of a layer can be checked via a `HEAD` request to the blob store
API. The request should be formatted as follows:
```
HEAD /v2/<name>/blobs/<digest>
```
If the layer with the digest specified in `digest` is available, a 200 OK
response will be received, with no actual body content (this is according to
http specification). The response will look as follows:
```
200 OK
Content-Length: <lengthofblob>
Docker-Content-Digest: <digest>
```
When this response is received, the client can assume that the layer is
already available in the registry under the given name and should take no
further action to upload the layer. Note that the binary digests may differ
for the existing registry layer, but the digests will be guaranteed to match.
##### Uploading the Layer
If the POST request is successful, a `202 Accepted` response will be returned
with the upload URL in the `Location` header:
```
202 Accepted
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The rest of the upload process can be carried out with the returned url,
called the "Upload URL" from the `Location` header. All responses to the
upload url, whether sending data or getting status, will be in this format.
Though the URI format (`/v2/<name>/blobs/uploads/<uuid>`) for the `Location`
header is specified, clients should treat it as an opaque url and should never
try to assemble it. While the `uuid` parameter may be an actual UUID, this
proposal imposes no constraints on the format and clients should never impose
any.
If clients need to correlate local upload state with remote upload state, the
contents of the `Docker-Upload-UUID` header should be used. Such an id can be
used to key the last used location header when implementing resumable uploads.
##### Upload Progress
The progress and chunk coordination of the upload process will be coordinated
through the `Range` header. While this is a non-standard use of the `Range`
header, there are examples of [similar approaches](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) in APIs with heavy use.
For an upload that just started, for an example with a 1000 byte layer file,
the `Range` header would be as follows:
```
Range: bytes=0-0
```
To get the status of an upload, issue a GET request to the upload URL:
```
GET /v2/<name>/blobs/uploads/<uuid>
Host: <registryhost>
```
The response will be similar to the above, except will return 204 status:
```
204 No Content
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Docker-Upload-UUID: <uuid>
```
Note that the HTTP `Range` header byte ranges are inclusive and that will be
honored, even in non-standard use cases.
##### Monolithic Upload
A monolithic upload is simply a chunked upload with a single chunk and may be
favored by clients that would like to avoided the complexity of chunking. To
carry out a "monolithic" upload, one can simply put the entire content blob to
the provided URL:
```
PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
Content-Length: <sizeoflayer>
Content-Type: application/octet-stream
<LayerBinaryData>
```
The "digest" parameter must be included with the PUT request. Please see the
[_Completed Upload_](#completed-upload) section for details on the parameters
and expected responses.
##### Chunked Upload
To carry out an upload of a chunk, the client can specify a range header and
only include that part of the layer file:
```
PATCH /v2/<name>/blobs/uploads/<uuid>
Content-Length: <sizeofchunk>
Content-Range: <startofrange>-<endofrange>
Content-Type: application/octet-stream
<LayerChunkBinaryData>
```
There is no enforcement on layer chunk splits other than that the server must
receive them in order. The server may enforce a minimum chunk size. If the
server cannot accept the chunk, a `416 Requested Range Not Satisfiable`
response will be returned and will include a `Range` header indicating the
current status:
```
416 Requested Range Not Satisfiable
Location: /v2/<name>/blobs/uploads/<uuid>
Range: 0-<lastvalidrange>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
If this response is received, the client should resume from the "last valid
range" and upload the subsequent chunk. A 416 will be returned under the
following conditions:
- Invalid Content-Range header format
- Out of order chunk: the range of the next chunk must start immediately after
the "last valid range" from the previous response.
When a chunk is accepted as part of the upload, a `202 Accepted` response will
be returned, including a `Range` header with the current upload status:
```
202 Accepted
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
##### Completed Upload
For an upload to be considered complete, the client must submit a `PUT`
request on the upload endpoint with a digest parameter. If it is not provided,
the upload will not be considered complete. The format for the final chunk
will be as follows:
```
PUT /v2/<name>/blob/uploads/<uuid>?digest=<digest>
Content-Length: <sizeofchunk>
Content-Range: <startofrange>-<endofrange>
Content-Type: application/octet-stream
<LastLayerChunkBinaryData>
```
Optionally, if all chunks have already been uploaded, a `PUT` request with a
`digest` parameter and zero-length body may be sent to complete and validated
the upload. Multiple "digest" parameters may be provided with different
digests. The server may verify none or all of them but _must_ notify the
client if the content is rejected.
When the last chunk is received and the layer has been validated, the client
will receive a `201 Created` response:
```
201 Created
Location: /v2/<name>/blobs/<digest>
Content-Length: 0
Docker-Content-Digest: <digest>
```
The `Location` header will contain the registry URL to access the accepted
layer file. The `Docker-Content-Digest` header returns the canonical digest of
the uploaded blob which may differ from the provided digest. Most clients may
ignore the value but if it is used, the client should verify the value against
the uploaded blob data.
###### Digest Parameter
The "digest" parameter is designed as an opaque parameter to support
verification of a successful transfer. For example, an HTTP URI parameter
> for more details, see: [compatibility.md](../compatibility.md#content-addressable-storage-cas)
## Detail
> **Note**: This section is still under construction. For the purposes of
> implementation, if any details below differ from the described request flows
> above, the section below should be corrected. When they match, this note
> should be removed.
The behavior of the endpoints are covered in detail in this section, organized
by route and entity. All aspects of the request and responses are covered,
including headers, parameters and body formats. Examples of requests and their
corresponding responses, with success and failure, are enumerated.
> **Note**: The sections on endpoint detail are arranged with an example
> request, a description of the request, followed by information about that
> request.
A list of methods and URIs are covered in the table below:
|Method|Path|Entity|Description|
|------|----|------|-----------|
| GET | `/v2/` | Base | Check that the endpoint implements Docker Registry API V2. |
| GET | `/v2/<name>/tags/list` | Tags | Fetch the tags under the repository identified by `name`. |
| GET | `/v2/<name>/manifests/<reference>` | Manifest | Fetch the manifest identified by `name` and `reference` where `reference` can be a tag or digest. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. |
| PUT | `/v2/<name>/manifests/<reference>` | Manifest | Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest. |
| DELETE | `/v2/<name>/manifests/<reference>` | Manifest | Delete the manifest identified by `name` and `reference`. Note that a manifest can _only_ be deleted by `digest`. |
| GET | `/v2/<name>/blobs/<digest>` | Blob | Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data. |
| DELETE | `/v2/<name>/blobs/<digest>` | Blob | Delete the blob identified by `name` and `digest` |
| POST | `/v2/<name>/blobs/uploads/` | Initiate Blob Upload | Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request. |
| GET | `/v2/<name>/blobs/uploads/<uuid>` | Blob Upload | Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload. |
| PATCH | `/v2/<name>/blobs/uploads/<uuid>` | Blob Upload | Upload a chunk of data for the specified upload. |
| PUT | `/v2/<name>/blobs/uploads/<uuid>` | Blob Upload | Complete the upload specified by `uuid`, optionally appending the body as the final chunk. |
| DELETE | `/v2/<name>/blobs/uploads/<uuid>` | Blob Upload | Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout. |
| GET | `/v2/_catalog` | Catalog | Retrieve a sorted, json list of repositories available in the registry. |
The detail for each endpoint is covered in the following sections.
### Errors
The error codes encountered via the API are enumerated in the following table:
|Code|Message|Description|
|----|-------|-----------|
`BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload.
`BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed.
`BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned.
`DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest.
`MANIFEST_BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a manifest blob is unknown to the registry.
`MANIFEST_INVALID` | manifest invalid | During upload, manifests undergo several checks ensuring validity. If those checks fail, this error may be returned, unless a more specific error is included. The detail will contain information the failed validation.
`MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository.
`MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned.
`NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation.
`NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry.
`SIZE_INVALID` | provided length did not match content length | When a layer is uploaded, the provided size will be checked against the uploaded content. If they do not match, this error will be returned.
`TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned.
`UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate.
`DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource.
`UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters.
### Base
Base V2 API route. Typically, this can be used for lightweight version checks and to validate registry authentication.
#### GET Base
Check that the endpoint implements Docker Registry API V2.
```
GET /v2/
Host: <registryhost>
Authorization: <scheme><token>
```
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
### Tags
Retrieve information about tags.
#### GET Tags
Fetch the tags under the repository identified by `name`.
##### Tags
```
GET /v2/<name>/tags/list
Host: <registryhost>
Authorization: <scheme><token>
```
Return all tags for the repository
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
##### Tags Paginated
```
GET /v2/<name>/tags/list?n=<integer>&last=<integer>
```
Return a portion of the tags for the specified repository.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`name`|path|Name of the target repository.|
|`n`|query|Limit the number of entries in each response. It not present, all entries will be returned.|
|`last`|query|Result set will include values lexically after last.|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
### Manifest
Create, update, delete and retrieve manifests.
#### GET Manifest
Fetch the manifest identified by `name` and `reference` where `reference` can be a tag or digest. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data.
```
GET /v2/<name>/manifests/<reference>
Host: <registryhost>
Authorization: <scheme><token>
```
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`reference`|path|Tag or digest of the target manifest.|
###### On Success: OK
```
200 OK
Docker-Content-Digest: <digest>
Content-Type: <mediatypeofmanifest>
{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": "<digest>"
},
...
]
],
"history": <v1images>,
"signature": <JWS>
}
```
The manifest identified by `name` and `reference`. The contents can be used to identify and resolve resources required to run the specified image.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The name or reference was invalid.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
#### PUT Manifest
Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest.
```
PUT /v2/<name>/manifests/<reference>
Host: <registryhost>
Authorization: <scheme><token>
Content-Type: <mediatypeofmanifest>
{
"name": <name>,
"tag": <tag>,
"fsLayers": [
{
"blobSum": "<digest>"
},
...
]
],
"history": <v1images>,
"signature": <JWS>
}
```
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`reference`|path|Tag or digest of the target manifest.|
###### On Success: Created
```
201 Created
Location: <url>
Content-Length: 0
Docker-Content-Digest: <digest>
```
The manifest has been accepted by the registry and is stored under the specified `name` and `tag`.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`|The canonical location url of the uploaded manifest.|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
###### On Failure: Invalid Manifest
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The received manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. |
| `MANIFEST_INVALID` | manifest invalid | During upload, manifests undergo several checks ensuring validity. If those checks fail, this error may be returned, unless a more specific error is included. The detail will contain information the failed validation. |
| `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
###### On Failure: Missing Layer(s)
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [{
"code": "BLOB_UNKNOWN",
"message": "blob unknown to registry",
"detail": {
"digest": "<digest>"
}
},
...
]
}
```
One or more layers may be missing during a manifest upload. If so, the missing layers will be enumerated in the error response.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
###### On Failure: Not allowed
```
405 Method Not Allowed
```
Manifest put is not allowed because the registry is configured as a pull-through cache or for some other reason
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
#### DELETE Manifest
Delete the manifest identified by `name` and `reference`. Note that a manifest can _only_ be deleted by `digest`.
```
DELETE /v2/<name>/manifests/<reference>
Host: <registryhost>
Authorization: <scheme><token>
```
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`reference`|path|Tag or digest of the target manifest.|
###### On Success: Accepted
```
202 Accepted
```
###### On Failure: Invalid Name or Reference
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The specified `name` or `reference` were invalid and the delete was unable to proceed.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `TAG_INVALID` | manifest tag did not match URI | During a manifest upload, if the tag in the manifest does not match the uri tag, this error will be returned. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
###### On Failure: Unknown Manifest
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The specified `name` or `reference` are unknown to the registry and the delete was unable to proceed. Clients can assume the manifest was already deleted if this response is returned.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository. |
###### On Failure: Not allowed
```
405 Method Not Allowed
```
Manifest delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
### Blob
Operations on blobs identified by `name` and `digest`. Used to fetch or delete layers by digest.
#### GET Blob
Retrieve the blob from the registry identified by `digest`. A `HEAD` request can also be issued to this endpoint to obtain resource information without receiving all data.
##### Fetch Blob
```
GET /v2/<name>/blobs/<digest>
Host: <registryhost>
Authorization: <scheme><token>
```
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
The blob identified by `digest` is available. The blob content will be present in the body of the request.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Content-Length`|The length of the requested blob content.|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
###### On Success: Temporary Redirect
```
307 Temporary Redirect
Location: <bloblocation>
Docker-Content-Digest: <digest>
```
The blob identified by `digest` is available at the provided location.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`|The location where the layer should be accessible.|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The blob, identified by `name` and `digest`, is unknown to the registry.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
##### Fetch Blob Part
```
GET /v2/<name>/blobs/<digest>
Host: <registryhost>
Authorization: <scheme><token>
Range: bytes=<start>-<end>
```
This endpoint may also support RFC7233 compliant range requests. Support can be detected by issuing a HEAD request. If the header `Accept-Range: bytes` is returned, range requests can be used to fetch partial content.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Range`|header|HTTP Range header specifying blob chunk.|
|`name`|path|Name of the target repository.|
|`digest`|path|Digest of desired blob.|
###### On Success: Partial Content
```
206 Partial Content
Content-Length: <length>
Content-Range: bytes <start>-<end>/<size>
Content-Type: application/octet-stream
<blobbinarydata>
```
The blob identified by `digest` is available. The specified chunk of blob content will be present in the body of the request.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Content-Length`|The length of the requested blob chunk.|
|`Content-Range`|Content range of blob chunk.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
###### On Failure: Requested Range Not Satisfiable
```
416 Requested Range Not Satisfiable
```
The range specification cannot be satisfied for the requested content. This can happen when the range is not formatted correctly or if the range is outside of the valid size of the content.
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
#### DELETE Blob
Delete the blob identified by `name` and `digest`
```
DELETE /v2/<name>/blobs/<digest>
Host: <registryhost>
Authorization: <scheme><token>
```
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Content-Length`|0|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
###### On Failure: Invalid Name or Digest
```
400 Bad Request
```
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The blob, identified by `name` and `digest`, is unknown to the registry.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
| `BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a blob is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
###### On Failure: Method Not Allowed
```
405 Method Not Allowed
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
Blob delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
### Initiate Blob Upload
Initiate a blob upload. This endpoint can be used to create resumable uploads or monolithic uploads.
#### POST Initiate Blob Upload
Initiate a resumable blob upload. If successful, an upload location will be provided to complete the upload. Optionally, if the `digest` parameter is present, the request body will be used to complete the upload in a single request.
##### Initiate Monolithic Blob Upload
```
POST /v2/<name>/blobs/uploads/?digest=<digest>
Host: <registryhost>
Authorization: <scheme><token>
Content-Length: <lengthofblob>
Content-Type: application/octect-stream
<binarydata>
```
Upload a blob identified by the `digest` parameter in single request. This upload will not be resumable unless a recoverable error is returned.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`digest`|query|Digest of uploaded blob. If present, the upload will be completed, in a single request, with contents of the request body as the resulting blob.|
###### On Success: Created
```
201 Created
Location: <bloblocation>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The blob has been created in the registry and is available at the provided location.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`||
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
###### On Failure: Invalid Name or Digest
```
400 Bad Request
```
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
###### On Failure: Not allowed
```
405 Method Not Allowed
```
Blob upload is not allowed because the registry is configured as a pull-through cache or for some other reason
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
##### Initiate Resumable Blob Upload
```
POST /v2/<name>/blobs/uploads/
Host: <registryhost>
Authorization: <scheme><token>
Content-Length: 0
```
Initiate a resumable blob upload with an empty request body.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
|`name`|path|Name of the target repository.|
###### On Success: Accepted
```
202 Accepted
Content-Length: 0
Location: /v2/<name>/blobs/uploads/<uuid>
Range: 0-0
Docker-Upload-UUID: <uuid>
```
The upload has been created. The `Location` header must be used to complete the upload. The response should be identical to a `GET` request on the contents of the returned `Location` header.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Location`|The location of the created upload. Clients should use the contents verbatim to complete the upload, adding parameters where required.|
|`Range`|Range header indicating the progress of the upload. When starting an upload, it will return an empty range, since no content has been received.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
###### On Failure: Invalid Name or Digest
```
400 Bad Request
```
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
##### Mount Blob
```
POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repositoryname>
Host: <registryhost>
Authorization: <scheme><token>
Content-Length: 0
```
Mount a blob identified by the `mount` parameter from another repository.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
|`name`|path|Name of the target repository.|
|`mount`|query|Digest of blob to mount from the source repository.|
|`from`|query|Name of the source repository.|
###### On Success: Created
```
201 Created
Location: <bloblocation>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The blob has been mounted in the repository and is available at the provided location.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`||
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
###### On Failure: Invalid Name or Digest
```
400 Bad Request
```
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
###### On Failure: Not allowed
```
405 Method Not Allowed
```
Blob mount is not allowed because the registry is configured as a pull-through cache or for some other reason
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
### Blob Upload
Interact with blob uploads. Clients should never assemble URLs for this endpoint and should only take it through the `Location` header on related API requests. The `Location` header and its parameters should be preserved by clients, using the latest value returned via upload related API calls.
#### GET Blob Upload
Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload.
```
GET /v2/<name>/blobs/uploads/<uuid>
Host: <registryhost>
Authorization: <scheme><token>
```
Retrieve the progress of the current upload, as reported by the `Range` header.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
###### On Success: Upload Progress
```
204 No Content
Range: 0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The upload is known and in progress. The last received offset is available in the `Range` header.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Range`|Range indicating the current progress of the upload.|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
There was an error processing the upload and it must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The upload is unknown to the registry. The upload must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
#### PATCH Blob Upload
Upload a chunk of data for the specified upload.
##### Stream upload
```
PATCH /v2/<name>/blobs/uploads/<uuid>
Host: <registryhost>
Authorization: <scheme><token>
Content-Type: application/octet-stream
<binarydata>
```
Upload a stream of data to upload without completing the upload.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
###### On Success: Data Accepted
```
204 No Content
Location: /v2/<name>/blobs/uploads/<uuid>
Range: 0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The stream of data has been accepted and the current progress is available in the range header. The updated upload location is available in the `Location` header.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`|The location of the upload. Clients should assume this changes after each request. Clients should use the contents verbatim to complete the upload, adding parameters where required.|
|`Range`|Range indicating the current progress of the upload.|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
There was an error processing the upload and it must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The upload is unknown to the registry. The upload must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
|`Content-Range`|header|Range of bytes identifying the desired block of content represented by the body. Start must the end offset retrieved via status check plus one. Note that this is a non-standard use of the `Content-Range` header.|
|`Content-Length`|header|Length of the chunk being uploaded, corresponding the length of the request body.|
|`name`|path|Name of the target repository.|
|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
###### On Success: Chunk Accepted
```
204 No Content
Location: /v2/<name>/blobs/uploads/<uuid>
Range: 0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>
```
The chunk of data has been accepted and the current progress is available in the range header. The updated upload location is available in the `Location` header.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`|The location of the upload. Clients should assume this changes after each request. Clients should use the contents verbatim to complete the upload, adding parameters where required.|
|`Range`|Range indicating the current progress of the upload.|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
There was an error processing the upload and it must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The upload is unknown to the registry. The upload must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. |
###### On Failure: Requested Range Not Satisfiable
```
416 Requested Range Not Satisfiable
```
The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid.
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
#### PUT Blob Upload
Complete the upload specified by `uuid`, optionally appending the body as the final chunk.
```
PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
Host: <registryhost>
Authorization: <scheme><token>
Content-Length: <lengthofdata>
Content-Type: application/octet-stream
<binarydata>
```
Complete the upload, providing all the data in the body, if necessary. A request without a body will just complete the upload with previously uploaded content.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
The upload has been completed and accepted by the registry. The canonical location will be available in the `Location` header.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Location`|The canonical location of the blob for retrieval|
|`Content-Range`|Range of bytes identifying the desired block of content represented by the body. Start must match the end of offset retrieved via status check. Note that this is a non-standard use of the `Content-Range` header.|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
|`Docker-Content-Digest`|Digest of the targeted content for the request.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
There was an error processing the upload and it must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DIGEST_INVALID` | provided digest did not match uploaded content | When a blob is uploaded, the registry will check that the content matches the digest provided by the client. The error may include a detail structure with the key "digest", including the invalid digest string. This error may also be returned when a manifest includes an invalid layer digest. |
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The upload is unknown to the registry. The upload must be restarted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
#### DELETE Blob Upload
Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout.
```
DELETE /v2/<name>/blobs/uploads/<uuid>
Host: <registryhost>
Authorization: <scheme><token>
Content-Length: 0
```
Cancel the upload specified by `uuid`.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
|`name`|path|Name of the target repository.|
|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
###### On Success: Upload Deleted
```
204 No Content
Content-Length: 0
```
The upload has been successfully deleted.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
###### On Failure: Bad Request
```
400 Bad Request
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
An error was encountered processing the delete. The client may ignore this error.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
###### On Failure: Not Found
```
404 Not Found
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The upload is unknown to the registry. The client may ignore this error and assume the upload has been deleted.
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | If a blob upload has been cancelled or was never started, this error code may be returned. |
###### On Failure: Authentication Required
```
401 Unauthorized
WWW-Authenticate: <scheme> realm="<realm>", ..."
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client is not authenticated.
The following headers will be returned on the response:
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `UNAUTHORIZED` | authentication required | The access controller was unable to authenticate the client. Often this will be accompanied by a Www-Authenticate HTTP response header indicating how to authenticate. |
###### On Failure: No Such Repository Error
```
404 Not Found
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The repository is not known to the registry.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
###### On Failure: Access Denied
```
403 Forbidden
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client does not have required access to the repository.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
###### On Failure: Too Many Requests
```
429 Too Many Requests
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"errors:" [
{
"code": <errorcode>,
"message": "<errormessage>",
"detail": ...
},
...
]
}
```
The client made too many requests within a time interval.
The following headers will be returned on the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
The error codes that may be included in the response body are enumerated below:
|Code|Message|Description|
|----|-------|-----------|
| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
### Catalog
List a set of available repositories in the local registry cluster. Does not provide any indication of what may be available upstream. Applications can only determine if a repository is available but not if it is not available.
#### GET Catalog
Retrieve a sorted, json list of repositories available in the registry.
##### Catalog Fetch
```
GET /v2/_catalog
```
Request an unabridged list of repositories available. The implementation may impose a maximum limit and return a partial set with pagination links.
###### On Success: OK
```
200 OK
Content-Length: <length>
Content-Type: application/json; charset=utf-8
{
"repositories": [
<name>,
...
]
}
```
Returns the unabridged list of repositories as a json response.
The following headers will be returned with the response:
|Name|Description|
|----|-----------|
|`Content-Length`|Length of the JSON response body.|
##### Catalog Fetch Paginated
```
GET /v2/_catalog?n=<integer>&last=<integer>
```
Return the specified portion of repositories.
The following parameters should be specified on the request:
|Name|Kind|Description|
|----|----|-----------|
|`n`|query|Limit the number of entries in each response. It not present, all entries will be returned.|
|`last`|query|Result set will include values lexically after last.|
