1---
2title: "HTTP API V2"
3description: "Specification for the Registry API."
4keywords: registry, on-prem, images, tags, repository, distribution, api, advanced
5redirect_from:
6 - /reference/api/registry_api/
7---
8
9# Docker Registry HTTP API V2
10
11## Introduction
12
13The _Docker Registry HTTP API_ is the protocol to facilitate distribution of
14images to the docker engine. It interacts with instances of the docker
15registry, which is a service to manage information about docker images and
16enable their distribution. The specification covers the operation of version 2
17of this API, known as _Docker Registry HTTP API V2_.
18
19While the V1 registry protocol is usable, there are several problems with the
20architecture that have led to this new version. The main driver of this
21specification is a set of changes to the Docker image format, covered in
22[docker/docker#8093](https://github.com/docker/docker/issues/8093).
23The new, self-contained image manifest simplifies image definition and improves
24security. This specification will build on that work, leveraging new properties
25of the manifest format to improve performance, reduce bandwidth usage and
26decrease the likelihood of backend corruption.
27
28For relevant details and history leading up to this specification, please see
29the following issues:
30
31- [docker/docker#8093](https://github.com/docker/docker/issues/8093)
32- [docker/docker#9015](https://github.com/docker/docker/issues/9015)
33- [docker/docker-registry#612](https://github.com/docker/docker-registry/issues/612)
34
35### Scope
36
37This specification covers the URL layout and protocols of the interaction
38between docker registry and docker core. This will affect the docker core
39registry API and the rewrite of docker-registry. Docker registry
40implementations may implement other API endpoints, but they are not covered by
41this specification.
42
43This includes the following features:
44
45- Namespace-oriented URI Layout
46- PUSH/PULL registry server for V2 image manifest format
47- Resumable layer PUSH support
48- V2 Client library implementation
49
50While authentication and authorization support will influence this
51specification, details of the protocol will be left to a future specification.
52Relevant header definitions and error codes are present to provide an
53indication of what a client may encounter.
54
55#### Future
56
57There are features that have been discussed during the process of cutting this
58specification. The following is an incomplete list:
59
60- Immutable image references
61- Multiple architecture support
62- Migration from v2compatibility representation
63
64These may represent features that are either out of the scope of this
65specification, the purview of another specification or have been deferred to a
66future version.
67
68### Use Cases
69
70For the most part, the use cases of the former registry API apply to the new
71version. Differentiating use cases are covered below.
72
73#### Image Verification
74
75A docker engine instance would like to run verified image named
76"library/ubuntu", with the tag "latest". The engine contacts the registry,
77requesting the manifest for "library/ubuntu:latest". An untrusted registry
78returns a manifest. Before proceeding to download the individual layers, the
79engine verifies the manifest's signature, ensuring that the content was
80produced from a trusted source and no tampering has occurred. After each layer
81is downloaded, the engine verifies the digest of the layer, ensuring that the
82content matches that specified by the manifest.
83
84#### Resumable Push
85
86Company X's build servers lose connectivity to docker registry before
87completing an image layer transfer. After connectivity returns, the build
88server attempts to re-upload the image. The registry notifies the build server
89that the upload has already been partially attempted. The build server
90responds by only sending the remaining data to complete the image file.
91
92#### Resumable Pull
93
94Company X is having more connectivity problems but this time in their
95deployment datacenter. When downloading an image, the connection is
96interrupted before completion. The client keeps the partial data and uses http
97`Range` requests to avoid downloading repeated data.
98
99#### Layer Upload De-duplication
100
101Company Y's build system creates two identical docker layers from build
102processes A and B. Build process A completes uploading the layer before B.
103When process B attempts to upload the layer, the registry indicates that its
104not necessary because the layer is already known.
105
106If process A and B upload the same layer at the same time, both operations
107will proceed and the first to complete will be stored in the registry (Note:
108we may modify this to prevent dogpile with some locking mechanism).
109
110### Changes
111
112The V2 specification has been written to work as a living document, specifying
113only what is certain and leaving what is not specified open or to future
114changes. Only non-conflicting additions should be made to the API and accepted
115changes should avoid preventing future changes from happening.
116
117This section should be updated when changes are made to the specification,
118indicating what is different. Optionally, we may start marking parts of the
119specification to correspond with the versions enumerated here.
120
121Each set of changes is given a letter corresponding to a set of modifications
122that were applied to the baseline specification. These are merely for
123reference and shouldn't be used outside the specification other than to
124identify a set of modifications.
125
126<dl>
127 <dt>l</dt>
128 <dd>
129 <ul>
130 <li>Document TOOMANYREQUESTS error code.</li>
131 </ul>
132 </dd>
133
134 <dt>k</dt>
135 <dd>
136 <ul>
137 <li>Document use of Accept and Content-Type headers in manifests endpoint.</li>
138 </ul>
139 </dd>
140
141 <dt>j</dt>
142 <dd>
143 <ul>
144 <li>Add ability to mount blobs across repositories.</li>
145 </ul>
146 </dd>
147
148 <dt>i</dt>
149 <dd>
150 <ul>
151 <li>Clarified expected behavior response to manifest HEAD request.</li>
152 </ul>
153 </dd>
154
155 <dt>h</dt>
156 <dd>
157 <ul>
158 <li>All mention of tarsum removed.</li>
159 </ul>
160 </dd>
161
162 <dt>g</dt>
163 <dd>
164 <ul>
165 <li>Clarify behavior of pagination behavior with unspecified parameters.</li>
166 </ul>
167 </dd>
168
169 <dt>f</dt>
170 <dd>
171 <ul>
172 <li>Specify the delete API for layers and manifests.</li>
173 </ul>
174 </dd>
175
176 <dt>e</dt>
177 <dd>
178 <ul>
179 <li>Added support for listing registry contents.</li>
180 <li>Added pagination to tags API.</li>
181 <li>Added common approach to support pagination.</li>
182 </ul>
183 </dd>
184
185 <dt>d</dt>
186 <dd>
187 <ul>
188 <li>Allow repository name components to be one character.</li>
189 <li>Clarified that single component names are allowed.</li>
190 </ul>
191 </dd>
192
193 <dt>c</dt>
194 <dd>
195 <ul>
196 <li>Added section covering digest format.</li>
197 <li>Added more clarification that manifest cannot be deleted by tag.</li>
198 </ul>
199 </dd>
200
201 <dt>b</dt>
202 <dd>
203 <ul>
204 <li>Added capability of doing streaming upload to PATCH blob upload.</li>
205 <li>Updated PUT blob upload to no longer take final chunk, now requires entire data or no data.</li>
206 <li>Removed `416 Requested Range Not Satisfiable` response status from PUT blob upload.</li>
207 </ul>
208 </dd>
209
210 <dt>a</dt>
211 <dd>
212 <ul>
213 <li>Added support for immutable manifest references in manifest endpoints.</li>
214 <li>Deleting a manifest by tag has been deprecated.</li>
215 <li>Specified `Docker-Content-Digest` header for appropriate entities.</li>
216 <li>Added error code for unsupported operations.</li>
217 </ul>
218 </dd>
219</dl>
220
221## Overview
222
223This section covers client flows and details of the API endpoints. The URI
224layout of the new API is structured to support a rich authentication and
225authorization model by leveraging namespaces. All endpoints will be prefixed
226by the API version and the repository name:
227
228 /v2/<name>/
229
230For example, an API endpoint that will work with the `library/ubuntu`
231repository, the URI prefix will be:
232
233 /v2/library/ubuntu/
234
235This scheme provides rich access control over various operations and methods
236using the URI prefix and http methods that can be controlled in variety of
237ways.
238
239Classically, repository names have always been two path components where each
240path component is less than 30 characters. The V2 registry API does not
241enforce this. The rules for a repository name are as follows:
242
2431. A repository name is broken up into _path components_. A component of a
244 repository name must be at least one lowercase, alpha-numeric characters,
245 optionally separated by periods, dashes or underscores. More strictly, it
246 must match the regular expression `[a-z0-9]+(?:[._-][a-z0-9]+)*`.
2472. If a repository name has two or more path components, they must be
248 separated by a forward slash ("/").
2493. The total length of a repository name, including slashes, must be less than
250 256 characters.
251
252These name requirements _only_ apply to the registry API and should accept a
253superset of what is supported by other docker ecosystem components.
254
255All endpoints should support aggressive http caching, compression and range
256headers, where appropriate. The new API attempts to leverage HTTP semantics
257where possible but may break from standards to implement targeted features.
258
259For detail on individual endpoints, please see the [_Detail_](#detail)
260section.
261
262### Errors
263
264Actionable failure conditions, covered in detail in their relevant sections,
265are reported as part of 4xx responses, in a json response body. One or more
266errors will be returned in the following format:
267
268 {
269 "errors:" [{
270 "code": <error identifier>,
271 "message": <message describing condition>,
272 "detail": <unstructured>
273 },
274 ...
275 ]
276 }
277
278The `code` field will be a unique identifier, all caps with underscores by
279convention. The `message` field will be a human readable string. The optional
280`detail` field may contain arbitrary json data providing information the
281client can use to resolve the issue.
282
283While the client can take action on certain error codes, the registry may add
284new error codes over time. All client implementations should treat unknown
285error codes as `UNKNOWN`, allowing future error codes to be added without
286breaking API compatibility. For the purposes of the specification error codes
287will only be added and never removed.
288
289For a complete account of all error codes, please see the [_Errors_](#errors-2)
290section.
291
292### API Version Check
293
294A minimal endpoint, mounted at `/v2/` will provide version support information
295based on its response statuses. The request format is as follows:
296
297 GET /v2/
298
299If a `200 OK` response is returned, the registry implements the V2(.1)
300registry API and the client may proceed safely with other V2 operations.
301Optionally, the response may contain information about the supported paths in
302the response body. The client should be prepared to ignore this data.
303
304If a `401 Unauthorized` response is returned, the client should take action
305based on the contents of the "WWW-Authenticate" header and try the endpoint
306again. Depending on access control setup, the client may still have to
307authenticate against different resources, even if this check succeeds.
308
309If `404 Not Found` response status, or other unexpected status, is returned,
310the client should proceed with the assumption that the registry does not
311implement V2 of the API.
312
313When a `200 OK` or `401 Unauthorized` response is returned, the
314"Docker-Distribution-API-Version" header should be set to "registry/2.0".
315Clients may require this header value to determine if the endpoint serves this
316API. When this header is omitted, clients may fallback to an older API version.
317
318### Content Digests
319
320This API design is driven heavily by [content addressability](http://en.wikipedia.org/wiki/Content-addressable_storage).
321The core of this design is the concept of a content addressable identifier. It
322uniquely identifies content by taking a collision-resistant hash of the bytes.
323Such an identifier can be independently calculated and verified by selection
324of a common _algorithm_. If such an identifier can be communicated in a secure
325manner, one can retrieve the content from an insecure source, calculate it
326independently and be certain that the correct content was obtained. Put simply,
327the identifier is a property of the content.
328
329To disambiguate from other concepts, we call this identifier a _digest_. A
330_digest_ is a serialized hash result, consisting of a _algorithm_ and _hex_
331portion. The _algorithm_ identifies the methodology used to calculate the
332digest. The _hex_ portion is the hex-encoded result of the hash.
333
334We define a _digest_ string to match the following grammar:
335```
336digest := algorithm ":" hex
337algorithm := /[A-Fa-f0-9_+.-]+/
338hex := /[A-Fa-f0-9]+/
339```
340
341Some examples of _digests_ include the following:
342
343digest | description |
344----------------------------------------------------------------------------------|------------------------------------------------
345sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b | Common sha256 based digest |
346
347While the _algorithm_ does allow one to implement a wide variety of
348algorithms, compliant implementations should use sha256. Heavy processing of
349input before calculating a hash is discouraged to avoid degrading the
350uniqueness of the _digest_ but some canonicalization may be performed to
351ensure consistent identifiers.
352
353Let's use a simple example in pseudo-code to demonstrate a digest calculation:
354```
355let C = 'a small string'
356let B = sha256(C)
357let D = 'sha256:' + EncodeHex(B)
358let ID(C) = D
359```
360
361Above, we have bytestring `C` passed into a function, `SHA256`, that returns a
362bytestring `B`, which is the hash of `C`. `D` gets the algorithm concatenated
363with the hex encoding of `B`. We then define the identifier of `C` to `ID(C)`
364as equal to `D`. A digest can be verified by independently calculating `D` and
365comparing it with identifier `ID(C)`.
366
367#### Digest Header
368
369To provide verification of http content, any response may include a
370`Docker-Content-Digest` header. This will include the digest of the target
371entity returned in the response. For blobs, this is the entire blob content. For
372manifests, this is the manifest body without the signature content, also known
373as the JWS payload. Note that the commonly used canonicalization for digest
374calculation may be dependent on the mediatype of the content, such as with
375manifests.
376
377The client may choose to ignore the header or may verify it to ensure content
378integrity and transport security. This is most important when fetching by a
379digest. To ensure security, the content should be verified against the digest
380used to fetch the content. At times, the returned digest may differ from that
381used to initiate a request. Such digests are considered to be from different
382_domains_, meaning they have different values for _algorithm_. In such a case,
383the client may choose to verify the digests in both domains or ignore the
384server's digest. To maintain security, the client _must_ always verify the
385content against the _digest_ used to fetch the content.
386
387> __IMPORTANT:__ If a _digest_ is used to fetch content, the client should use
388> the same digest used to fetch the content to verify it. The header
389> `Docker-Content-Digest` should not be trusted over the "local" digest.
390
391### Pulling An Image
392
393An "image" is a combination of a JSON manifest and individual layer files. The
394process of pulling an image centers around retrieving these two components.
395
396The first step in pulling an image is to retrieve the manifest. For reference,
397the relevant manifest fields for the registry are the following:
398
399 field | description |
400----------|------------------------------------------------|
401name | The name of the image. |
402tag | The tag for this version of the image. |
403fsLayers | A list of layer descriptors (including digest) |
404signature | A JWS used to verify the manifest content |
405
406For more information about the manifest format, please see
407[docker/docker#8093](https://github.com/docker/docker/issues/8093).
408
409When the manifest is in hand, the client must verify the signature to ensure
410the names and layers are valid. Once confirmed, the client will then use the
411digests to download the individual layers. Layers are stored in as blobs in
412the V2 registry API, keyed by their digest.
413
414#### Pulling an Image Manifest
415
416The image manifest can be fetched with the following url:
417
418```
419GET /v2/<name>/manifests/<reference>
420```
421
422The `name` and `reference` parameter identify the image and are required. The
423reference may include a tag or digest.
424
425The client should include an Accept header indicating which manifest content
426types it supports. For more details on the manifest formats and their content
427types, see [manifest-v2-1.md](manifest-v2-1.md) and
428[manifest-v2-2.md](manifest-v2-2.md). In a successful response, the Content-Type
429header will indicate which manifest type is being returned.
430
431A `404 Not Found` response will be returned if the image is unknown to the
432registry. If the image exists and the response is successful, the image
433manifest will be returned, with the following format (see
434[docker/docker#8093](https://github.com/docker/docker/issues/8093) for details):
435
436 {
437 "name": <name>,
438 "tag": <tag>,
439 "fsLayers": [
440 {
441 "blobSum": <digest>
442 },
443 ...
444 ]
445 ],
446 "history": <v1 images>,
447 "signature": <JWS>
448 }
449
450The client should verify the returned manifest signature for authenticity
451before fetching layers.
452
453##### Existing Manifests
454
455The image manifest can be checked for existence with the following url:
456
457```
458HEAD /v2/<name>/manifests/<reference>
459```
460
461The `name` and `reference` parameter identify the image and are required. The
462reference may include a tag or digest.
463
464A `404 Not Found` response will be returned if the image is unknown to the
465registry. If the image exists and the response is successful the response will
466be as follows:
467
468```
469200 OK
470Content-Length: <length of manifest>
471Docker-Content-Digest: <digest>
472```
473
474
475#### Pulling a Layer
476
477Layers are stored in the blob portion of the registry, keyed by digest.
478Pulling a layer is carried out by a standard http request. The URL is as
479follows:
480
481 GET /v2/<name>/blobs/<digest>
482
483Access to a layer will be gated by the `name` of the repository but is
484identified uniquely in the registry by `digest`.
485
486This endpoint may issue a 307 (302 for <HTTP 1.1) redirect to another service
487for downloading the layer and clients should be prepared to handle redirects.
488
489This endpoint should support aggressive HTTP caching for image layers. Support
490for Etags, modification dates and other cache control headers should be
491included. To allow for incremental downloads, `Range` requests should be
492supported, as well.
493
494### Pushing An Image
495
496Pushing an image works in the opposite order as a pull. After assembling the
497image manifest, the client must first push the individual layers. When the
498layers are fully pushed into the registry, the client should upload the signed
499manifest.
500
501The details of each step of the process are covered in the following sections.
502
503#### Pushing a Layer
504
505All layer uploads use two steps to manage the upload process. The first step
506starts the upload in the registry service, returning a url to carry out the
507second step. The second step uses the upload url to transfer the actual data.
508Uploads are started with a POST request which returns a url that can be used
509to push data and check upload status.
510
511The `Location` header will be used to communicate the upload location after
512each request. While it won't change in the this specification, clients should
513use the most recent value returned by the API.
514
515##### Starting An Upload
516
517To begin the process, a POST request should be issued in the following format:
518
519```
520POST /v2/<name>/blobs/uploads/
521```
522
523The parameters of this request are the image namespace under which the layer
524will be linked. Responses to this request are covered below.
525
526##### Existing Layers
527
528The existence of a layer can be checked via a `HEAD` request to the blob store
529API. The request should be formatted as follows:
530
531```
532HEAD /v2/<name>/blobs/<digest>
533```
534
535If the layer with the digest specified in `digest` is available, a 200 OK
536response will be received, with no actual body content (this is according to
537http specification). The response will look as follows:
538
539```
540200 OK
541Content-Length: <length of blob>
542Docker-Content-Digest: <digest>
543```
544
545When this response is received, the client can assume that the layer is
546already available in the registry under the given name and should take no
547further action to upload the layer. Note that the binary digests may differ
548for the existing registry layer, but the digests will be guaranteed to match.
549
550##### Uploading the Layer
551
552If the POST request is successful, a `202 Accepted` response will be returned
553with the upload URL in the `Location` header:
554
555```
556202 Accepted
557Location: /v2/<name>/blobs/uploads/<uuid>
558Range: bytes=0-<offset>
559Content-Length: 0
560Docker-Upload-UUID: <uuid>
561```
562
563The rest of the upload process can be carried out with the returned url,
564called the "Upload URL" from the `Location` header. All responses to the
565upload url, whether sending data or getting status, will be in this format.
566Though the URI format (`/v2/<name>/blobs/uploads/<uuid>`) for the `Location`
567header is specified, clients should treat it as an opaque url and should never
568try to assemble it. While the `uuid` parameter may be an actual UUID, this
569proposal imposes no constraints on the format and clients should never impose
570any.
571
572If clients need to correlate local upload state with remote upload state, the
573contents of the `Docker-Upload-UUID` header should be used. Such an id can be
574used to key the last used location header when implementing resumable uploads.
575
576##### Upload Progress
577
578The progress and chunk coordination of the upload process will be coordinated
579through the `Range` header. While this is a non-standard use of the `Range`
580header, there are examples of [similar approaches](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) in APIs with heavy use.
581For an upload that just started, for an example with a 1000 byte layer file,
582the `Range` header would be as follows:
583
584```
585Range: bytes=0-0
586```
587
588To get the status of an upload, issue a GET request to the upload URL:
589
590```
591GET /v2/<name>/blobs/uploads/<uuid>
592Host: <registry host>
593```
594
595The response will be similar to the above, except will return 204 status:
596
597```
598204 No Content
599Location: /v2/<name>/blobs/uploads/<uuid>
600Range: bytes=0-<offset>
601Docker-Upload-UUID: <uuid>
602```
603
604Note that the HTTP `Range` header byte ranges are inclusive and that will be
605honored, even in non-standard use cases.
606
607##### Monolithic Upload
608
609A monolithic upload is simply a chunked upload with a single chunk and may be
610favored by clients that would like to avoided the complexity of chunking. To
611carry out a "monolithic" upload, one can simply put the entire content blob to
612the provided URL:
613
614```
615PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
616Content-Length: <size of layer>
617Content-Type: application/octet-stream
618
619<Layer Binary Data>
620```
621
622The "digest" parameter must be included with the PUT request. Please see the
623[_Completed Upload_](#completed-upload) section for details on the parameters
624and expected responses.
625
626##### Chunked Upload
627
628To carry out an upload of a chunk, the client can specify a range header and
629only include that part of the layer file:
630
631```
632PATCH /v2/<name>/blobs/uploads/<uuid>
633Content-Length: <size of chunk>
634Content-Range: <start of range>-<end of range>
635Content-Type: application/octet-stream
636
637<Layer Chunk Binary Data>
638```
639
640There is no enforcement on layer chunk splits other than that the server must
641receive them in order. The server may enforce a minimum chunk size. If the
642server cannot accept the chunk, a `416 Requested Range Not Satisfiable`
643response will be returned and will include a `Range` header indicating the
644current status:
645
646```
647416 Requested Range Not Satisfiable
648Location: /v2/<name>/blobs/uploads/<uuid>
649Range: 0-<last valid range>
650Content-Length: 0
651Docker-Upload-UUID: <uuid>
652```
653
654If this response is received, the client should resume from the "last valid
655range" and upload the subsequent chunk. A 416 will be returned under the
656following conditions:
657
658- Invalid Content-Range header format
659- Out of order chunk: the range of the next chunk must start immediately after
660 the "last valid range" from the previous response.
661
662When a chunk is accepted as part of the upload, a `202 Accepted` response will
663be returned, including a `Range` header with the current upload status:
664
665```
666202 Accepted
667Location: /v2/<name>/blobs/uploads/<uuid>
668Range: bytes=0-<offset>
669Content-Length: 0
670Docker-Upload-UUID: <uuid>
671```
672
673##### Completed Upload
674
675For an upload to be considered complete, the client must submit a `PUT`
676request on the upload endpoint with a digest parameter. If it is not provided,
677the upload will not be considered complete. The format for the final chunk
678will be as follows:
679
680```
681PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
682Content-Length: <size of chunk>
683Content-Range: <start of range>-<end of range>
684Content-Type: application/octet-stream
685
686<Last Layer Chunk Binary Data>
687```
688
689Optionally, if all chunks have already been uploaded, a `PUT` request with a
690`digest` parameter and zero-length body may be sent to complete and validate
691the upload. Multiple "digest" parameters may be provided with different
692digests. The server may verify none or all of them but _must_ notify the
693client if the content is rejected.
694
695When the last chunk is received and the layer has been validated, the client
696will receive a `201 Created` response:
697
698```
699201 Created
700Location: /v2/<name>/blobs/<digest>
701Content-Length: 0
702Docker-Content-Digest: <digest>
703```
704
705The `Location` header will contain the registry URL to access the accepted
706layer file. The `Docker-Content-Digest` header returns the canonical digest of
707the uploaded blob which may differ from the provided digest. Most clients may
708ignore the value but if it is used, the client should verify the value against
709the uploaded blob data.
710
711###### Digest Parameter
712
713The "digest" parameter is designed as an opaque parameter to support
714verification of a successful transfer. For example, an HTTP URI parameter
715might be as follows:
716
717```
718sha256:6c3c624b58dbbcd3c0dd82b4c53f04194d1247c6eebdaab7c610cf7d66709b3b
719```
720
721Given this parameter, the registry will verify that the provided content does
722match this digest.
723
724##### Canceling an Upload
725
726An upload can be cancelled by issuing a DELETE request to the upload endpoint.
727The format will be as follows:
728
729```
730DELETE /v2/<name>/blobs/uploads/<uuid>
731```
732
733After this request is issued, the upload uuid will no longer be valid and the
734registry server will dump all intermediate data. While uploads will time out
735if not completed, clients should issue this request if they encounter a fatal
736error but still have the ability to issue an http request.
737
738##### Cross Repository Blob Mount
739
740A blob may be mounted from another repository that the client has read access
741to, removing the need to upload a blob already known to the registry. To issue
742a blob mount instead of an upload, a POST request should be issued in the
743following format:
744
745```
746POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repository name>
747Content-Length: 0
748```
749
750If the blob is successfully mounted, the client will receive a `201 Created`
751response:
752
753```
754201 Created
755Location: /v2/<name>/blobs/<digest>
756Content-Length: 0
757Docker-Content-Digest: <digest>
758```
759
760The `Location` header will contain the registry URL to access the accepted
761layer file. The `Docker-Content-Digest` header returns the canonical digest of
762the uploaded blob which may differ from the provided digest. Most clients may
763ignore the value but if it is used, the client should verify the value against
764the uploaded blob data.
765
766If a mount fails due to invalid repository or digest arguments, the registry
767will fall back to the standard upload behavior and return a `202 Accepted` with
768the upload URL in the `Location` header:
769
770```
771202 Accepted
772Location: /v2/<name>/blobs/uploads/<uuid>
773Range: bytes=0-<offset>
774Content-Length: 0
775Docker-Upload-UUID: <uuid>
776```
777
778This behavior is consistent with older versions of the registry, which do not
779recognize the repository mount query parameters.
780
781Note: a client may issue a HEAD request to check existence of a blob in a source
782repository to distinguish between the registry not supporting blob mounts and
783the blob not existing in the expected repository.
784
785##### Errors
786
787If an 502, 503 or 504 error is received, the client should assume that the
788download can proceed due to a temporary condition, honoring the appropriate
789retry mechanism. Other 5xx errors should be treated as terminal.
790
791If there is a problem with the upload, a 4xx error will be returned indicating
792the problem. After receiving a 4xx response (except 416, as called out above),
793the upload will be considered failed and the client should take appropriate
794action.
795
796Note that the upload url will not be available forever. If the upload uuid is
797unknown to the registry, a `404 Not Found` response will be returned and the
798client must restart the upload process.
799
800#### Deleting a Layer
801
802A layer may be deleted from the registry via its `name` and `digest`. A
803delete may be issued with the following request format:
804
805 DELETE /v2/<name>/blobs/<digest>
806
807If the blob exists and has been successfully deleted, the following response
808will be issued:
809
810 202 Accepted
811 Content-Length: None
812
813If the blob had already been deleted or did not exist, a `404 Not Found`
814response will be issued instead.
815
816If a layer is deleted which is referenced by a manifest in the registry,
817then the complete images will not be resolvable.
818
819#### Pushing an Image Manifest
820
821Once all of the layers for an image are uploaded, the client can upload the
822image manifest. An image can be pushed using the following request format:
823
824 PUT /v2/<name>/manifests/<reference>
825 Content-Type: <manifest media type>
826
827 {
828 "name": <name>,
829 "tag": <tag>,
830 "fsLayers": [
831 {
832 "blobSum": <digest>
833 },
834 ...
835 ]
836 ],
837 "history": <v1 images>,
838 "signature": <JWS>,
839 ...
840 }
841
842The `name` and `reference` fields of the response body must match those
843specified in the URL. The `reference` field may be a "tag" or a "digest". The
844content type should match the type of the manifest being uploaded, as specified
845in [manifest-v2-1.md](manifest-v2-1.md) and [manifest-v2-2.md](manifest-v2-2.md).
846
847If there is a problem with pushing the manifest, a relevant 4xx response will
848be returned with a JSON error message. Please see the
849[_PUT Manifest_](#put-manifest) section for details on possible error codes that
850may be returned.
851
852If one or more layers are unknown to the registry, `BLOB_UNKNOWN` errors are
853returned. The `detail` field of the error response will have a `digest` field
854identifying the missing blob. An error is returned for each unknown blob. The
855response format is as follows:
856
857 {
858 "errors:" [{
859 "code": "BLOB_UNKNOWN",
860 "message": "blob unknown to registry",
861 "detail": {
862 "digest": <digest>
863 }
864 },
865 ...
866 ]
867 }
868
869### Listing Repositories
870
871Images are stored in collections, known as a _repository_, which is keyed by a
872`name`, as seen throughout the API specification. A registry instance may
873contain several repositories. The list of available repositories is made
874available through the _catalog_.
875
876The catalog for a given registry can be retrieved with the following request:
877
878```
879GET /v2/_catalog
880```
881
882The response will be in the following format:
883
884```
885200 OK
886Content-Type: application/json
887
888{
889 "repositories": [
890 <name>,
891 ...
892 ]
893}
894```
895
896Note that the contents of the response are specific to the registry
897implementation. Some registries may opt to provide a full catalog output,
898limit it based on the user's access level or omit upstream results, if
899providing mirroring functionality. Subsequently, the presence of a repository
900in the catalog listing only means that the registry *may* provide access to
901the repository at the time of the request. Conversely, a missing entry does
902*not* mean that the registry does not have the repository. More succinctly,
903the presence of a repository only guarantees that it is there but not that it
904is _not_ there.
905
906For registries with a large number of repositories, this response may be quite
907large. If such a response is expected, one should use pagination. A registry
908may also limit the amount of responses returned even if pagination was not
909explicitly requested. In this case the `Link` header will be returned along
910with the results, and subsequent results can be obtained by following the link
911as if pagination had been initially requested.
912
913For details of the `Link` header, please see the [_Pagination_](#pagination)
914section.
915
916#### Pagination
917
918Paginated catalog results can be retrieved by adding an `n` parameter to the
919request URL, declaring that the response should be limited to `n` results.
920Starting a paginated flow begins as follows:
921
922```
923GET /v2/_catalog?n=<integer>
924```
925
926The above specifies that a catalog response should be returned, from the start of
927the result set, ordered lexically, limiting the number of results to `n`. The
928response to such a request would look as follows:
929
930```
931200 OK
932Content-Type: application/json
933Link: <<url>?n=<n from the request>&last=<last repository in response>>; rel="next"
934
935{
936 "repositories": [
937 <name>,
938 ...
939 ]
940}
941```
942
943The above includes the _first_ `n` entries from the result set. To get the
944_next_ `n` entries, one can create a URL where the argument `last` has the
945value from `repositories[len(repositories)-1]`. If there are indeed more
946results, the URL for the next block is encoded in an
947[RFC5988](https://tools.ietf.org/html/rfc5988) `Link` header, as a "next"
948relation. The presence of the `Link` header communicates to the client that
949the entire result set has not been returned and another request must be
950issued. If the header is not present, the client can assume that all results
951have been received.
952
953> __NOTE:__ In the request template above, note that the brackets
954> are required. For example, if the url is
955> `http://example.com/v2/_catalog?n=20&last=b`, the value of the header would
956> be `<http://example.com/v2/_catalog?n=20&last=b>; rel="next"`. Please see
957> [RFC5988](https://tools.ietf.org/html/rfc5988) for details.
958
959Compliant client implementations should always use the `Link` header
960value when proceeding through results linearly. The client may construct URLs
961to skip forward in the catalog.
962
963To get the next result set, a client would issue the request as follows, using
964the URL encoded in the described `Link` header:
965
966```
967GET /v2/_catalog?n=<n from the request>&last=<last repository value from previous response>
968```
969
970The above process should then be repeated until the `Link` header is no longer
971set.
972
973The catalog result set is represented abstractly as a lexically sorted list,
974where the position in that list can be specified by the query term `last`. The
975entries in the response start _after_ the term specified by `last`, up to `n`
976entries.
977
978The behavior of `last` is quite simple when demonstrated with an example. Let
979us say the registry has the following repositories:
980
981```
982a
983b
984c
985d
986```
987
988If the value of `n` is 2, _a_ and _b_ will be returned on the first response.
989The `Link` header returned on the response will have `n` set to 2 and last set
990to _b_:
991
992```
993Link: <<url>?n=2&last=b>; rel="next"
994```
995
996The client can then issue the request with the above value from the `Link`
997header, receiving the values _c_ and _d_. Note that `n` may change on the second
998to last response or be fully omitted, depending on the server implementation.
999
1000### Listing Image Tags
1001
1002It may be necessary to list all of the tags under a given repository. The tags
1003for an image repository can be retrieved with the following request:
1004
1005 GET /v2/<name>/tags/list
1006
1007The response will be in the following format:
1008
1009 200 OK
1010 Content-Type: application/json
1011
1012 {
1013 "name": <name>,
1014 "tags": [
1015 <tag>,
1016 ...
1017 ]
1018 }
1019
1020For repositories with a large number of tags, this response may be quite
1021large. If such a response is expected, one should use the pagination.
1022
1023#### Pagination
1024
1025Paginated tag results can be retrieved by adding the appropriate parameters to
1026the request URL described above. The behavior of tag pagination is identical
1027to that specified for catalog pagination. We cover a simple flow to highlight
1028any differences.
1029
1030Starting a paginated flow may begin as follows:
1031
1032```
1033GET /v2/<name>/tags/list?n=<integer>
1034```
1035
1036The above specifies that a tags response should be returned, from the start of
1037the result set, ordered lexically, limiting the number of results to `n`. The
1038response to such a request would look as follows:
1039
1040```
1041200 OK
1042Content-Type: application/json
1043Link: <<url>?n=<n from the request>&last=<last tag value from previous response>>; rel="next"
1044
1045{
1046 "name": <name>,
1047 "tags": [
1048 <tag>,
1049 ...
1050 ]
1051}
1052```
1053
1054To get the next result set, a client would issue the request as follows, using
1055the value encoded in the [RFC5988](https://tools.ietf.org/html/rfc5988) `Link`
1056header:
1057
1058```
1059GET /v2/<name>/tags/list?n=<n from the request>&last=<last tag value from previous response>
1060```
1061
1062The above process should then be repeated until the `Link` header is no longer
1063set in the response. The behavior of the `last` parameter, the provided
1064response result, lexical ordering and encoding of the `Link` header are
1065identical to that of catalog pagination.
1066
1067### Deleting an Image
1068
1069An image may be deleted from the registry via its `name` and `reference`. A
1070delete may be issued with the following request format:
1071
1072 DELETE /v2/<name>/manifests/<reference>
1073
1074For deletes, `reference` *must* be a digest or the delete will fail. If the
1075image exists and has been successfully deleted, the following response will be
1076issued:
1077
1078 202 Accepted
1079 Content-Length: None
1080
1081If the image had already been deleted or did not exist, a `404 Not Found`
1082response will be issued instead.
1083
1084> **Note** When deleting a manifest from a registry version 2.3 or later, the
1085> following header must be used when `HEAD` or `GET`-ing the manifest to obtain
1086> the correct digest to delete:
1087
1088 Accept: application/vnd.docker.distribution.manifest.v2+json
1089
1090> for more details, see: [compatibility.md](../compatibility.md#content-addressable-storage-cas)
1091
1092## Detail
1093
1094> **Note**: This section is still under construction. For the purposes of
1095> implementation, if any details below differ from the described request flows
1096> above, the section below should be corrected. When they match, this note
1097> should be removed.
1098
1099The behavior of the endpoints are covered in detail in this section, organized
1100by route and entity. All aspects of the request and responses are covered,
1101including headers, parameters and body formats. Examples of requests and their
1102corresponding responses, with success and failure, are enumerated.
1103
1104> **Note**: The sections on endpoint detail are arranged with an example
1105> request, a description of the request, followed by information about that
1106> request.
1107
1108A list of methods and URIs are covered in the table below:
1109
1110|Method|Path|Entity|Description|
1111|------|----|------|-----------|
1112| GET | `/v2/` | Base | Check that the endpoint implements Docker Registry API V2. |
1113| GET | `/v2/<name>/tags/list` | Tags | Fetch the tags under the repository identified by `name`. |
1114| 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. |
1115| PUT | `/v2/<name>/manifests/<reference>` | Manifest | Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest. |
1116| DELETE | `/v2/<name>/manifests/<reference>` | Manifest | Delete the manifest identified by `name` and `reference`. Note that a manifest can _only_ be deleted by `digest`. |
1117| 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. |
1118| DELETE | `/v2/<name>/blobs/<digest>` | Blob | Delete the blob identified by `name` and `digest` |
1119| 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. |
1120| 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. |
1121| PATCH | `/v2/<name>/blobs/uploads/<uuid>` | Blob Upload | Upload a chunk of data for the specified upload. |
1122| PUT | `/v2/<name>/blobs/uploads/<uuid>` | Blob Upload | Complete the upload specified by `uuid`, optionally appending the body as the final chunk. |
1123| 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. |
1124| GET | `/v2/_catalog` | Catalog | Retrieve a sorted, json list of repositories available in the registry. |
1125
1126
1127The detail for each endpoint is covered in the following sections.
1128
1129### Errors
1130
1131The error codes encountered via the API are enumerated in the following table:
1132
1133|Code|Message|Description|
1134|----|-------|-----------|
1135 `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.
1136 `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed.
1137 `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.
1138 `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.
1139 `MANIFEST_BLOB_UNKNOWN` | blob unknown to registry | This error may be returned when a manifest blob is unknown to the registry.
1140 `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.
1141 `MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository.
1142 `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned.
1143 `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation.
1144 `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry.
1145 `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.
1146 `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.
1147 `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.
1148 `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource.
1149 `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters.
1150
1151
1152
1153### Base
1154
1155Base V2 API route. Typically, this can be used for lightweight version checks and to validate registry authentication.
1156
1157
1158
1159#### GET Base
1160
1161Check that the endpoint implements Docker Registry API V2.
1162
1163
1164
1165```
1166GET /v2/
1167Host: <registry host>
1168Authorization: <scheme> <token>
1169```
1170
1171
1172
1173
1174The following parameters should be specified on the request:
1175
1176|Name|Kind|Description|
1177|----|----|-----------|
1178|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
1179|`Authorization`|header|An RFC7235 compliant authorization header.|
1180
1181
1182
1183
1184###### On Success: OK
1185
1186```
1187200 OK
1188```
1189
1190The API implements V2 protocol and is accessible.
1191
1192
1193
1194
1195###### On Failure: Not Found
1196
1197```
1198404 Not Found
1199```
1200
1201The registry does not implement the V2 API.
1202
1203
1204
1205###### On Failure: Authentication Required
1206
1207```
1208401 Unauthorized
1209WWW-Authenticate: <scheme> realm="<realm>", ..."
1210Content-Length: <length>
1211Content-Type: application/json; charset=utf-8
1212
1213{
1214 "errors:" [
1215 {
1216 "code": <error code>,
1217 "message": "<error message>",
1218 "detail": ...
1219 },
1220 ...
1221 ]
1222}
1223```
1224
1225The client is not authenticated.
1226
1227The following headers will be returned on the response:
1228
1229|Name|Description|
1230|----|-----------|
1231|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
1232|`Content-Length`|Length of the JSON response body.|
1233
1234
1235
1236The error codes that may be included in the response body are enumerated below:
1237
1238|Code|Message|Description|
1239|----|-------|-----------|
1240| `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. |
1241
1242
1243
1244###### On Failure: Too Many Requests
1245
1246```
1247429 Too Many Requests
1248Content-Length: <length>
1249Content-Type: application/json; charset=utf-8
1250
1251{
1252 "errors:" [
1253 {
1254 "code": <error code>,
1255 "message": "<error message>",
1256 "detail": ...
1257 },
1258 ...
1259 ]
1260}
1261```
1262
1263The client made too many requests within a time interval.
1264
1265The following headers will be returned on the response:
1266
1267|Name|Description|
1268|----|-----------|
1269|`Content-Length`|Length of the JSON response body.|
1270
1271
1272
1273The error codes that may be included in the response body are enumerated below:
1274
1275|Code|Message|Description|
1276|----|-------|-----------|
1277| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
1278
1279
1280
1281
1282
1283### Tags
1284
1285Retrieve information about tags.
1286
1287
1288
1289#### GET Tags
1290
1291Fetch the tags under the repository identified by `name`.
1292
1293
1294##### Tags
1295
1296```
1297GET /v2/<name>/tags/list
1298Host: <registry host>
1299Authorization: <scheme> <token>
1300```
1301
1302Return all tags for the repository
1303
1304
1305The following parameters should be specified on the request:
1306
1307|Name|Kind|Description|
1308|----|----|-----------|
1309|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
1310|`Authorization`|header|An RFC7235 compliant authorization header.|
1311|`name`|path|Name of the target repository.|
1312
1313
1314
1315
1316###### On Success: OK
1317
1318```
1319200 OK
1320Content-Length: <length>
1321Content-Type: application/json; charset=utf-8
1322
1323{
1324 "name": <name>,
1325 "tags": [
1326 <tag>,
1327 ...
1328 ]
1329}
1330```
1331
1332A list of tags for the named repository.
1333
1334The following headers will be returned with the response:
1335
1336|Name|Description|
1337|----|-----------|
1338|`Content-Length`|Length of the JSON response body.|
1339
1340
1341
1342
1343###### On Failure: Authentication Required
1344
1345```
1346401 Unauthorized
1347WWW-Authenticate: <scheme> realm="<realm>", ..."
1348Content-Length: <length>
1349Content-Type: application/json; charset=utf-8
1350
1351{
1352 "errors:" [
1353 {
1354 "code": <error code>,
1355 "message": "<error message>",
1356 "detail": ...
1357 },
1358 ...
1359 ]
1360}
1361```
1362
1363The client is not authenticated.
1364
1365The following headers will be returned on the response:
1366
1367|Name|Description|
1368|----|-----------|
1369|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
1370|`Content-Length`|Length of the JSON response body.|
1371
1372
1373
1374The error codes that may be included in the response body are enumerated below:
1375
1376|Code|Message|Description|
1377|----|-------|-----------|
1378| `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. |
1379
1380
1381
1382###### On Failure: No Such Repository Error
1383
1384```
1385404 Not Found
1386Content-Length: <length>
1387Content-Type: application/json; charset=utf-8
1388
1389{
1390 "errors:" [
1391 {
1392 "code": <error code>,
1393 "message": "<error message>",
1394 "detail": ...
1395 },
1396 ...
1397 ]
1398}
1399```
1400
1401The repository is not known to the registry.
1402
1403The following headers will be returned on the response:
1404
1405|Name|Description|
1406|----|-----------|
1407|`Content-Length`|Length of the JSON response body.|
1408
1409
1410
1411The error codes that may be included in the response body are enumerated below:
1412
1413|Code|Message|Description|
1414|----|-------|-----------|
1415| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
1416
1417
1418
1419###### On Failure: Access Denied
1420
1421```
1422403 Forbidden
1423Content-Length: <length>
1424Content-Type: application/json; charset=utf-8
1425
1426{
1427 "errors:" [
1428 {
1429 "code": <error code>,
1430 "message": "<error message>",
1431 "detail": ...
1432 },
1433 ...
1434 ]
1435}
1436```
1437
1438The client does not have required access to the repository.
1439
1440The following headers will be returned on the response:
1441
1442|Name|Description|
1443|----|-----------|
1444|`Content-Length`|Length of the JSON response body.|
1445
1446
1447
1448The error codes that may be included in the response body are enumerated below:
1449
1450|Code|Message|Description|
1451|----|-------|-----------|
1452| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
1453
1454
1455
1456###### On Failure: Too Many Requests
1457
1458```
1459429 Too Many Requests
1460Content-Length: <length>
1461Content-Type: application/json; charset=utf-8
1462
1463{
1464 "errors:" [
1465 {
1466 "code": <error code>,
1467 "message": "<error message>",
1468 "detail": ...
1469 },
1470 ...
1471 ]
1472}
1473```
1474
1475The client made too many requests within a time interval.
1476
1477The following headers will be returned on the response:
1478
1479|Name|Description|
1480|----|-----------|
1481|`Content-Length`|Length of the JSON response body.|
1482
1483
1484
1485The error codes that may be included in the response body are enumerated below:
1486
1487|Code|Message|Description|
1488|----|-------|-----------|
1489| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
1490
1491
1492
1493##### Tags Paginated
1494
1495```
1496GET /v2/<name>/tags/list?n=<integer>&last=<integer>
1497```
1498
1499Return a portion of the tags for the specified repository.
1500
1501
1502The following parameters should be specified on the request:
1503
1504|Name|Kind|Description|
1505|----|----|-----------|
1506|`name`|path|Name of the target repository.|
1507|`n`|query|Limit the number of entries in each response. It not present, all entries will be returned.|
1508|`last`|query|Result set will include values lexically after last.|
1509
1510
1511
1512
1513###### On Success: OK
1514
1515```
1516200 OK
1517Content-Length: <length>
1518Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
1519Content-Type: application/json; charset=utf-8
1520
1521{
1522 "name": <name>,
1523 "tags": [
1524 <tag>,
1525 ...
1526 ],
1527}
1528```
1529
1530A list of tags for the named repository.
1531
1532The following headers will be returned with the response:
1533
1534|Name|Description|
1535|----|-----------|
1536|`Content-Length`|Length of the JSON response body.|
1537|`Link`|RFC5988 compliant rel='next' with URL to next result set, if available|
1538
1539
1540
1541
1542###### On Failure: Authentication Required
1543
1544```
1545401 Unauthorized
1546WWW-Authenticate: <scheme> realm="<realm>", ..."
1547Content-Length: <length>
1548Content-Type: application/json; charset=utf-8
1549
1550{
1551 "errors:" [
1552 {
1553 "code": <error code>,
1554 "message": "<error message>",
1555 "detail": ...
1556 },
1557 ...
1558 ]
1559}
1560```
1561
1562The client is not authenticated.
1563
1564The following headers will be returned on the response:
1565
1566|Name|Description|
1567|----|-----------|
1568|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
1569|`Content-Length`|Length of the JSON response body.|
1570
1571
1572
1573The error codes that may be included in the response body are enumerated below:
1574
1575|Code|Message|Description|
1576|----|-------|-----------|
1577| `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. |
1578
1579
1580
1581###### On Failure: No Such Repository Error
1582
1583```
1584404 Not Found
1585Content-Length: <length>
1586Content-Type: application/json; charset=utf-8
1587
1588{
1589 "errors:" [
1590 {
1591 "code": <error code>,
1592 "message": "<error message>",
1593 "detail": ...
1594 },
1595 ...
1596 ]
1597}
1598```
1599
1600The repository is not known to the registry.
1601
1602The following headers will be returned on the response:
1603
1604|Name|Description|
1605|----|-----------|
1606|`Content-Length`|Length of the JSON response body.|
1607
1608
1609
1610The error codes that may be included in the response body are enumerated below:
1611
1612|Code|Message|Description|
1613|----|-------|-----------|
1614| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
1615
1616
1617
1618###### On Failure: Access Denied
1619
1620```
1621403 Forbidden
1622Content-Length: <length>
1623Content-Type: application/json; charset=utf-8
1624
1625{
1626 "errors:" [
1627 {
1628 "code": <error code>,
1629 "message": "<error message>",
1630 "detail": ...
1631 },
1632 ...
1633 ]
1634}
1635```
1636
1637The client does not have required access to the repository.
1638
1639The following headers will be returned on the response:
1640
1641|Name|Description|
1642|----|-----------|
1643|`Content-Length`|Length of the JSON response body.|
1644
1645
1646
1647The error codes that may be included in the response body are enumerated below:
1648
1649|Code|Message|Description|
1650|----|-------|-----------|
1651| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
1652
1653
1654
1655###### On Failure: Too Many Requests
1656
1657```
1658429 Too Many Requests
1659Content-Length: <length>
1660Content-Type: application/json; charset=utf-8
1661
1662{
1663 "errors:" [
1664 {
1665 "code": <error code>,
1666 "message": "<error message>",
1667 "detail": ...
1668 },
1669 ...
1670 ]
1671}
1672```
1673
1674The client made too many requests within a time interval.
1675
1676The following headers will be returned on the response:
1677
1678|Name|Description|
1679|----|-----------|
1680|`Content-Length`|Length of the JSON response body.|
1681
1682
1683
1684The error codes that may be included in the response body are enumerated below:
1685
1686|Code|Message|Description|
1687|----|-------|-----------|
1688| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
1689
1690
1691
1692
1693
1694### Manifest
1695
1696Create, update, delete and retrieve manifests.
1697
1698
1699
1700#### GET Manifest
1701
1702Fetch 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.
1703
1704
1705
1706```
1707GET /v2/<name>/manifests/<reference>
1708Host: <registry host>
1709Authorization: <scheme> <token>
1710```
1711
1712
1713
1714
1715The following parameters should be specified on the request:
1716
1717|Name|Kind|Description|
1718|----|----|-----------|
1719|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
1720|`Authorization`|header|An RFC7235 compliant authorization header.|
1721|`name`|path|Name of the target repository.|
1722|`reference`|path|Tag or digest of the target manifest.|
1723
1724
1725
1726
1727###### On Success: OK
1728
1729```
1730200 OK
1731Docker-Content-Digest: <digest>
1732Content-Type: <media type of manifest>
1733
1734{
1735 "name": <name>,
1736 "tag": <tag>,
1737 "fsLayers": [
1738 {
1739 "blobSum": "<digest>"
1740 },
1741 ...
1742 ]
1743 ],
1744 "history": <v1 images>,
1745 "signature": <JWS>
1746}
1747```
1748
1749The manifest identified by `name` and `reference`. The contents can be used to identify and resolve resources required to run the specified image.
1750
1751The following headers will be returned with the response:
1752
1753|Name|Description|
1754|----|-----------|
1755|`Docker-Content-Digest`|Digest of the targeted content for the request.|
1756
1757
1758
1759
1760###### On Failure: Bad Request
1761
1762```
1763400 Bad Request
1764Content-Type: application/json; charset=utf-8
1765
1766{
1767 "errors:" [
1768 {
1769 "code": <error code>,
1770 "message": "<error message>",
1771 "detail": ...
1772 },
1773 ...
1774 ]
1775}
1776```
1777
1778The name or reference was invalid.
1779
1780
1781
1782The error codes that may be included in the response body are enumerated below:
1783
1784|Code|Message|Description|
1785|----|-------|-----------|
1786| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
1787| `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. |
1788
1789
1790
1791###### On Failure: Authentication Required
1792
1793```
1794401 Unauthorized
1795WWW-Authenticate: <scheme> realm="<realm>", ..."
1796Content-Length: <length>
1797Content-Type: application/json; charset=utf-8
1798
1799{
1800 "errors:" [
1801 {
1802 "code": <error code>,
1803 "message": "<error message>",
1804 "detail": ...
1805 },
1806 ...
1807 ]
1808}
1809```
1810
1811The client is not authenticated.
1812
1813The following headers will be returned on the response:
1814
1815|Name|Description|
1816|----|-----------|
1817|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
1818|`Content-Length`|Length of the JSON response body.|
1819
1820
1821
1822The error codes that may be included in the response body are enumerated below:
1823
1824|Code|Message|Description|
1825|----|-------|-----------|
1826| `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. |
1827
1828
1829
1830###### On Failure: No Such Repository Error
1831
1832```
1833404 Not Found
1834Content-Length: <length>
1835Content-Type: application/json; charset=utf-8
1836
1837{
1838 "errors:" [
1839 {
1840 "code": <error code>,
1841 "message": "<error message>",
1842 "detail": ...
1843 },
1844 ...
1845 ]
1846}
1847```
1848
1849The repository is not known to the registry.
1850
1851The following headers will be returned on the response:
1852
1853|Name|Description|
1854|----|-----------|
1855|`Content-Length`|Length of the JSON response body.|
1856
1857
1858
1859The error codes that may be included in the response body are enumerated below:
1860
1861|Code|Message|Description|
1862|----|-------|-----------|
1863| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
1864
1865
1866
1867###### On Failure: Access Denied
1868
1869```
1870403 Forbidden
1871Content-Length: <length>
1872Content-Type: application/json; charset=utf-8
1873
1874{
1875 "errors:" [
1876 {
1877 "code": <error code>,
1878 "message": "<error message>",
1879 "detail": ...
1880 },
1881 ...
1882 ]
1883}
1884```
1885
1886The client does not have required access to the repository.
1887
1888The following headers will be returned on the response:
1889
1890|Name|Description|
1891|----|-----------|
1892|`Content-Length`|Length of the JSON response body.|
1893
1894
1895
1896The error codes that may be included in the response body are enumerated below:
1897
1898|Code|Message|Description|
1899|----|-------|-----------|
1900| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
1901
1902
1903
1904###### On Failure: Too Many Requests
1905
1906```
1907429 Too Many Requests
1908Content-Length: <length>
1909Content-Type: application/json; charset=utf-8
1910
1911{
1912 "errors:" [
1913 {
1914 "code": <error code>,
1915 "message": "<error message>",
1916 "detail": ...
1917 },
1918 ...
1919 ]
1920}
1921```
1922
1923The client made too many requests within a time interval.
1924
1925The following headers will be returned on the response:
1926
1927|Name|Description|
1928|----|-----------|
1929|`Content-Length`|Length of the JSON response body.|
1930
1931
1932
1933The error codes that may be included in the response body are enumerated below:
1934
1935|Code|Message|Description|
1936|----|-------|-----------|
1937| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
1938
1939
1940
1941
1942#### PUT Manifest
1943
1944Put the manifest identified by `name` and `reference` where `reference` can be a tag or digest.
1945
1946
1947
1948```
1949PUT /v2/<name>/manifests/<reference>
1950Host: <registry host>
1951Authorization: <scheme> <token>
1952Content-Type: <media type of manifest>
1953
1954{
1955 "name": <name>,
1956 "tag": <tag>,
1957 "fsLayers": [
1958 {
1959 "blobSum": "<digest>"
1960 },
1961 ...
1962 ]
1963 ],
1964 "history": <v1 images>,
1965 "signature": <JWS>
1966}
1967```
1968
1969
1970
1971
1972The following parameters should be specified on the request:
1973
1974|Name|Kind|Description|
1975|----|----|-----------|
1976|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
1977|`Authorization`|header|An RFC7235 compliant authorization header.|
1978|`name`|path|Name of the target repository.|
1979|`reference`|path|Tag or digest of the target manifest.|
1980
1981
1982
1983
1984###### On Success: Created
1985
1986```
1987201 Created
1988Location: <url>
1989Content-Length: 0
1990Docker-Content-Digest: <digest>
1991```
1992
1993The manifest has been accepted by the registry and is stored under the specified `name` and `tag`.
1994
1995The following headers will be returned with the response:
1996
1997|Name|Description|
1998|----|-----------|
1999|`Location`|The canonical location url of the uploaded manifest.|
2000|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
2001|`Docker-Content-Digest`|Digest of the targeted content for the request.|
2002
2003
2004
2005
2006###### On Failure: Invalid Manifest
2007
2008```
2009400 Bad Request
2010Content-Type: application/json; charset=utf-8
2011
2012{
2013 "errors:" [
2014 {
2015 "code": <error code>,
2016 "message": "<error message>",
2017 "detail": ...
2018 },
2019 ...
2020 ]
2021}
2022```
2023
2024The received manifest was invalid in some way, as described by the error codes. The client should resolve the issue and retry the request.
2025
2026
2027
2028The error codes that may be included in the response body are enumerated below:
2029
2030|Code|Message|Description|
2031|----|-------|-----------|
2032| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
2033| `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. |
2034| `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. |
2035| `MANIFEST_UNVERIFIED` | manifest failed signature verification | During manifest upload, if the manifest fails signature verification, this error will be returned. |
2036| `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. |
2037
2038
2039
2040###### On Failure: Authentication Required
2041
2042```
2043401 Unauthorized
2044WWW-Authenticate: <scheme> realm="<realm>", ..."
2045Content-Length: <length>
2046Content-Type: application/json; charset=utf-8
2047
2048{
2049 "errors:" [
2050 {
2051 "code": <error code>,
2052 "message": "<error message>",
2053 "detail": ...
2054 },
2055 ...
2056 ]
2057}
2058```
2059
2060The client is not authenticated.
2061
2062The following headers will be returned on the response:
2063
2064|Name|Description|
2065|----|-----------|
2066|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
2067|`Content-Length`|Length of the JSON response body.|
2068
2069
2070
2071The error codes that may be included in the response body are enumerated below:
2072
2073|Code|Message|Description|
2074|----|-------|-----------|
2075| `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. |
2076
2077
2078
2079###### On Failure: No Such Repository Error
2080
2081```
2082404 Not Found
2083Content-Length: <length>
2084Content-Type: application/json; charset=utf-8
2085
2086{
2087 "errors:" [
2088 {
2089 "code": <error code>,
2090 "message": "<error message>",
2091 "detail": ...
2092 },
2093 ...
2094 ]
2095}
2096```
2097
2098The repository is not known to the registry.
2099
2100The following headers will be returned on the response:
2101
2102|Name|Description|
2103|----|-----------|
2104|`Content-Length`|Length of the JSON response body.|
2105
2106
2107
2108The error codes that may be included in the response body are enumerated below:
2109
2110|Code|Message|Description|
2111|----|-------|-----------|
2112| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2113
2114
2115
2116###### On Failure: Access Denied
2117
2118```
2119403 Forbidden
2120Content-Length: <length>
2121Content-Type: application/json; charset=utf-8
2122
2123{
2124 "errors:" [
2125 {
2126 "code": <error code>,
2127 "message": "<error message>",
2128 "detail": ...
2129 },
2130 ...
2131 ]
2132}
2133```
2134
2135The client does not have required access to the repository.
2136
2137The following headers will be returned on the response:
2138
2139|Name|Description|
2140|----|-----------|
2141|`Content-Length`|Length of the JSON response body.|
2142
2143
2144
2145The error codes that may be included in the response body are enumerated below:
2146
2147|Code|Message|Description|
2148|----|-------|-----------|
2149| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
2150
2151
2152
2153###### On Failure: Too Many Requests
2154
2155```
2156429 Too Many Requests
2157Content-Length: <length>
2158Content-Type: application/json; charset=utf-8
2159
2160{
2161 "errors:" [
2162 {
2163 "code": <error code>,
2164 "message": "<error message>",
2165 "detail": ...
2166 },
2167 ...
2168 ]
2169}
2170```
2171
2172The client made too many requests within a time interval.
2173
2174The following headers will be returned on the response:
2175
2176|Name|Description|
2177|----|-----------|
2178|`Content-Length`|Length of the JSON response body.|
2179
2180
2181
2182The error codes that may be included in the response body are enumerated below:
2183
2184|Code|Message|Description|
2185|----|-------|-----------|
2186| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
2187
2188
2189
2190###### On Failure: Missing Layer(s)
2191
2192```
2193400 Bad Request
2194Content-Type: application/json; charset=utf-8
2195
2196{
2197 "errors:" [{
2198 "code": "BLOB_UNKNOWN",
2199 "message": "blob unknown to registry",
2200 "detail": {
2201 "digest": "<digest>"
2202 }
2203 },
2204 ...
2205 ]
2206}
2207```
2208
2209One or more layers may be missing during a manifest upload. If so, the missing layers will be enumerated in the error response.
2210
2211
2212
2213The error codes that may be included in the response body are enumerated below:
2214
2215|Code|Message|Description|
2216|----|-------|-----------|
2217| `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. |
2218
2219
2220
2221###### On Failure: Not allowed
2222
2223```
2224405 Method Not Allowed
2225```
2226
2227Manifest put is not allowed because the registry is configured as a pull-through cache or for some other reason
2228
2229
2230
2231The error codes that may be included in the response body are enumerated below:
2232
2233|Code|Message|Description|
2234|----|-------|-----------|
2235| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
2236
2237
2238
2239
2240#### DELETE Manifest
2241
2242Delete the manifest identified by `name` and `reference`. Note that a manifest can _only_ be deleted by `digest`.
2243
2244
2245
2246```
2247DELETE /v2/<name>/manifests/<reference>
2248Host: <registry host>
2249Authorization: <scheme> <token>
2250```
2251
2252
2253
2254
2255The following parameters should be specified on the request:
2256
2257|Name|Kind|Description|
2258|----|----|-----------|
2259|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
2260|`Authorization`|header|An RFC7235 compliant authorization header.|
2261|`name`|path|Name of the target repository.|
2262|`reference`|path|Tag or digest of the target manifest.|
2263
2264
2265
2266
2267###### On Success: Accepted
2268
2269```
2270202 Accepted
2271```
2272
2273
2274
2275
2276
2277
2278###### On Failure: Invalid Name or Reference
2279
2280```
2281400 Bad Request
2282Content-Type: application/json; charset=utf-8
2283
2284{
2285 "errors:" [
2286 {
2287 "code": <error code>,
2288 "message": "<error message>",
2289 "detail": ...
2290 },
2291 ...
2292 ]
2293}
2294```
2295
2296The specified `name` or `reference` were invalid and the delete was unable to proceed.
2297
2298
2299
2300The error codes that may be included in the response body are enumerated below:
2301
2302|Code|Message|Description|
2303|----|-------|-----------|
2304| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
2305| `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. |
2306
2307
2308
2309###### On Failure: Authentication Required
2310
2311```
2312401 Unauthorized
2313WWW-Authenticate: <scheme> realm="<realm>", ..."
2314Content-Length: <length>
2315Content-Type: application/json; charset=utf-8
2316
2317{
2318 "errors:" [
2319 {
2320 "code": <error code>,
2321 "message": "<error message>",
2322 "detail": ...
2323 },
2324 ...
2325 ]
2326}
2327```
2328
2329The client is not authenticated.
2330
2331The following headers will be returned on the response:
2332
2333|Name|Description|
2334|----|-----------|
2335|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
2336|`Content-Length`|Length of the JSON response body.|
2337
2338
2339
2340The error codes that may be included in the response body are enumerated below:
2341
2342|Code|Message|Description|
2343|----|-------|-----------|
2344| `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. |
2345
2346
2347
2348###### On Failure: No Such Repository Error
2349
2350```
2351404 Not Found
2352Content-Length: <length>
2353Content-Type: application/json; charset=utf-8
2354
2355{
2356 "errors:" [
2357 {
2358 "code": <error code>,
2359 "message": "<error message>",
2360 "detail": ...
2361 },
2362 ...
2363 ]
2364}
2365```
2366
2367The repository is not known to the registry.
2368
2369The following headers will be returned on the response:
2370
2371|Name|Description|
2372|----|-----------|
2373|`Content-Length`|Length of the JSON response body.|
2374
2375
2376
2377The error codes that may be included in the response body are enumerated below:
2378
2379|Code|Message|Description|
2380|----|-------|-----------|
2381| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2382
2383
2384
2385###### On Failure: Access Denied
2386
2387```
2388403 Forbidden
2389Content-Length: <length>
2390Content-Type: application/json; charset=utf-8
2391
2392{
2393 "errors:" [
2394 {
2395 "code": <error code>,
2396 "message": "<error message>",
2397 "detail": ...
2398 },
2399 ...
2400 ]
2401}
2402```
2403
2404The client does not have required access to the repository.
2405
2406The following headers will be returned on the response:
2407
2408|Name|Description|
2409|----|-----------|
2410|`Content-Length`|Length of the JSON response body.|
2411
2412
2413
2414The error codes that may be included in the response body are enumerated below:
2415
2416|Code|Message|Description|
2417|----|-------|-----------|
2418| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
2419
2420
2421
2422###### On Failure: Too Many Requests
2423
2424```
2425429 Too Many Requests
2426Content-Length: <length>
2427Content-Type: application/json; charset=utf-8
2428
2429{
2430 "errors:" [
2431 {
2432 "code": <error code>,
2433 "message": "<error message>",
2434 "detail": ...
2435 },
2436 ...
2437 ]
2438}
2439```
2440
2441The client made too many requests within a time interval.
2442
2443The following headers will be returned on the response:
2444
2445|Name|Description|
2446|----|-----------|
2447|`Content-Length`|Length of the JSON response body.|
2448
2449
2450
2451The error codes that may be included in the response body are enumerated below:
2452
2453|Code|Message|Description|
2454|----|-------|-----------|
2455| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
2456
2457
2458
2459###### On Failure: Unknown Manifest
2460
2461```
2462404 Not Found
2463Content-Type: application/json; charset=utf-8
2464
2465{
2466 "errors:" [
2467 {
2468 "code": <error code>,
2469 "message": "<error message>",
2470 "detail": ...
2471 },
2472 ...
2473 ]
2474}
2475```
2476
2477The 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.
2478
2479
2480
2481The error codes that may be included in the response body are enumerated below:
2482
2483|Code|Message|Description|
2484|----|-------|-----------|
2485| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2486| `MANIFEST_UNKNOWN` | manifest unknown | This error is returned when the manifest, identified by name and tag is unknown to the repository. |
2487
2488
2489
2490###### On Failure: Not allowed
2491
2492```
2493405 Method Not Allowed
2494```
2495
2496Manifest delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled.
2497
2498
2499
2500The error codes that may be included in the response body are enumerated below:
2501
2502|Code|Message|Description|
2503|----|-------|-----------|
2504| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
2505
2506
2507
2508
2509
2510### Blob
2511
2512Operations on blobs identified by `name` and `digest`. Used to fetch or delete layers by digest.
2513
2514
2515
2516#### GET Blob
2517
2518Retrieve 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.
2519
2520
2521##### Fetch Blob
2522
2523```
2524GET /v2/<name>/blobs/<digest>
2525Host: <registry host>
2526Authorization: <scheme> <token>
2527```
2528
2529
2530
2531
2532The following parameters should be specified on the request:
2533
2534|Name|Kind|Description|
2535|----|----|-----------|
2536|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
2537|`Authorization`|header|An RFC7235 compliant authorization header.|
2538|`name`|path|Name of the target repository.|
2539|`digest`|path|Digest of desired blob.|
2540
2541
2542
2543
2544###### On Success: OK
2545
2546```
2547200 OK
2548Content-Length: <length>
2549Docker-Content-Digest: <digest>
2550Content-Type: application/octet-stream
2551
2552<blob binary data>
2553```
2554
2555The blob identified by `digest` is available. The blob content will be present in the body of the request.
2556
2557The following headers will be returned with the response:
2558
2559|Name|Description|
2560|----|-----------|
2561|`Content-Length`|The length of the requested blob content.|
2562|`Docker-Content-Digest`|Digest of the targeted content for the request.|
2563
2564###### On Success: Temporary Redirect
2565
2566```
2567307 Temporary Redirect
2568Location: <blob location>
2569Docker-Content-Digest: <digest>
2570```
2571
2572The blob identified by `digest` is available at the provided location.
2573
2574The following headers will be returned with the response:
2575
2576|Name|Description|
2577|----|-----------|
2578|`Location`|The location where the layer should be accessible.|
2579|`Docker-Content-Digest`|Digest of the targeted content for the request.|
2580
2581
2582
2583
2584###### On Failure: Bad Request
2585
2586```
2587400 Bad Request
2588Content-Type: application/json; charset=utf-8
2589
2590{
2591 "errors:" [
2592 {
2593 "code": <error code>,
2594 "message": "<error message>",
2595 "detail": ...
2596 },
2597 ...
2598 ]
2599}
2600```
2601
2602There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.
2603
2604
2605
2606The error codes that may be included in the response body are enumerated below:
2607
2608|Code|Message|Description|
2609|----|-------|-----------|
2610| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
2611| `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. |
2612
2613
2614
2615###### On Failure: Not Found
2616
2617```
2618404 Not Found
2619Content-Type: application/json; charset=utf-8
2620
2621{
2622 "errors:" [
2623 {
2624 "code": <error code>,
2625 "message": "<error message>",
2626 "detail": ...
2627 },
2628 ...
2629 ]
2630}
2631```
2632
2633The blob, identified by `name` and `digest`, is unknown to the registry.
2634
2635
2636
2637The error codes that may be included in the response body are enumerated below:
2638
2639|Code|Message|Description|
2640|----|-------|-----------|
2641| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2642| `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. |
2643
2644
2645
2646###### On Failure: Authentication Required
2647
2648```
2649401 Unauthorized
2650WWW-Authenticate: <scheme> realm="<realm>", ..."
2651Content-Length: <length>
2652Content-Type: application/json; charset=utf-8
2653
2654{
2655 "errors:" [
2656 {
2657 "code": <error code>,
2658 "message": "<error message>",
2659 "detail": ...
2660 },
2661 ...
2662 ]
2663}
2664```
2665
2666The client is not authenticated.
2667
2668The following headers will be returned on the response:
2669
2670|Name|Description|
2671|----|-----------|
2672|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
2673|`Content-Length`|Length of the JSON response body.|
2674
2675
2676
2677The error codes that may be included in the response body are enumerated below:
2678
2679|Code|Message|Description|
2680|----|-------|-----------|
2681| `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. |
2682
2683
2684
2685###### On Failure: No Such Repository Error
2686
2687```
2688404 Not Found
2689Content-Length: <length>
2690Content-Type: application/json; charset=utf-8
2691
2692{
2693 "errors:" [
2694 {
2695 "code": <error code>,
2696 "message": "<error message>",
2697 "detail": ...
2698 },
2699 ...
2700 ]
2701}
2702```
2703
2704The repository is not known to the registry.
2705
2706The following headers will be returned on the response:
2707
2708|Name|Description|
2709|----|-----------|
2710|`Content-Length`|Length of the JSON response body.|
2711
2712
2713
2714The error codes that may be included in the response body are enumerated below:
2715
2716|Code|Message|Description|
2717|----|-------|-----------|
2718| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2719
2720
2721
2722###### On Failure: Access Denied
2723
2724```
2725403 Forbidden
2726Content-Length: <length>
2727Content-Type: application/json; charset=utf-8
2728
2729{
2730 "errors:" [
2731 {
2732 "code": <error code>,
2733 "message": "<error message>",
2734 "detail": ...
2735 },
2736 ...
2737 ]
2738}
2739```
2740
2741The client does not have required access to the repository.
2742
2743The following headers will be returned on the response:
2744
2745|Name|Description|
2746|----|-----------|
2747|`Content-Length`|Length of the JSON response body.|
2748
2749
2750
2751The error codes that may be included in the response body are enumerated below:
2752
2753|Code|Message|Description|
2754|----|-------|-----------|
2755| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
2756
2757
2758
2759###### On Failure: Too Many Requests
2760
2761```
2762429 Too Many Requests
2763Content-Length: <length>
2764Content-Type: application/json; charset=utf-8
2765
2766{
2767 "errors:" [
2768 {
2769 "code": <error code>,
2770 "message": "<error message>",
2771 "detail": ...
2772 },
2773 ...
2774 ]
2775}
2776```
2777
2778The client made too many requests within a time interval.
2779
2780The following headers will be returned on the response:
2781
2782|Name|Description|
2783|----|-----------|
2784|`Content-Length`|Length of the JSON response body.|
2785
2786
2787
2788The error codes that may be included in the response body are enumerated below:
2789
2790|Code|Message|Description|
2791|----|-------|-----------|
2792| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
2793
2794
2795
2796##### Fetch Blob Part
2797
2798```
2799GET /v2/<name>/blobs/<digest>
2800Host: <registry host>
2801Authorization: <scheme> <token>
2802Range: bytes=<start>-<end>
2803```
2804
2805This 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.
2806
2807
2808The following parameters should be specified on the request:
2809
2810|Name|Kind|Description|
2811|----|----|-----------|
2812|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
2813|`Authorization`|header|An RFC7235 compliant authorization header.|
2814|`Range`|header|HTTP Range header specifying blob chunk.|
2815|`name`|path|Name of the target repository.|
2816|`digest`|path|Digest of desired blob.|
2817
2818
2819
2820
2821###### On Success: Partial Content
2822
2823```
2824206 Partial Content
2825Content-Length: <length>
2826Content-Range: bytes <start>-<end>/<size>
2827Content-Type: application/octet-stream
2828
2829<blob binary data>
2830```
2831
2832The blob identified by `digest` is available. The specified chunk of blob content will be present in the body of the request.
2833
2834The following headers will be returned with the response:
2835
2836|Name|Description|
2837|----|-----------|
2838|`Content-Length`|The length of the requested blob chunk.|
2839|`Content-Range`|Content range of blob chunk.|
2840
2841
2842
2843
2844###### On Failure: Bad Request
2845
2846```
2847400 Bad Request
2848Content-Type: application/json; charset=utf-8
2849
2850{
2851 "errors:" [
2852 {
2853 "code": <error code>,
2854 "message": "<error message>",
2855 "detail": ...
2856 },
2857 ...
2858 ]
2859}
2860```
2861
2862There was a problem with the request that needs to be addressed by the client, such as an invalid `name` or `tag`.
2863
2864
2865
2866The error codes that may be included in the response body are enumerated below:
2867
2868|Code|Message|Description|
2869|----|-------|-----------|
2870| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
2871| `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. |
2872
2873
2874
2875###### On Failure: Not Found
2876
2877```
2878404 Not Found
2879Content-Type: application/json; charset=utf-8
2880
2881{
2882 "errors:" [
2883 {
2884 "code": <error code>,
2885 "message": "<error message>",
2886 "detail": ...
2887 },
2888 ...
2889 ]
2890}
2891```
2892
2893
2894
2895
2896
2897The error codes that may be included in the response body are enumerated below:
2898
2899|Code|Message|Description|
2900|----|-------|-----------|
2901| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2902| `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. |
2903
2904
2905
2906###### On Failure: Requested Range Not Satisfiable
2907
2908```
2909416 Requested Range Not Satisfiable
2910```
2911
2912The 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.
2913
2914
2915
2916###### On Failure: Authentication Required
2917
2918```
2919401 Unauthorized
2920WWW-Authenticate: <scheme> realm="<realm>", ..."
2921Content-Length: <length>
2922Content-Type: application/json; charset=utf-8
2923
2924{
2925 "errors:" [
2926 {
2927 "code": <error code>,
2928 "message": "<error message>",
2929 "detail": ...
2930 },
2931 ...
2932 ]
2933}
2934```
2935
2936The client is not authenticated.
2937
2938The following headers will be returned on the response:
2939
2940|Name|Description|
2941|----|-----------|
2942|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
2943|`Content-Length`|Length of the JSON response body.|
2944
2945
2946
2947The error codes that may be included in the response body are enumerated below:
2948
2949|Code|Message|Description|
2950|----|-------|-----------|
2951| `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. |
2952
2953
2954
2955###### On Failure: No Such Repository Error
2956
2957```
2958404 Not Found
2959Content-Length: <length>
2960Content-Type: application/json; charset=utf-8
2961
2962{
2963 "errors:" [
2964 {
2965 "code": <error code>,
2966 "message": "<error message>",
2967 "detail": ...
2968 },
2969 ...
2970 ]
2971}
2972```
2973
2974The repository is not known to the registry.
2975
2976The following headers will be returned on the response:
2977
2978|Name|Description|
2979|----|-----------|
2980|`Content-Length`|Length of the JSON response body.|
2981
2982
2983
2984The error codes that may be included in the response body are enumerated below:
2985
2986|Code|Message|Description|
2987|----|-------|-----------|
2988| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
2989
2990
2991
2992###### On Failure: Access Denied
2993
2994```
2995403 Forbidden
2996Content-Length: <length>
2997Content-Type: application/json; charset=utf-8
2998
2999{
3000 "errors:" [
3001 {
3002 "code": <error code>,
3003 "message": "<error message>",
3004 "detail": ...
3005 },
3006 ...
3007 ]
3008}
3009```
3010
3011The client does not have required access to the repository.
3012
3013The following headers will be returned on the response:
3014
3015|Name|Description|
3016|----|-----------|
3017|`Content-Length`|Length of the JSON response body.|
3018
3019
3020
3021The error codes that may be included in the response body are enumerated below:
3022
3023|Code|Message|Description|
3024|----|-------|-----------|
3025| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
3026
3027
3028
3029###### On Failure: Too Many Requests
3030
3031```
3032429 Too Many Requests
3033Content-Length: <length>
3034Content-Type: application/json; charset=utf-8
3035
3036{
3037 "errors:" [
3038 {
3039 "code": <error code>,
3040 "message": "<error message>",
3041 "detail": ...
3042 },
3043 ...
3044 ]
3045}
3046```
3047
3048The client made too many requests within a time interval.
3049
3050The following headers will be returned on the response:
3051
3052|Name|Description|
3053|----|-----------|
3054|`Content-Length`|Length of the JSON response body.|
3055
3056
3057
3058The error codes that may be included in the response body are enumerated below:
3059
3060|Code|Message|Description|
3061|----|-------|-----------|
3062| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
3063
3064
3065
3066
3067#### DELETE Blob
3068
3069Delete the blob identified by `name` and `digest`
3070
3071
3072
3073```
3074DELETE /v2/<name>/blobs/<digest>
3075Host: <registry host>
3076Authorization: <scheme> <token>
3077```
3078
3079
3080
3081
3082The following parameters should be specified on the request:
3083
3084|Name|Kind|Description|
3085|----|----|-----------|
3086|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
3087|`Authorization`|header|An RFC7235 compliant authorization header.|
3088|`name`|path|Name of the target repository.|
3089|`digest`|path|Digest of desired blob.|
3090
3091
3092
3093
3094###### On Success: Accepted
3095
3096```
3097202 Accepted
3098Content-Length: 0
3099Docker-Content-Digest: <digest>
3100```
3101
3102
3103
3104The following headers will be returned with the response:
3105
3106|Name|Description|
3107|----|-----------|
3108|`Content-Length`|0|
3109|`Docker-Content-Digest`|Digest of the targeted content for the request.|
3110
3111
3112
3113
3114###### On Failure: Invalid Name or Digest
3115
3116```
3117400 Bad Request
3118```
3119
3120
3121
3122
3123
3124The error codes that may be included in the response body are enumerated below:
3125
3126|Code|Message|Description|
3127|----|-------|-----------|
3128| `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. |
3129| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
3130
3131
3132
3133###### On Failure: Not Found
3134
3135```
3136404 Not Found
3137Content-Type: application/json; charset=utf-8
3138
3139{
3140 "errors:" [
3141 {
3142 "code": <error code>,
3143 "message": "<error message>",
3144 "detail": ...
3145 },
3146 ...
3147 ]
3148}
3149```
3150
3151The blob, identified by `name` and `digest`, is unknown to the registry.
3152
3153
3154
3155The error codes that may be included in the response body are enumerated below:
3156
3157|Code|Message|Description|
3158|----|-------|-----------|
3159| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
3160| `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. |
3161
3162
3163
3164###### On Failure: Method Not Allowed
3165
3166```
3167405 Method Not Allowed
3168Content-Type: application/json; charset=utf-8
3169
3170{
3171 "errors:" [
3172 {
3173 "code": <error code>,
3174 "message": "<error message>",
3175 "detail": ...
3176 },
3177 ...
3178 ]
3179}
3180```
3181
3182Blob delete is not allowed because the registry is configured as a pull-through cache or `delete` has been disabled
3183
3184
3185
3186The error codes that may be included in the response body are enumerated below:
3187
3188|Code|Message|Description|
3189|----|-------|-----------|
3190| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
3191
3192
3193
3194###### On Failure: Authentication Required
3195
3196```
3197401 Unauthorized
3198WWW-Authenticate: <scheme> realm="<realm>", ..."
3199Content-Length: <length>
3200Content-Type: application/json; charset=utf-8
3201
3202{
3203 "errors:" [
3204 {
3205 "code": <error code>,
3206 "message": "<error message>",
3207 "detail": ...
3208 },
3209 ...
3210 ]
3211}
3212```
3213
3214The client is not authenticated.
3215
3216The following headers will be returned on the response:
3217
3218|Name|Description|
3219|----|-----------|
3220|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
3221|`Content-Length`|Length of the JSON response body.|
3222
3223
3224
3225The error codes that may be included in the response body are enumerated below:
3226
3227|Code|Message|Description|
3228|----|-------|-----------|
3229| `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. |
3230
3231
3232
3233###### On Failure: No Such Repository Error
3234
3235```
3236404 Not Found
3237Content-Length: <length>
3238Content-Type: application/json; charset=utf-8
3239
3240{
3241 "errors:" [
3242 {
3243 "code": <error code>,
3244 "message": "<error message>",
3245 "detail": ...
3246 },
3247 ...
3248 ]
3249}
3250```
3251
3252The repository is not known to the registry.
3253
3254The following headers will be returned on the response:
3255
3256|Name|Description|
3257|----|-----------|
3258|`Content-Length`|Length of the JSON response body.|
3259
3260
3261
3262The error codes that may be included in the response body are enumerated below:
3263
3264|Code|Message|Description|
3265|----|-------|-----------|
3266| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
3267
3268
3269
3270###### On Failure: Access Denied
3271
3272```
3273403 Forbidden
3274Content-Length: <length>
3275Content-Type: application/json; charset=utf-8
3276
3277{
3278 "errors:" [
3279 {
3280 "code": <error code>,
3281 "message": "<error message>",
3282 "detail": ...
3283 },
3284 ...
3285 ]
3286}
3287```
3288
3289The client does not have required access to the repository.
3290
3291The following headers will be returned on the response:
3292
3293|Name|Description|
3294|----|-----------|
3295|`Content-Length`|Length of the JSON response body.|
3296
3297
3298
3299The error codes that may be included in the response body are enumerated below:
3300
3301|Code|Message|Description|
3302|----|-------|-----------|
3303| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
3304
3305
3306
3307###### On Failure: Too Many Requests
3308
3309```
3310429 Too Many Requests
3311Content-Length: <length>
3312Content-Type: application/json; charset=utf-8
3313
3314{
3315 "errors:" [
3316 {
3317 "code": <error code>,
3318 "message": "<error message>",
3319 "detail": ...
3320 },
3321 ...
3322 ]
3323}
3324```
3325
3326The client made too many requests within a time interval.
3327
3328The following headers will be returned on the response:
3329
3330|Name|Description|
3331|----|-----------|
3332|`Content-Length`|Length of the JSON response body.|
3333
3334
3335
3336The error codes that may be included in the response body are enumerated below:
3337
3338|Code|Message|Description|
3339|----|-------|-----------|
3340| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
3341
3342
3343
3344
3345
3346### Initiate Blob Upload
3347
3348Initiate a blob upload. This endpoint can be used to create resumable uploads or monolithic uploads.
3349
3350
3351
3352#### POST Initiate Blob Upload
3353
3354Initiate 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.
3355
3356
3357##### Initiate Monolithic Blob Upload
3358
3359```
3360POST /v2/<name>/blobs/uploads/?digest=<digest>
3361Host: <registry host>
3362Authorization: <scheme> <token>
3363Content-Length: <length of blob>
3364Content-Type: application/octect-stream
3365
3366<binary data>
3367```
3368
3369Upload a blob identified by the `digest` parameter in single request. This upload will not be resumable unless a recoverable error is returned.
3370
3371
3372The following parameters should be specified on the request:
3373
3374|Name|Kind|Description|
3375|----|----|-----------|
3376|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
3377|`Authorization`|header|An RFC7235 compliant authorization header.|
3378|`Content-Length`|header||
3379|`name`|path|Name of the target repository.|
3380|`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.|
3381
3382
3383
3384
3385###### On Success: Created
3386
3387```
3388201 Created
3389Location: <blob location>
3390Content-Length: 0
3391Docker-Upload-UUID: <uuid>
3392```
3393
3394The blob has been created in the registry and is available at the provided location.
3395
3396The following headers will be returned with the response:
3397
3398|Name|Description|
3399|----|-----------|
3400|`Location`||
3401|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
3402|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
3403
3404
3405
3406
3407###### On Failure: Invalid Name or Digest
3408
3409```
3410400 Bad Request
3411```
3412
3413
3414
3415
3416
3417The error codes that may be included in the response body are enumerated below:
3418
3419|Code|Message|Description|
3420|----|-------|-----------|
3421| `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. |
3422| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
3423
3424
3425
3426###### On Failure: Not allowed
3427
3428```
3429405 Method Not Allowed
3430```
3431
3432Blob upload is not allowed because the registry is configured as a pull-through cache or for some other reason
3433
3434
3435
3436The error codes that may be included in the response body are enumerated below:
3437
3438|Code|Message|Description|
3439|----|-------|-----------|
3440| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
3441
3442
3443
3444###### On Failure: Authentication Required
3445
3446```
3447401 Unauthorized
3448WWW-Authenticate: <scheme> realm="<realm>", ..."
3449Content-Length: <length>
3450Content-Type: application/json; charset=utf-8
3451
3452{
3453 "errors:" [
3454 {
3455 "code": <error code>,
3456 "message": "<error message>",
3457 "detail": ...
3458 },
3459 ...
3460 ]
3461}
3462```
3463
3464The client is not authenticated.
3465
3466The following headers will be returned on the response:
3467
3468|Name|Description|
3469|----|-----------|
3470|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
3471|`Content-Length`|Length of the JSON response body.|
3472
3473
3474
3475The error codes that may be included in the response body are enumerated below:
3476
3477|Code|Message|Description|
3478|----|-------|-----------|
3479| `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. |
3480
3481
3482
3483###### On Failure: No Such Repository Error
3484
3485```
3486404 Not Found
3487Content-Length: <length>
3488Content-Type: application/json; charset=utf-8
3489
3490{
3491 "errors:" [
3492 {
3493 "code": <error code>,
3494 "message": "<error message>",
3495 "detail": ...
3496 },
3497 ...
3498 ]
3499}
3500```
3501
3502The repository is not known to the registry.
3503
3504The following headers will be returned on the response:
3505
3506|Name|Description|
3507|----|-----------|
3508|`Content-Length`|Length of the JSON response body.|
3509
3510
3511
3512The error codes that may be included in the response body are enumerated below:
3513
3514|Code|Message|Description|
3515|----|-------|-----------|
3516| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
3517
3518
3519
3520###### On Failure: Access Denied
3521
3522```
3523403 Forbidden
3524Content-Length: <length>
3525Content-Type: application/json; charset=utf-8
3526
3527{
3528 "errors:" [
3529 {
3530 "code": <error code>,
3531 "message": "<error message>",
3532 "detail": ...
3533 },
3534 ...
3535 ]
3536}
3537```
3538
3539The client does not have required access to the repository.
3540
3541The following headers will be returned on the response:
3542
3543|Name|Description|
3544|----|-----------|
3545|`Content-Length`|Length of the JSON response body.|
3546
3547
3548
3549The error codes that may be included in the response body are enumerated below:
3550
3551|Code|Message|Description|
3552|----|-------|-----------|
3553| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
3554
3555
3556
3557###### On Failure: Too Many Requests
3558
3559```
3560429 Too Many Requests
3561Content-Length: <length>
3562Content-Type: application/json; charset=utf-8
3563
3564{
3565 "errors:" [
3566 {
3567 "code": <error code>,
3568 "message": "<error message>",
3569 "detail": ...
3570 },
3571 ...
3572 ]
3573}
3574```
3575
3576The client made too many requests within a time interval.
3577
3578The following headers will be returned on the response:
3579
3580|Name|Description|
3581|----|-----------|
3582|`Content-Length`|Length of the JSON response body.|
3583
3584
3585
3586The error codes that may be included in the response body are enumerated below:
3587
3588|Code|Message|Description|
3589|----|-------|-----------|
3590| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
3591
3592
3593
3594##### Initiate Resumable Blob Upload
3595
3596```
3597POST /v2/<name>/blobs/uploads/
3598Host: <registry host>
3599Authorization: <scheme> <token>
3600Content-Length: 0
3601```
3602
3603Initiate a resumable blob upload with an empty request body.
3604
3605
3606The following parameters should be specified on the request:
3607
3608|Name|Kind|Description|
3609|----|----|-----------|
3610|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
3611|`Authorization`|header|An RFC7235 compliant authorization header.|
3612|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
3613|`name`|path|Name of the target repository.|
3614
3615
3616
3617
3618###### On Success: Accepted
3619
3620```
3621202 Accepted
3622Content-Length: 0
3623Location: /v2/<name>/blobs/uploads/<uuid>
3624Range: 0-0
3625Docker-Upload-UUID: <uuid>
3626```
3627
3628The 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.
3629
3630The following headers will be returned with the response:
3631
3632|Name|Description|
3633|----|-----------|
3634|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
3635|`Location`|The location of the created upload. Clients should use the contents verbatim to complete the upload, adding parameters where required.|
3636|`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.|
3637|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
3638
3639
3640
3641
3642###### On Failure: Invalid Name or Digest
3643
3644```
3645400 Bad Request
3646```
3647
3648
3649
3650
3651
3652The error codes that may be included in the response body are enumerated below:
3653
3654|Code|Message|Description|
3655|----|-------|-----------|
3656| `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. |
3657| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
3658
3659
3660
3661###### On Failure: Authentication Required
3662
3663```
3664401 Unauthorized
3665WWW-Authenticate: <scheme> realm="<realm>", ..."
3666Content-Length: <length>
3667Content-Type: application/json; charset=utf-8
3668
3669{
3670 "errors:" [
3671 {
3672 "code": <error code>,
3673 "message": "<error message>",
3674 "detail": ...
3675 },
3676 ...
3677 ]
3678}
3679```
3680
3681The client is not authenticated.
3682
3683The following headers will be returned on the response:
3684
3685|Name|Description|
3686|----|-----------|
3687|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
3688|`Content-Length`|Length of the JSON response body.|
3689
3690
3691
3692The error codes that may be included in the response body are enumerated below:
3693
3694|Code|Message|Description|
3695|----|-------|-----------|
3696| `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. |
3697
3698
3699
3700###### On Failure: No Such Repository Error
3701
3702```
3703404 Not Found
3704Content-Length: <length>
3705Content-Type: application/json; charset=utf-8
3706
3707{
3708 "errors:" [
3709 {
3710 "code": <error code>,
3711 "message": "<error message>",
3712 "detail": ...
3713 },
3714 ...
3715 ]
3716}
3717```
3718
3719The repository is not known to the registry.
3720
3721The following headers will be returned on the response:
3722
3723|Name|Description|
3724|----|-----------|
3725|`Content-Length`|Length of the JSON response body.|
3726
3727
3728
3729The error codes that may be included in the response body are enumerated below:
3730
3731|Code|Message|Description|
3732|----|-------|-----------|
3733| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
3734
3735
3736
3737###### On Failure: Access Denied
3738
3739```
3740403 Forbidden
3741Content-Length: <length>
3742Content-Type: application/json; charset=utf-8
3743
3744{
3745 "errors:" [
3746 {
3747 "code": <error code>,
3748 "message": "<error message>",
3749 "detail": ...
3750 },
3751 ...
3752 ]
3753}
3754```
3755
3756The client does not have required access to the repository.
3757
3758The following headers will be returned on the response:
3759
3760|Name|Description|
3761|----|-----------|
3762|`Content-Length`|Length of the JSON response body.|
3763
3764
3765
3766The error codes that may be included in the response body are enumerated below:
3767
3768|Code|Message|Description|
3769|----|-------|-----------|
3770| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
3771
3772
3773
3774###### On Failure: Too Many Requests
3775
3776```
3777429 Too Many Requests
3778Content-Length: <length>
3779Content-Type: application/json; charset=utf-8
3780
3781{
3782 "errors:" [
3783 {
3784 "code": <error code>,
3785 "message": "<error message>",
3786 "detail": ...
3787 },
3788 ...
3789 ]
3790}
3791```
3792
3793The client made too many requests within a time interval.
3794
3795The following headers will be returned on the response:
3796
3797|Name|Description|
3798|----|-----------|
3799|`Content-Length`|Length of the JSON response body.|
3800
3801
3802
3803The error codes that may be included in the response body are enumerated below:
3804
3805|Code|Message|Description|
3806|----|-------|-----------|
3807| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
3808
3809
3810
3811##### Mount Blob
3812
3813```
3814POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repository name>
3815Host: <registry host>
3816Authorization: <scheme> <token>
3817Content-Length: 0
3818```
3819
3820Mount a blob identified by the `mount` parameter from another repository.
3821
3822
3823The following parameters should be specified on the request:
3824
3825|Name|Kind|Description|
3826|----|----|-----------|
3827|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
3828|`Authorization`|header|An RFC7235 compliant authorization header.|
3829|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
3830|`name`|path|Name of the target repository.|
3831|`mount`|query|Digest of blob to mount from the source repository.|
3832|`from`|query|Name of the source repository.|
3833
3834
3835
3836
3837###### On Success: Created
3838
3839```
3840201 Created
3841Location: <blob location>
3842Content-Length: 0
3843Docker-Upload-UUID: <uuid>
3844```
3845
3846The blob has been mounted in the repository and is available at the provided location.
3847
3848The following headers will be returned with the response:
3849
3850|Name|Description|
3851|----|-----------|
3852|`Location`||
3853|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
3854|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
3855
3856
3857
3858
3859###### On Failure: Invalid Name or Digest
3860
3861```
3862400 Bad Request
3863```
3864
3865
3866
3867
3868
3869The error codes that may be included in the response body are enumerated below:
3870
3871|Code|Message|Description|
3872|----|-------|-----------|
3873| `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. |
3874| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
3875
3876
3877
3878###### On Failure: Not allowed
3879
3880```
3881405 Method Not Allowed
3882```
3883
3884Blob mount is not allowed because the registry is configured as a pull-through cache or for some other reason
3885
3886
3887
3888The error codes that may be included in the response body are enumerated below:
3889
3890|Code|Message|Description|
3891|----|-------|-----------|
3892| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
3893
3894
3895
3896###### On Failure: Authentication Required
3897
3898```
3899401 Unauthorized
3900WWW-Authenticate: <scheme> realm="<realm>", ..."
3901Content-Length: <length>
3902Content-Type: application/json; charset=utf-8
3903
3904{
3905 "errors:" [
3906 {
3907 "code": <error code>,
3908 "message": "<error message>",
3909 "detail": ...
3910 },
3911 ...
3912 ]
3913}
3914```
3915
3916The client is not authenticated.
3917
3918The following headers will be returned on the response:
3919
3920|Name|Description|
3921|----|-----------|
3922|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
3923|`Content-Length`|Length of the JSON response body.|
3924
3925
3926
3927The error codes that may be included in the response body are enumerated below:
3928
3929|Code|Message|Description|
3930|----|-------|-----------|
3931| `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. |
3932
3933
3934
3935###### On Failure: No Such Repository Error
3936
3937```
3938404 Not Found
3939Content-Length: <length>
3940Content-Type: application/json; charset=utf-8
3941
3942{
3943 "errors:" [
3944 {
3945 "code": <error code>,
3946 "message": "<error message>",
3947 "detail": ...
3948 },
3949 ...
3950 ]
3951}
3952```
3953
3954The repository is not known to the registry.
3955
3956The following headers will be returned on the response:
3957
3958|Name|Description|
3959|----|-----------|
3960|`Content-Length`|Length of the JSON response body.|
3961
3962
3963
3964The error codes that may be included in the response body are enumerated below:
3965
3966|Code|Message|Description|
3967|----|-------|-----------|
3968| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
3969
3970
3971
3972###### On Failure: Access Denied
3973
3974```
3975403 Forbidden
3976Content-Length: <length>
3977Content-Type: application/json; charset=utf-8
3978
3979{
3980 "errors:" [
3981 {
3982 "code": <error code>,
3983 "message": "<error message>",
3984 "detail": ...
3985 },
3986 ...
3987 ]
3988}
3989```
3990
3991The client does not have required access to the repository.
3992
3993The following headers will be returned on the response:
3994
3995|Name|Description|
3996|----|-----------|
3997|`Content-Length`|Length of the JSON response body.|
3998
3999
4000
4001The error codes that may be included in the response body are enumerated below:
4002
4003|Code|Message|Description|
4004|----|-------|-----------|
4005| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
4006
4007
4008
4009###### On Failure: Too Many Requests
4010
4011```
4012429 Too Many Requests
4013Content-Length: <length>
4014Content-Type: application/json; charset=utf-8
4015
4016{
4017 "errors:" [
4018 {
4019 "code": <error code>,
4020 "message": "<error message>",
4021 "detail": ...
4022 },
4023 ...
4024 ]
4025}
4026```
4027
4028The client made too many requests within a time interval.
4029
4030The following headers will be returned on the response:
4031
4032|Name|Description|
4033|----|-----------|
4034|`Content-Length`|Length of the JSON response body.|
4035
4036
4037
4038The error codes that may be included in the response body are enumerated below:
4039
4040|Code|Message|Description|
4041|----|-------|-----------|
4042| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
4043
4044
4045
4046
4047
4048### Blob Upload
4049
4050Interact 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.
4051
4052
4053
4054#### GET Blob Upload
4055
4056Retrieve status of upload identified by `uuid`. The primary purpose of this endpoint is to resolve the current status of a resumable upload.
4057
4058
4059
4060```
4061GET /v2/<name>/blobs/uploads/<uuid>
4062Host: <registry host>
4063Authorization: <scheme> <token>
4064```
4065
4066Retrieve the progress of the current upload, as reported by the `Range` header.
4067
4068
4069The following parameters should be specified on the request:
4070
4071|Name|Kind|Description|
4072|----|----|-----------|
4073|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
4074|`Authorization`|header|An RFC7235 compliant authorization header.|
4075|`name`|path|Name of the target repository.|
4076|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
4077
4078
4079
4080
4081###### On Success: Upload Progress
4082
4083```
4084204 No Content
4085Range: 0-<offset>
4086Content-Length: 0
4087Docker-Upload-UUID: <uuid>
4088```
4089
4090The upload is known and in progress. The last received offset is available in the `Range` header.
4091
4092The following headers will be returned with the response:
4093
4094|Name|Description|
4095|----|-----------|
4096|`Range`|Range indicating the current progress of the upload.|
4097|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
4098|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
4099
4100
4101
4102
4103###### On Failure: Bad Request
4104
4105```
4106400 Bad Request
4107Content-Type: application/json; charset=utf-8
4108
4109{
4110 "errors:" [
4111 {
4112 "code": <error code>,
4113 "message": "<error message>",
4114 "detail": ...
4115 },
4116 ...
4117 ]
4118}
4119```
4120
4121There was an error processing the upload and it must be restarted.
4122
4123
4124
4125The error codes that may be included in the response body are enumerated below:
4126
4127|Code|Message|Description|
4128|----|-------|-----------|
4129| `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. |
4130| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
4131| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
4132
4133
4134
4135###### On Failure: Not Found
4136
4137```
4138404 Not Found
4139Content-Type: application/json; charset=utf-8
4140
4141{
4142 "errors:" [
4143 {
4144 "code": <error code>,
4145 "message": "<error message>",
4146 "detail": ...
4147 },
4148 ...
4149 ]
4150}
4151```
4152
4153The upload is unknown to the registry. The upload must be restarted.
4154
4155
4156
4157The error codes that may be included in the response body are enumerated below:
4158
4159|Code|Message|Description|
4160|----|-------|-----------|
4161| `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. |
4162
4163
4164
4165###### On Failure: Authentication Required
4166
4167```
4168401 Unauthorized
4169WWW-Authenticate: <scheme> realm="<realm>", ..."
4170Content-Length: <length>
4171Content-Type: application/json; charset=utf-8
4172
4173{
4174 "errors:" [
4175 {
4176 "code": <error code>,
4177 "message": "<error message>",
4178 "detail": ...
4179 },
4180 ...
4181 ]
4182}
4183```
4184
4185The client is not authenticated.
4186
4187The following headers will be returned on the response:
4188
4189|Name|Description|
4190|----|-----------|
4191|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
4192|`Content-Length`|Length of the JSON response body.|
4193
4194
4195
4196The error codes that may be included in the response body are enumerated below:
4197
4198|Code|Message|Description|
4199|----|-------|-----------|
4200| `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. |
4201
4202
4203
4204###### On Failure: No Such Repository Error
4205
4206```
4207404 Not Found
4208Content-Length: <length>
4209Content-Type: application/json; charset=utf-8
4210
4211{
4212 "errors:" [
4213 {
4214 "code": <error code>,
4215 "message": "<error message>",
4216 "detail": ...
4217 },
4218 ...
4219 ]
4220}
4221```
4222
4223The repository is not known to the registry.
4224
4225The following headers will be returned on the response:
4226
4227|Name|Description|
4228|----|-----------|
4229|`Content-Length`|Length of the JSON response body.|
4230
4231
4232
4233The error codes that may be included in the response body are enumerated below:
4234
4235|Code|Message|Description|
4236|----|-------|-----------|
4237| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
4238
4239
4240
4241###### On Failure: Access Denied
4242
4243```
4244403 Forbidden
4245Content-Length: <length>
4246Content-Type: application/json; charset=utf-8
4247
4248{
4249 "errors:" [
4250 {
4251 "code": <error code>,
4252 "message": "<error message>",
4253 "detail": ...
4254 },
4255 ...
4256 ]
4257}
4258```
4259
4260The client does not have required access to the repository.
4261
4262The following headers will be returned on the response:
4263
4264|Name|Description|
4265|----|-----------|
4266|`Content-Length`|Length of the JSON response body.|
4267
4268
4269
4270The error codes that may be included in the response body are enumerated below:
4271
4272|Code|Message|Description|
4273|----|-------|-----------|
4274| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
4275
4276
4277
4278###### On Failure: Too Many Requests
4279
4280```
4281429 Too Many Requests
4282Content-Length: <length>
4283Content-Type: application/json; charset=utf-8
4284
4285{
4286 "errors:" [
4287 {
4288 "code": <error code>,
4289 "message": "<error message>",
4290 "detail": ...
4291 },
4292 ...
4293 ]
4294}
4295```
4296
4297The client made too many requests within a time interval.
4298
4299The following headers will be returned on the response:
4300
4301|Name|Description|
4302|----|-----------|
4303|`Content-Length`|Length of the JSON response body.|
4304
4305
4306
4307The error codes that may be included in the response body are enumerated below:
4308
4309|Code|Message|Description|
4310|----|-------|-----------|
4311| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
4312
4313
4314
4315
4316#### PATCH Blob Upload
4317
4318Upload a chunk of data for the specified upload.
4319
4320
4321##### Stream upload
4322
4323```
4324PATCH /v2/<name>/blobs/uploads/<uuid>
4325Host: <registry host>
4326Authorization: <scheme> <token>
4327Content-Type: application/octet-stream
4328
4329<binary data>
4330```
4331
4332Upload a stream of data to upload without completing the upload.
4333
4334
4335The following parameters should be specified on the request:
4336
4337|Name|Kind|Description|
4338|----|----|-----------|
4339|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
4340|`Authorization`|header|An RFC7235 compliant authorization header.|
4341|`name`|path|Name of the target repository.|
4342|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
4343
4344
4345
4346
4347###### On Success: Data Accepted
4348
4349```
4350204 No Content
4351Location: /v2/<name>/blobs/uploads/<uuid>
4352Range: 0-<offset>
4353Content-Length: 0
4354Docker-Upload-UUID: <uuid>
4355```
4356
4357The 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.
4358
4359The following headers will be returned with the response:
4360
4361|Name|Description|
4362|----|-----------|
4363|`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.|
4364|`Range`|Range indicating the current progress of the upload.|
4365|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
4366|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
4367
4368
4369
4370
4371###### On Failure: Bad Request
4372
4373```
4374400 Bad Request
4375Content-Type: application/json; charset=utf-8
4376
4377{
4378 "errors:" [
4379 {
4380 "code": <error code>,
4381 "message": "<error message>",
4382 "detail": ...
4383 },
4384 ...
4385 ]
4386}
4387```
4388
4389There was an error processing the upload and it must be restarted.
4390
4391
4392
4393The error codes that may be included in the response body are enumerated below:
4394
4395|Code|Message|Description|
4396|----|-------|-----------|
4397| `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. |
4398| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
4399| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
4400
4401
4402
4403###### On Failure: Not Found
4404
4405```
4406404 Not Found
4407Content-Type: application/json; charset=utf-8
4408
4409{
4410 "errors:" [
4411 {
4412 "code": <error code>,
4413 "message": "<error message>",
4414 "detail": ...
4415 },
4416 ...
4417 ]
4418}
4419```
4420
4421The upload is unknown to the registry. The upload must be restarted.
4422
4423
4424
4425The error codes that may be included in the response body are enumerated below:
4426
4427|Code|Message|Description|
4428|----|-------|-----------|
4429| `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. |
4430
4431
4432
4433###### On Failure: Authentication Required
4434
4435```
4436401 Unauthorized
4437WWW-Authenticate: <scheme> realm="<realm>", ..."
4438Content-Length: <length>
4439Content-Type: application/json; charset=utf-8
4440
4441{
4442 "errors:" [
4443 {
4444 "code": <error code>,
4445 "message": "<error message>",
4446 "detail": ...
4447 },
4448 ...
4449 ]
4450}
4451```
4452
4453The client is not authenticated.
4454
4455The following headers will be returned on the response:
4456
4457|Name|Description|
4458|----|-----------|
4459|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
4460|`Content-Length`|Length of the JSON response body.|
4461
4462
4463
4464The error codes that may be included in the response body are enumerated below:
4465
4466|Code|Message|Description|
4467|----|-------|-----------|
4468| `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. |
4469
4470
4471
4472###### On Failure: No Such Repository Error
4473
4474```
4475404 Not Found
4476Content-Length: <length>
4477Content-Type: application/json; charset=utf-8
4478
4479{
4480 "errors:" [
4481 {
4482 "code": <error code>,
4483 "message": "<error message>",
4484 "detail": ...
4485 },
4486 ...
4487 ]
4488}
4489```
4490
4491The repository is not known to the registry.
4492
4493The following headers will be returned on the response:
4494
4495|Name|Description|
4496|----|-----------|
4497|`Content-Length`|Length of the JSON response body.|
4498
4499
4500
4501The error codes that may be included in the response body are enumerated below:
4502
4503|Code|Message|Description|
4504|----|-------|-----------|
4505| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
4506
4507
4508
4509###### On Failure: Access Denied
4510
4511```
4512403 Forbidden
4513Content-Length: <length>
4514Content-Type: application/json; charset=utf-8
4515
4516{
4517 "errors:" [
4518 {
4519 "code": <error code>,
4520 "message": "<error message>",
4521 "detail": ...
4522 },
4523 ...
4524 ]
4525}
4526```
4527
4528The client does not have required access to the repository.
4529
4530The following headers will be returned on the response:
4531
4532|Name|Description|
4533|----|-----------|
4534|`Content-Length`|Length of the JSON response body.|
4535
4536
4537
4538The error codes that may be included in the response body are enumerated below:
4539
4540|Code|Message|Description|
4541|----|-------|-----------|
4542| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
4543
4544
4545
4546###### On Failure: Too Many Requests
4547
4548```
4549429 Too Many Requests
4550Content-Length: <length>
4551Content-Type: application/json; charset=utf-8
4552
4553{
4554 "errors:" [
4555 {
4556 "code": <error code>,
4557 "message": "<error message>",
4558 "detail": ...
4559 },
4560 ...
4561 ]
4562}
4563```
4564
4565The client made too many requests within a time interval.
4566
4567The following headers will be returned on the response:
4568
4569|Name|Description|
4570|----|-----------|
4571|`Content-Length`|Length of the JSON response body.|
4572
4573
4574
4575The error codes that may be included in the response body are enumerated below:
4576
4577|Code|Message|Description|
4578|----|-------|-----------|
4579| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
4580
4581
4582
4583##### Chunked upload
4584
4585```
4586PATCH /v2/<name>/blobs/uploads/<uuid>
4587Host: <registry host>
4588Authorization: <scheme> <token>
4589Content-Range: <start of range>-<end of range, inclusive>
4590Content-Length: <length of chunk>
4591Content-Type: application/octet-stream
4592
4593<binary chunk>
4594```
4595
4596Upload a chunk of data to specified upload without completing the upload. The data will be uploaded to the specified Content Range.
4597
4598
4599The following parameters should be specified on the request:
4600
4601|Name|Kind|Description|
4602|----|----|-----------|
4603|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
4604|`Authorization`|header|An RFC7235 compliant authorization header.|
4605|`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.|
4606|`Content-Length`|header|Length of the chunk being uploaded, corresponding the length of the request body.|
4607|`name`|path|Name of the target repository.|
4608|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
4609
4610
4611
4612
4613###### On Success: Chunk Accepted
4614
4615```
4616204 No Content
4617Location: /v2/<name>/blobs/uploads/<uuid>
4618Range: 0-<offset>
4619Content-Length: 0
4620Docker-Upload-UUID: <uuid>
4621```
4622
4623The 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.
4624
4625The following headers will be returned with the response:
4626
4627|Name|Description|
4628|----|-----------|
4629|`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.|
4630|`Range`|Range indicating the current progress of the upload.|
4631|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
4632|`Docker-Upload-UUID`|Identifies the docker upload uuid for the current request.|
4633
4634
4635
4636
4637###### On Failure: Bad Request
4638
4639```
4640400 Bad Request
4641Content-Type: application/json; charset=utf-8
4642
4643{
4644 "errors:" [
4645 {
4646 "code": <error code>,
4647 "message": "<error message>",
4648 "detail": ...
4649 },
4650 ...
4651 ]
4652}
4653```
4654
4655There was an error processing the upload and it must be restarted.
4656
4657
4658
4659The error codes that may be included in the response body are enumerated below:
4660
4661|Code|Message|Description|
4662|----|-------|-----------|
4663| `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. |
4664| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
4665| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
4666
4667
4668
4669###### On Failure: Not Found
4670
4671```
4672404 Not Found
4673Content-Type: application/json; charset=utf-8
4674
4675{
4676 "errors:" [
4677 {
4678 "code": <error code>,
4679 "message": "<error message>",
4680 "detail": ...
4681 },
4682 ...
4683 ]
4684}
4685```
4686
4687The upload is unknown to the registry. The upload must be restarted.
4688
4689
4690
4691The error codes that may be included in the response body are enumerated below:
4692
4693|Code|Message|Description|
4694|----|-------|-----------|
4695| `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. |
4696
4697
4698
4699###### On Failure: Requested Range Not Satisfiable
4700
4701```
4702416 Requested Range Not Satisfiable
4703```
4704
4705The `Content-Range` specification cannot be accepted, either because it does not overlap with the current progress or it is invalid.
4706
4707
4708
4709###### On Failure: Authentication Required
4710
4711```
4712401 Unauthorized
4713WWW-Authenticate: <scheme> realm="<realm>", ..."
4714Content-Length: <length>
4715Content-Type: application/json; charset=utf-8
4716
4717{
4718 "errors:" [
4719 {
4720 "code": <error code>,
4721 "message": "<error message>",
4722 "detail": ...
4723 },
4724 ...
4725 ]
4726}
4727```
4728
4729The client is not authenticated.
4730
4731The following headers will be returned on the response:
4732
4733|Name|Description|
4734|----|-----------|
4735|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
4736|`Content-Length`|Length of the JSON response body.|
4737
4738
4739
4740The error codes that may be included in the response body are enumerated below:
4741
4742|Code|Message|Description|
4743|----|-------|-----------|
4744| `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. |
4745
4746
4747
4748###### On Failure: No Such Repository Error
4749
4750```
4751404 Not Found
4752Content-Length: <length>
4753Content-Type: application/json; charset=utf-8
4754
4755{
4756 "errors:" [
4757 {
4758 "code": <error code>,
4759 "message": "<error message>",
4760 "detail": ...
4761 },
4762 ...
4763 ]
4764}
4765```
4766
4767The repository is not known to the registry.
4768
4769The following headers will be returned on the response:
4770
4771|Name|Description|
4772|----|-----------|
4773|`Content-Length`|Length of the JSON response body.|
4774
4775
4776
4777The error codes that may be included in the response body are enumerated below:
4778
4779|Code|Message|Description|
4780|----|-------|-----------|
4781| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
4782
4783
4784
4785###### On Failure: Access Denied
4786
4787```
4788403 Forbidden
4789Content-Length: <length>
4790Content-Type: application/json; charset=utf-8
4791
4792{
4793 "errors:" [
4794 {
4795 "code": <error code>,
4796 "message": "<error message>",
4797 "detail": ...
4798 },
4799 ...
4800 ]
4801}
4802```
4803
4804The client does not have required access to the repository.
4805
4806The following headers will be returned on the response:
4807
4808|Name|Description|
4809|----|-----------|
4810|`Content-Length`|Length of the JSON response body.|
4811
4812
4813
4814The error codes that may be included in the response body are enumerated below:
4815
4816|Code|Message|Description|
4817|----|-------|-----------|
4818| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
4819
4820
4821
4822###### On Failure: Too Many Requests
4823
4824```
4825429 Too Many Requests
4826Content-Length: <length>
4827Content-Type: application/json; charset=utf-8
4828
4829{
4830 "errors:" [
4831 {
4832 "code": <error code>,
4833 "message": "<error message>",
4834 "detail": ...
4835 },
4836 ...
4837 ]
4838}
4839```
4840
4841The client made too many requests within a time interval.
4842
4843The following headers will be returned on the response:
4844
4845|Name|Description|
4846|----|-----------|
4847|`Content-Length`|Length of the JSON response body.|
4848
4849
4850
4851The error codes that may be included in the response body are enumerated below:
4852
4853|Code|Message|Description|
4854|----|-------|-----------|
4855| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
4856
4857
4858
4859
4860#### PUT Blob Upload
4861
4862Complete the upload specified by `uuid`, optionally appending the body as the final chunk.
4863
4864
4865
4866```
4867PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
4868Host: <registry host>
4869Authorization: <scheme> <token>
4870Content-Length: <length of data>
4871Content-Type: application/octet-stream
4872
4873<binary data>
4874```
4875
4876Complete 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.
4877
4878
4879The following parameters should be specified on the request:
4880
4881|Name|Kind|Description|
4882|----|----|-----------|
4883|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
4884|`Authorization`|header|An RFC7235 compliant authorization header.|
4885|`Content-Length`|header|Length of the data being uploaded, corresponding to the length of the request body. May be zero if no data is provided.|
4886|`name`|path|Name of the target repository.|
4887|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
4888|`digest`|query|Digest of uploaded blob.|
4889
4890
4891
4892
4893###### On Success: Upload Complete
4894
4895```
4896204 No Content
4897Location: <blob location>
4898Content-Range: <start of range>-<end of range, inclusive>
4899Content-Length: 0
4900Docker-Content-Digest: <digest>
4901```
4902
4903The upload has been completed and accepted by the registry. The canonical location will be available in the `Location` header.
4904
4905The following headers will be returned with the response:
4906
4907|Name|Description|
4908|----|-----------|
4909|`Location`|The canonical location of the blob for retrieval|
4910|`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.|
4911|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
4912|`Docker-Content-Digest`|Digest of the targeted content for the request.|
4913
4914
4915
4916
4917###### On Failure: Bad Request
4918
4919```
4920400 Bad Request
4921Content-Type: application/json; charset=utf-8
4922
4923{
4924 "errors:" [
4925 {
4926 "code": <error code>,
4927 "message": "<error message>",
4928 "detail": ...
4929 },
4930 ...
4931 ]
4932}
4933```
4934
4935There was an error processing the upload and it must be restarted.
4936
4937
4938
4939The error codes that may be included in the response body are enumerated below:
4940
4941|Code|Message|Description|
4942|----|-------|-----------|
4943| `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. |
4944| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
4945| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
4946| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |
4947
4948
4949
4950###### On Failure: Not Found
4951
4952```
4953404 Not Found
4954Content-Type: application/json; charset=utf-8
4955
4956{
4957 "errors:" [
4958 {
4959 "code": <error code>,
4960 "message": "<error message>",
4961 "detail": ...
4962 },
4963 ...
4964 ]
4965}
4966```
4967
4968The upload is unknown to the registry. The upload must be restarted.
4969
4970
4971
4972The error codes that may be included in the response body are enumerated below:
4973
4974|Code|Message|Description|
4975|----|-------|-----------|
4976| `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. |
4977
4978
4979
4980###### On Failure: Authentication Required
4981
4982```
4983401 Unauthorized
4984WWW-Authenticate: <scheme> realm="<realm>", ..."
4985Content-Length: <length>
4986Content-Type: application/json; charset=utf-8
4987
4988{
4989 "errors:" [
4990 {
4991 "code": <error code>,
4992 "message": "<error message>",
4993 "detail": ...
4994 },
4995 ...
4996 ]
4997}
4998```
4999
5000The client is not authenticated.
5001
5002The following headers will be returned on the response:
5003
5004|Name|Description|
5005|----|-----------|
5006|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
5007|`Content-Length`|Length of the JSON response body.|
5008
5009
5010
5011The error codes that may be included in the response body are enumerated below:
5012
5013|Code|Message|Description|
5014|----|-------|-----------|
5015| `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. |
5016
5017
5018
5019###### On Failure: No Such Repository Error
5020
5021```
5022404 Not Found
5023Content-Length: <length>
5024Content-Type: application/json; charset=utf-8
5025
5026{
5027 "errors:" [
5028 {
5029 "code": <error code>,
5030 "message": "<error message>",
5031 "detail": ...
5032 },
5033 ...
5034 ]
5035}
5036```
5037
5038The repository is not known to the registry.
5039
5040The following headers will be returned on the response:
5041
5042|Name|Description|
5043|----|-----------|
5044|`Content-Length`|Length of the JSON response body.|
5045
5046
5047
5048The error codes that may be included in the response body are enumerated below:
5049
5050|Code|Message|Description|
5051|----|-------|-----------|
5052| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
5053
5054
5055
5056###### On Failure: Access Denied
5057
5058```
5059403 Forbidden
5060Content-Length: <length>
5061Content-Type: application/json; charset=utf-8
5062
5063{
5064 "errors:" [
5065 {
5066 "code": <error code>,
5067 "message": "<error message>",
5068 "detail": ...
5069 },
5070 ...
5071 ]
5072}
5073```
5074
5075The client does not have required access to the repository.
5076
5077The following headers will be returned on the response:
5078
5079|Name|Description|
5080|----|-----------|
5081|`Content-Length`|Length of the JSON response body.|
5082
5083
5084
5085The error codes that may be included in the response body are enumerated below:
5086
5087|Code|Message|Description|
5088|----|-------|-----------|
5089| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
5090
5091
5092
5093###### On Failure: Too Many Requests
5094
5095```
5096429 Too Many Requests
5097Content-Length: <length>
5098Content-Type: application/json; charset=utf-8
5099
5100{
5101 "errors:" [
5102 {
5103 "code": <error code>,
5104 "message": "<error message>",
5105 "detail": ...
5106 },
5107 ...
5108 ]
5109}
5110```
5111
5112The client made too many requests within a time interval.
5113
5114The following headers will be returned on the response:
5115
5116|Name|Description|
5117|----|-----------|
5118|`Content-Length`|Length of the JSON response body.|
5119
5120
5121
5122The error codes that may be included in the response body are enumerated below:
5123
5124|Code|Message|Description|
5125|----|-------|-----------|
5126| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
5127
5128
5129
5130
5131#### DELETE Blob Upload
5132
5133Cancel outstanding upload processes, releasing associated resources. If this is not called, the unfinished uploads will eventually timeout.
5134
5135
5136
5137```
5138DELETE /v2/<name>/blobs/uploads/<uuid>
5139Host: <registry host>
5140Authorization: <scheme> <token>
5141Content-Length: 0
5142```
5143
5144Cancel the upload specified by `uuid`.
5145
5146
5147The following parameters should be specified on the request:
5148
5149|Name|Kind|Description|
5150|----|----|-----------|
5151|`Host`|header|Standard HTTP Host Header. Should be set to the registry host.|
5152|`Authorization`|header|An RFC7235 compliant authorization header.|
5153|`Content-Length`|header|The `Content-Length` header must be zero and the body must be empty.|
5154|`name`|path|Name of the target repository.|
5155|`uuid`|path|A uuid identifying the upload. This field can accept characters that match `[a-zA-Z0-9-_.=]+`.|
5156
5157
5158
5159
5160###### On Success: Upload Deleted
5161
5162```
5163204 No Content
5164Content-Length: 0
5165```
5166
5167The upload has been successfully deleted.
5168
5169The following headers will be returned with the response:
5170
5171|Name|Description|
5172|----|-----------|
5173|`Content-Length`|The `Content-Length` header must be zero and the body must be empty.|
5174
5175
5176
5177
5178###### On Failure: Bad Request
5179
5180```
5181400 Bad Request
5182Content-Type: application/json; charset=utf-8
5183
5184{
5185 "errors:" [
5186 {
5187 "code": <error code>,
5188 "message": "<error message>",
5189 "detail": ...
5190 },
5191 ...
5192 ]
5193}
5194```
5195
5196An error was encountered processing the delete. The client may ignore this error.
5197
5198
5199
5200The error codes that may be included in the response body are enumerated below:
5201
5202|Code|Message|Description|
5203|----|-------|-----------|
5204| `NAME_INVALID` | invalid repository name | Invalid repository name encountered either during manifest validation or any API operation. |
5205| `BLOB_UPLOAD_INVALID` | blob upload invalid | The blob upload encountered an error and can no longer proceed. |
5206
5207
5208
5209###### On Failure: Not Found
5210
5211```
5212404 Not Found
5213Content-Type: application/json; charset=utf-8
5214
5215{
5216 "errors:" [
5217 {
5218 "code": <error code>,
5219 "message": "<error message>",
5220 "detail": ...
5221 },
5222 ...
5223 ]
5224}
5225```
5226
5227The upload is unknown to the registry. The client may ignore this error and assume the upload has been deleted.
5228
5229
5230
5231The error codes that may be included in the response body are enumerated below:
5232
5233|Code|Message|Description|
5234|----|-------|-----------|
5235| `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. |
5236
5237
5238
5239###### On Failure: Authentication Required
5240
5241```
5242401 Unauthorized
5243WWW-Authenticate: <scheme> realm="<realm>", ..."
5244Content-Length: <length>
5245Content-Type: application/json; charset=utf-8
5246
5247{
5248 "errors:" [
5249 {
5250 "code": <error code>,
5251 "message": "<error message>",
5252 "detail": ...
5253 },
5254 ...
5255 ]
5256}
5257```
5258
5259The client is not authenticated.
5260
5261The following headers will be returned on the response:
5262
5263|Name|Description|
5264|----|-----------|
5265|`WWW-Authenticate`|An RFC7235 compliant authentication challenge header.|
5266|`Content-Length`|Length of the JSON response body.|
5267
5268
5269
5270The error codes that may be included in the response body are enumerated below:
5271
5272|Code|Message|Description|
5273|----|-------|-----------|
5274| `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. |
5275
5276
5277
5278###### On Failure: No Such Repository Error
5279
5280```
5281404 Not Found
5282Content-Length: <length>
5283Content-Type: application/json; charset=utf-8
5284
5285{
5286 "errors:" [
5287 {
5288 "code": <error code>,
5289 "message": "<error message>",
5290 "detail": ...
5291 },
5292 ...
5293 ]
5294}
5295```
5296
5297The repository is not known to the registry.
5298
5299The following headers will be returned on the response:
5300
5301|Name|Description|
5302|----|-----------|
5303|`Content-Length`|Length of the JSON response body.|
5304
5305
5306
5307The error codes that may be included in the response body are enumerated below:
5308
5309|Code|Message|Description|
5310|----|-------|-----------|
5311| `NAME_UNKNOWN` | repository name not known to registry | This is returned if the name used during an operation is unknown to the registry. |
5312
5313
5314
5315###### On Failure: Access Denied
5316
5317```
5318403 Forbidden
5319Content-Length: <length>
5320Content-Type: application/json; charset=utf-8
5321
5322{
5323 "errors:" [
5324 {
5325 "code": <error code>,
5326 "message": "<error message>",
5327 "detail": ...
5328 },
5329 ...
5330 ]
5331}
5332```
5333
5334The client does not have required access to the repository.
5335
5336The following headers will be returned on the response:
5337
5338|Name|Description|
5339|----|-----------|
5340|`Content-Length`|Length of the JSON response body.|
5341
5342
5343
5344The error codes that may be included in the response body are enumerated below:
5345
5346|Code|Message|Description|
5347|----|-------|-----------|
5348| `DENIED` | requested access to the resource is denied | The access controller denied access for the operation on a resource. |
5349
5350
5351
5352###### On Failure: Too Many Requests
5353
5354```
5355429 Too Many Requests
5356Content-Length: <length>
5357Content-Type: application/json; charset=utf-8
5358
5359{
5360 "errors:" [
5361 {
5362 "code": <error code>,
5363 "message": "<error message>",
5364 "detail": ...
5365 },
5366 ...
5367 ]
5368}
5369```
5370
5371The client made too many requests within a time interval.
5372
5373The following headers will be returned on the response:
5374
5375|Name|Description|
5376|----|-----------|
5377|`Content-Length`|Length of the JSON response body.|
5378
5379
5380
5381The error codes that may be included in the response body are enumerated below:
5382
5383|Code|Message|Description|
5384|----|-------|-----------|
5385| `TOOMANYREQUESTS` | too many requests | Returned when a client attempts to contact a service too many times |
5386
5387
5388
5389
5390
5391### Catalog
5392
5393List 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.
5394
5395
5396
5397#### GET Catalog
5398
5399Retrieve a sorted, json list of repositories available in the registry.
5400
5401
5402##### Catalog Fetch
5403
5404```
5405GET /v2/_catalog
5406```
5407
5408Request an unabridged list of repositories available. The implementation may impose a maximum limit and return a partial set with pagination links.
5409
5410
5411
5412
5413
5414###### On Success: OK
5415
5416```
5417200 OK
5418Content-Length: <length>
5419Content-Type: application/json; charset=utf-8
5420
5421{
5422 "repositories": [
5423 <name>,
5424 ...
5425 ]
5426}
5427```
5428
5429Returns the unabridged list of repositories as a json response.
5430
5431The following headers will be returned with the response:
5432
5433|Name|Description|
5434|----|-----------|
5435|`Content-Length`|Length of the JSON response body.|
5436
5437
5438
5439##### Catalog Fetch Paginated
5440
5441```
5442GET /v2/_catalog?n=<integer>&last=<integer>
5443```
5444
5445Return the specified portion of repositories.
5446
5447
5448The following parameters should be specified on the request:
5449
5450|Name|Kind|Description|
5451|----|----|-----------|
5452|`n`|query|Limit the number of entries in each response. It not present, all entries will be returned.|
5453|`last`|query|Result set will include values lexically after last.|
5454
5455
5456
5457
5458###### On Success: OK
5459
5460```
5461200 OK
5462Content-Length: <length>
5463Link: <<url>?n=<last n value>&last=<last entry from response>>; rel="next"
5464Content-Type: application/json; charset=utf-8
5465
5466{
5467 "repositories": [
5468 <name>,
5469 ...
5470 ]
5471 "next": "<url>?last=<name>&n=<last value of n>"
5472}
5473```
5474
5475
5476
5477The following headers will be returned with the response:
5478
5479|Name|Description|
5480|----|-----------|
5481|`Content-Length`|Length of the JSON response body.|
5482|`Link`|RFC5988 compliant rel='next' with URL to next result set, if available|
5483
5484
5485
5486
5487
View as plain text