docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ref: reformat from vscode default formatting

This commit is contained in:
Josh Newman 2022-07-18 22:39:26 -06:00
parent 445770f245
commit f764a6e934
1 changed files with 159 additions and 218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

377
docker-hub/api/latest.yaml
View File

@ -5,7 +5,7 @@ info:
x-logo: x-logo:
url: https://docs.docker.com/images/logo-docker-main.png url: https://docs.docker.com/images/logo-docker-main.png
href: /reference href: /reference
description: > description: |
Docker Hub is a service provided by Docker for finding and sharing container Docker Hub is a service provided by Docker for finding and sharing container
images with your team. images with your team.
@ -19,43 +19,28 @@ info:
tags: tags:
- name: resources - name: resources
x-displayName: Resources x-displayName: Resources
description: > description: |
The following resources are available to interact with the documented API: The following resources are available to interact with the documented API:
- <a href="https://github.com/docker/hub-tool#readme" target="_blank">Docker Hub CLI tool</a> (currently experimental) - <a href="https://github.com/docker/hub-tool#readme" target="_blank">Docker Hub CLI tool</a> (currently experimental)
- <a href="https://www.postman.com/dockerdev/workspace/docker-hub/collection/17990590-9574e087-2a50-4ecf-88b3-55f12a29d99e" target="_blank">Postman Collection</a> - <a href="https://www.postman.com/dockerdev/workspace/docker-hub/collection/17990590-9574e087-2a50-4ecf-88b3-55f12a29d99e" target="_blank">Postman Collection</a>
- name: rate-limiting - name: rate-limiting
x-displayName: Rate Limiting x-displayName: Rate Limiting
description: > description: |
The Docker Hub API is limited on the amount of requests you can perform The Docker Hub API is limited on the amount of requests you can perform per minute against it.
per minute against it.
If you haven't hit the limit, each request to the API will return the If you haven't hit the limit, each request to the API will return the
following headers in the response. following headers in the response.
- `X-RateLimit-Limit` - The limit of requests per minute. - `X-RateLimit-Limit` - The limit of requests per minute.
- `X-RateLimit-Remaining` - The remaining amount of calls within the limit period.
- `X-RateLimit-Remaining` - The remaining amount of calls within the limit
period.
- `X-RateLimit-Reset` - The unix timestamp of when the remaining resets. - `X-RateLimit-Reset` - The unix timestamp of when the remaining resets.
If you have hit the limit, you will receive a response status of `429` and the `X-Retry-After`
header in the response.
If you have hit the limit, you will receive a response status of `429` and The `X-Retry-After` header is a unix timestamp of when you can call the API again.
the `X-Retry-After` header in the response.
The `X-Retry-After` header is a unix timestamp of when you can call the
API again.
*Note: These rate limits are separate from anti-abuse and Docker Hub *Note: These rate limits are separate from anti-abuse and Docker Hub
@ -64,72 +49,55 @@ tags:
limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/).* limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/).*
- name: authentication - name: authentication
x-displayName: Authentication x-displayName: Authentication
description: > description: |
Most Docker Hub API endpoints require you to authenticate using your Most Docker Hub API endpoints require you to authenticate using your
Docker credentials before using them. Docker credentials before using them.
Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending
Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Free, Pro, or Team) and your account's permissions. on your plan (Free, Pro, or Team) and your account's permissions.
To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing). To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing).
- name: access-tokens - name: access-tokens
x-displayName: Personal Access Tokens x-displayName: Personal Access Tokens
description: > description: |
The Personal Access Token endpoints lets you manage personal access The Personal Access Token endpoints lets you manage personal access tokens. For more
information, see [Access Tokens](https://docs.docker.com/docker-hub/access-tokens/).
tokens. For more information, see
[Access Tokens](https://docs.docker.com/docker-hub/access-tokens/).
You can use a personal access token instead of a password in the
[Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) or
in the [Create an authentication token](#operation/PostUsersLogin) route
to obtain a bearer token.
You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/)
or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer
token.
### Scopes ### Scopes
For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower
For each scope grouping (in this case "repo"), you only need to define 1 scopes are assumed. For example: If you define `repo:write`, the API assumes the scope of both
`repo:read` *and* `repo:public_read` as well. If you were to define both `repo:write` *and*
scope as any lower scopes are assumed. For example: If you define
`repo:write`, the API assumes the scope of both `repo:read` *and*
`repo:public_read` as well. If you were to define both `repo:write` *and*
`repo:read`, then `repo:read` is assumed by `repo:write` and ignored. `repo:read`, then `repo:read` is assumed by `repo:write` and ignored.
***Treat your personal access token like your password and keep it secret. You cannot retrieve
***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after your token after it is generated.***
it is generated.***
- name: images - name: images
x-displayName: Advanced Image Management x-displayName: Advanced Image Management
description: > description: |
The Advanced Image Management API endpoints allow you to manage Docker The Advanced Image Management API endpoints allow you to manage Docker
images across all repositories. images across all repositories.
For more information, see [Advanced Image Management dashboard](https://docs.docker.com/docker-hub/image-management/). For more information, see [Advanced Image Management dashboard](https://docs.docker.com/docker-hub/image-management/).
- name: audit-logs - name: audit-logs
x-displayName: Audit Logs x-displayName: Audit Logs
description: > description: |
The Audit Logs API endpoints allow you to query audit log events across a The Audit Logs API endpoints allow you to query audit log events across a
namespace. namespace.
For more information, see [Audit Log](https://docs.docker.com/docker-hub/audit-log/) For more information, see [Audit Log](https://docs.docker.com/docker-hub/audit-log/)
- name: org-settings - name: org-settings
x-displayName: Org Settings x-displayName: Org Settings
description: > description: |
The Org Settings API endpoints allow you to manage your organization's The Org Settings API endpoints allow you to manage your organization's
settings. settings.
- name: repositories - name: repositories
x-displayName: Repositories x-displayName: Repositories
description: > description: |
The repository endpoints allow you to manage your repository's The repository endpoints allow you to manage your repository's
configuration like description. configuration like description.
x-tagGroups: x-tagGroups:
@ -152,14 +120,12 @@ paths:
- authentication - authentication
summary: Create an authentication token summary: Create an authentication token
operationId: PostUsersLogin operationId: PostUsersLogin
description: > description: |
Creates and returns a bearer token in JWT format that you can use to Creates and returns a bearer token in JWT format that you can use to
authenticate with Docker Hub APIs. authenticate with Docker Hub APIs.
The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`. The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
requestBody: requestBody:
content: content:
@ -169,13 +135,13 @@ paths:
description: Login details. description: Login details.
required: true required: true
responses: responses:
"200": 200:
description: Authentication successful description: Authentication successful
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/PostUsersLoginSuccessResponse" $ref: "#/components/schemas/PostUsersLoginSuccessResponse"
"401": 401:
description: Authentication failed or second factor required description: Authentication failed or second factor required
content: content:
application/json: application/json:
@ -187,17 +153,14 @@ paths:
- authentication - authentication
summary: Second factor authentication. summary: Second factor authentication.
operationId: PostUsers2FALogin operationId: PostUsers2FALogin
description: > description: |
When user has 2FA enabled, this is the second call to perform after When user has 2FA enabled, this is the second call to perform after
`/v2/users/login` call. `/v2/users/login` call.
Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.
The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`. The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.
Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.
requestBody: requestBody:
content: content:
@ -207,13 +170,13 @@ paths:
description: Login details. description: Login details.
required: true required: true
responses: responses:
"200": 200:
description: Authentication successful description: Authentication successful
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/PostUsersLoginSuccessResponse" $ref: "#/components/schemas/PostUsersLoginSuccessResponse"
"401": 401:
description: Authentication failed or second factor required description: Authentication failed or second factor required
content: content:
application/json: application/json:
@ -232,15 +195,15 @@ paths:
$ref: "#/components/schemas/createAccessTokenRequest" $ref: "#/components/schemas/createAccessTokenRequest"
required: true required: true
responses: responses:
"201": 201:
description: Created description: Created
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/createAccessTokensResponse" $ref: "#/components/schemas/createAccessTokensResponse"
"400": 400:
$ref: "#/components/responses/BadRequest" $ref: "#/components/responses/BadRequest"
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
get: get:
summary: Get a list of personal access tokens summary: Get a list of personal access tokens
@ -259,15 +222,15 @@ paths:
type: number type: number
default: 10 default: 10
responses: responses:
"200": 200:
description: OK description: OK
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/getAccessTokensResponse" $ref: "#/components/schemas/getAccessTokensResponse"
"400": 400:
$ref: "#/components/responses/BadRequest" $ref: "#/components/responses/BadRequest"
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
/v2/access-tokens/{uuid}: /v2/access-tokens/{uuid}:
parameters: parameters:
@ -290,15 +253,15 @@ paths:
$ref: "#/components/schemas/patchAccessTokenRequest" $ref: "#/components/schemas/patchAccessTokenRequest"
required: true required: true
responses: responses:
"200": 200:
description: OK description: OK
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/patchAccessTokenResponse" $ref: "#/components/schemas/patchAccessTokenResponse"
"400": 400:
$ref: "#/components/responses/BadRequest" $ref: "#/components/responses/BadRequest"
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
get: get:
summary: Get a personal access token summary: Get a personal access token
@ -306,7 +269,7 @@ paths:
tags: tags:
- access-tokens - access-tokens
responses: responses:
"200": 200:
description: OK description: OK
content: content:
application/json: application/json:
@ -318,9 +281,9 @@ paths:
token: token:
type: string type: string
example: "" example: ""
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
"404": 404:
$ref: "#/components/responses/NotFound" $ref: "#/components/responses/NotFound"
delete: delete:
summary: Delete a personal access token summary: Delete a personal access token
@ -329,18 +292,18 @@ paths:
tags: tags:
- access-tokens - access-tokens
responses: responses:
"204": 204:
description: A successful response. description: A successful response.
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
"404": 404:
$ref: "#/components/responses/NotFound" $ref: "#/components/responses/NotFound"
"/v2/namespaces/{namespace}/repositories/{repository}/images-summary": /v2/namespaces/{namespace}/repositories/{repository}/images-summary:
get: get:
tags: tags:
- images - images
summary: Get summary of repository's images summary: Get summary of repository's images
description: > description: |
Gets the number of images in a repository and the number of images Gets the number of images in a repository and the number of images
counted as active and inactive. counted as active and inactive.
operationId: GetNamespacesRepositoriesImagesSummary operationId: GetNamespacesRepositoriesImagesSummary
@ -360,29 +323,28 @@ paths:
- name: active_from - name: active_from
in: query in: query
required: false required: false
description: > description: |
Sets the time from which an image must have been pushed or pulled to Sets the time from which an image must have been pushed or pulled to
be counted as active. be counted as active.
Defaults to 1 month before the current time. Defaults to 1 month before the current time.
schema: schema:
type: string type: string
responses: responses:
"200": 200:
description: Success description: Success
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/GetNamespaceRepositoryImagesSummaryResp\ $ref:
onse" "#/components/schemas/GetNamespaceRepositoryImagesSummaryResponse"
"401": 401:
description: Unauthorized - user does not have read access to the namespace description: Unauthorized - user does not have read access to the namespace
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
"/v2/namespaces/{namespace}/repositories/{repository}/images": /v2/namespaces/{namespace}/repositories/{repository}/images:
get: get:
tags: tags:
- images - images
@ -416,8 +378,8 @@ paths:
required: false required: false
description: | description: |
Filters to only show images with: Filters to only show images with:
* `true`: at least 1 current tag. - `true`: at least 1 current tag.
* `false`: no current tags. - `false`: no current tags.
schema: schema:
type: boolean type: boolean
- name: ordering - name: ordering
@ -437,11 +399,10 @@ paths:
- name: active_from - name: active_from
in: query in: query
required: false required: false
description: > description: |
Sets the time from which an image must have been pushed or pulled to Sets the time from which an image must have been pushed or pulled to
be counted as active. be counted as active.
Defaults to 1 month before the current time. Defaults to 1 month before the current time.
schema: schema:
type: string type: string
@ -458,25 +419,25 @@ paths:
schema: schema:
type: integer type: integer
responses: responses:
"200": 200:
description: Success description: Success
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/GetNamespaceRepositoryImagesResponse" $ref: "#/components/schemas/GetNamespaceRepositoryImagesResponse"
"401": 401:
description: Unauthorized - user does not have read access to the namespace. description: Unauthorized - user does not have read access to the namespace.
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
"403": 403:
description: Forbidden - this API is only available to users on Pro or Team plans. description: Forbidden - this API is only available to users on Pro or Team plans.
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
"/v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags": /v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags:
get: get:
tags: tags:
- images - images
@ -515,43 +476,39 @@ paths:
schema: schema:
type: integer type: integer
responses: responses:
"200": 200:
description: Success description: Success
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/GetNamespaceRepositoryImagesTagsResponse" $ref: "#/components/schemas/GetNamespaceRepositoryImagesTagsResponse"
"401": 401:
description: Unauthorized - user does not have read access to the namespace description: Unauthorized - user does not have read access to the namespace
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
"403": 403:
description: Forbidden - this API is only available to users on Pro or Team plans description: Forbidden - this API is only available to users on Pro or Team plans
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
"/v2/namespaces/{namespace}/delete-images": /v2/namespaces/{namespace}/delete-images:
post: post:
tags: tags:
- images - images
summary: Delete images summary: Delete images
operationId: PostNamespacesDeleteImages operationId: PostNamespacesDeleteImages
description: > description: |
Deletes one or more images within a namespace. This is currently limited Deletes one or more images within a namespace. This is currently limited to a single
to a single repostiory. repository.
If you attempt to delete images that are marked as active or are currently tagged, the deletion does not happen and it displays the warnings. If you attempt to delete images that are marked as active or are currently tagged, the deletion does not happen and it displays the warnings.
To continue with the deletion, you must ignore these warnings by putting them in the `ignore_warnings` property. To continue with the deletion, you must ignore these warnings by putting them in the `ignore_warnings` property.
Deleting a currently tagged image deletes the tag from the repository. Deleting a currently tagged image deletes the tag from the repository.
You cannot ignore errors. It is not possible to directly delete children of multi-arch images. You cannot ignore errors. It is not possible to directly delete children of multi-arch images.
parameters: parameters:
- name: namespace - name: namespace
@ -568,32 +525,31 @@ paths:
description: Delete request. description: Delete request.
required: true required: true
responses: responses:
"200": 200:
description: Deletion completed description: Deletion completed
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/PostNamespacesDeleteImagesResponseSucce\ $ref: "#/components/schemas/PostNamespacesDeleteImagesResponseSuccess"
ss" 400:
"400":
description: Deletion not possible description: Deletion not possible
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/PostNamespacesDeleteImagesResponseError" $ref: "#/components/schemas/PostNamespacesDeleteImagesResponseError"
"403": 403:
description: Forbidden - this API is only available to users on Pro or Team plans description: Forbidden - this API is only available to users on Pro or Team plans
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
"/v2/auditlogs/{account}": /v2/auditlogs/{account}:
get: get:
summary: Returns list of audit log events. summary: Returns list of audit log events.
description: Get audit log events for a given namespace. description: Get audit log events for a given namespace.
operationId: AuditLogs_GetAuditLogs operationId: AuditLogs_GetAuditLogs
responses: responses:
"200": 200:
description: A successful response. description: A successful response.
content: content:
application/json: application/json:
@ -611,9 +567,10 @@ paths:
digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa
tag: latest tag: latest
timestamp: 2021-02-19T01:34:35Z timestamp: 2021-02-19T01:34:35Z
action_description: pushed the tag latest with the digest action_description:
pushed the tag latest with the digest
sha256:c1ae9c435032a to the repository docker/example sha256:c1ae9c435032a to the repository docker/example
"429": 429:
description: "" description: ""
content: content:
application/json: application/json:
@ -623,7 +580,7 @@ paths:
value: value:
detail: Rate limit exceeded detail: Rate limit exceeded
error: false error: false
"500": 500:
description: "" description: ""
content: content:
application/json: application/json:
@ -642,14 +599,16 @@ paths:
schema: schema:
type: string type: string
- name: action - name: action
description: action name one of ["repo.tag.push", ...]. Optional parameter to description:
action name one of ["repo.tag.push", ...]. Optional parameter to
filter specific audit log actions. filter specific audit log actions.
in: query in: query
required: false required: false
schema: schema:
type: string type: string
- name: name - name: name
description: name. Optional parameter to filter audit log events to a specific description:
name. Optional parameter to filter audit log events to a specific
name. For repository events, this is the name of the repository. For name. For repository events, this is the name of the repository. For
organization events, this is the name of the organization. For team organization events, this is the name of the organization. For team
member events, this is the username of the team member. member events, this is the username of the team member.
@ -658,7 +617,8 @@ paths:
schema: schema:
type: string type: string
- name: actor - name: actor
description: actor name. Optional parameter to filter audit log events to the description:
actor name. Optional parameter to filter audit log events to the
specific user who triggered the event. specific user who triggered the event.
in: query in: query
required: false required: false
@ -696,14 +656,15 @@ paths:
default: 25 default: 25
tags: tags:
- audit-logs - audit-logs
"/v2/auditlogs/{account}/actions": /v2/auditlogs/{account}/actions:
get: get:
summary: Returns list of audit log actions. summary: Returns list of audit log actions.
description: Get audit log actions for a namespace to be used as a filter for description:
Get audit log actions for a namespace to be used as a filter for
querying audit events. querying audit events.
operationId: AuditLogs_GetAuditActions operationId: AuditLogs_GetAuditActions
responses: responses:
"200": 200:
description: A successful response. description: A successful response.
content: content:
application/json: application/json:
@ -755,7 +716,7 @@ paths:
description: contains image tag delete events description: contains image tag delete events
label: Tag Deleted label: Tag Deleted
label: Repository label: Repository
"429": 429:
description: "" description: ""
content: content:
application/json: application/json:
@ -765,7 +726,7 @@ paths:
value: value:
detail: Rate limit exceeded detail: Rate limit exceeded
error: false error: false
"500": 500:
description: "" description: ""
content: content:
application/json: application/json:
@ -785,7 +746,7 @@ paths:
type: string type: string
tags: tags:
- audit-logs - audit-logs
"/v2/orgs/{name}/settings": /v2/orgs/{name}/settings:
parameters: parameters:
- in: path - in: path
name: name name: name
@ -800,30 +761,27 @@ paths:
tags: tags:
- org-settings - org-settings
responses: responses:
"200": 200:
description: OK description: OK
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/orgSettings" $ref: "#/components/schemas/orgSettings"
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
"403": 403:
$ref: "#/components/responses/Forbidden" $ref: "#/components/responses/Forbidden"
"404": 404:
$ref: "#/components/responses/NotFound" $ref: "#/components/responses/NotFound"
put: put:
summary: Update organization settings summary: Update organization settings
description: > description: |
Updates an organization's settings. Some settings are only used when the Updates an organization's settings. Some settings are only used when the
organization is on a business plan. organization is on a business plan.
***Only users in the "owners" group of the organization can use this endpoint.*** ***Only users in the "owners" group of the organization can use this endpoint.***
The following settings are only used on a business plan: The following settings are only used on a business plan:
- `restricted_images` - `restricted_images`
tags: tags:
- org-settings - org-settings
@ -844,19 +802,19 @@ paths:
- allow_verified_publishers - allow_verified_publishers
required: true required: true
responses: responses:
"200": 200:
description: OK description: OK
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/orgSettings" $ref: "#/components/schemas/orgSettings"
"401": 401:
$ref: "#/components/responses/Unauthorized" $ref: "#/components/responses/Unauthorized"
"403": 403:
$ref: "#/components/responses/Forbidden" $ref: "#/components/responses/Forbidden"
"404": 404:
$ref: "#/components/responses/NotFound" $ref: "#/components/responses/NotFound"
"/v2/repositories/{namespace}/{repository}/": /v2/repositories/{namespace}/{repository}/:
parameters: parameters:
- name: namespace - name: namespace
in: path in: path
@ -874,17 +832,13 @@ paths:
tags: tags:
- repositories - repositories
summary: Update repository configuration summary: Update repository configuration
description: > description: |
Update the configuration of a repository: Update the configuration of a repository:
- description: the summary of a repository - description: the summary of a repository
- full description: the readme displayed on repository's page, markdown accepted - full description: the readme displayed on repository's page, markdown accepted
- visibility: is the repository public or private - visibility: is the repository public or private
Authentication is required. Authentication is required.
operationId: PatchRepositoryDescription operationId: PatchRepositoryDescription
requestBody: requestBody:
@ -893,14 +847,15 @@ paths:
schema: schema:
$ref: "#/components/schemas/update_repository" $ref: "#/components/schemas/update_repository"
responses: responses:
"200": 200:
description: Success description: Success
content: content:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/repository" $ref: "#/components/schemas/repository"
"403": 403:
description: Forbidden - access to the resource is forbidden, you don't have description:
Forbidden - access to the resource is forbidden, you don't have
needed permission to perform this action. needed permission to perform this action.
content: content:
application/json: application/json:
@ -910,8 +865,8 @@ paths:
response: response:
value: value:
detail: You do not have permission to perform this action. detail: You do not have permission to perform this action.
"404": 404:
description: Repository not found or unable to access the ressource description: Repository not found or unable to access the resource
content: content:
application/json: application/json:
schema: schema:
@ -961,7 +916,8 @@ components:
type: string type: string
example: myusername example: myusername
password: password:
description: The password or personal access token (PAT) of the Docker Hub description:
The password or personal access token (PAT) of the Docker Hub
account to authenticate with. account to authenticate with.
type: string type: string
example: hunter2 example: hunter2
@ -970,7 +926,7 @@ components:
type: object type: object
properties: properties:
token: token:
description: > description: |
Created authentication token. Created authentication token.
This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs.
@ -989,7 +945,8 @@ components:
example: Incorrect authentication credentials example: Incorrect authentication credentials
nullable: false nullable: false
login_2fa_token: login_2fa_token:
description: Short time lived token to be used on `/v2/users/2fa-login` to description:
Short time lived token to be used on `/v2/users/2fa-login` to
complete the authentication. This field is present only if 2FA is complete the authentication. This field is present only if 2FA is
enabled. enabled.
type: string type: string
@ -1007,7 +964,8 @@ components:
type: string type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
code: code:
description: The Time-based One-Time Password of the Docker Hub account to description:
The Time-based One-Time Password of the Docker Hub account to
authenticate with. authenticate with.
type: string type: string
example: 123456 example: 123456
@ -1060,7 +1018,8 @@ components:
type: object type: object
properties: properties:
active_from: active_from:
description: Time from which an image must have been pushed or pulled to be description:
Time from which an image must have been pushed or pulled to be
counted as active. counted as active.
type: string type: string
example: 2021-01-25T14:25:37.076343059Z example: 2021-01-25T14:25:37.076343059Z
@ -1088,13 +1047,15 @@ components:
type: integer type: integer
example: 100 example: 100
next: next:
description: Link to the next page with the same query parameters if there are description:
Link to the next page with the same query parameters if there are
more images. more images.
type: string type: string
example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=4&page_size=20 example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=4&page_size=20
nullable: true nullable: true
previous: previous:
description: Link to the previous page with the same query parameters if not on description:
Link to the previous page with the same query parameters if not on
first page. first page.
type: string type: string
example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=2&page_size=20 example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=2&page_size=20
@ -1128,10 +1089,9 @@ components:
type: string type: string
example: latest example: latest
is_current: is_current:
description: > description: |
`true` if the tag currently points to this image. `true` if the tag currently points to this image.
`false` if it has been overwritten to point at a different image. `false` if it has been overwritten to point at a different image.
type: boolean type: boolean
example: true example: true
@ -1141,13 +1101,15 @@ components:
example: 2021-02-24T22:05:27.526308Z example: 2021-02-24T22:05:27.526308Z
nullable: true nullable: true
last_pulled: last_pulled:
description: Time when this image was last pulled. Note this is updated at description:
Time when this image was last pulled. Note this is updated at
most once per hour. most once per hour.
type: string type: string
example: 2021-02-24T23:16:10.200008Z example: 2021-02-24T23:16:10.200008Z
nullable: true nullable: true
status: status:
description: The status of the image based on its last activity against the description:
The status of the image based on its last activity against the
`active_from` time. `active_from` time.
type: string type: string
enum: enum:
@ -1183,10 +1145,9 @@ components:
type: string type: string
example: latest example: latest
is_current: is_current:
description: > description: |
`true` if the tag currently points to this image. `true` if the tag currently points to this image.
`false` if it has been overwritten to point at a different image. `false` if it has been overwritten to point at a different image.
type: boolean type: boolean
example: true example: true
@ -1195,16 +1156,16 @@ components:
type: object type: object
properties: properties:
dry_run: dry_run:
description: If `true` then will check and return errors and unignored warnings description:
If `true` then will check and return errors and unignored warnings
for the deletion request but will not delete any images. for the deletion request but will not delete any images.
type: boolean type: boolean
example: false example: false
active_from: active_from:
description: > description: |
Sets the time from which an image must have been pushed or pulled to Sets the time from which an image must have been pushed or pulled to
be counted as active. be counted as active.
Defaults to 1 month before the current time. Defaults to 1 month before the current time.
type: string type: string
example: 2020-12-01T12:00:00Z example: 2020-12-01T12:00:00Z
@ -1226,19 +1187,15 @@ components:
type: string type: string
example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr
ignore_warnings: ignore_warnings:
description: > description: |
Warnings to ignore. If a warning is not ignored then no deletions Warnings to ignore. If a warning is not ignored then no deletions will happen and the
will happen and the warning is returned in the response. warning is returned in the response.
These warnings include: These warnings include:
- is_active: warning when attempting to delete an image that is marked as active.
* is_active: warning when attempting to delete an image that is marked as active. - current_tag: warning when attempting to delete an image that has one or more current
tags in the repository.
* current_tag: warning when attempting to delete an image that has one or more current tags in the repository.
Warnings can be copied from the response to the request. Warnings can be copied from the response to the request.
type: array type: array
@ -1320,14 +1277,16 @@ components:
type: object type: object
properties: properties:
errors: errors:
description: Errors from validating delete request. These cannot be description:
Errors from validating delete request. These cannot be
ignored. ignored.
type: array type: array
items: items:
type: object type: object
properties: properties:
repository: repository:
description: Name of the repository of the image that caused description:
Name of the repository of the image that caused
the error. the error.
type: string type: string
example: myrepo example: myrepo
@ -1344,18 +1303,15 @@ components:
- child_manifest - child_manifest
example: not_found example: not_found
warnings: warnings:
description: > description: |
Warnings that can be ignored. Warnings that can be ignored.
These warnings include: These warnings include:
- is_active: warning when attempting to delete an image that is marked as
* is_active: warning when attempting to delete an image that is marked as active. active.
- current_tag: warning when attempting to delete an image that has one or
more current tags in the repository.
* current_tag: warning when attempting to delete an image that has one or more current tags in the repository.
Warnings can be copied from the response to the request. Warnings can be copied from the response to the request.
type: array type: array
@ -1363,7 +1319,8 @@ components:
type: object type: object
properties: properties:
repository: repository:
description: Name of the repository of the image that caused description:
Name of the repository of the image that caused
the warning. the warning.
type: string type: string
example: myrepo example: myrepo
@ -1536,8 +1493,8 @@ components:
example: My read only token example: My read only token
scopes: scopes:
type: array type: array
description: 'Valid scopes: "repo:admin", "repo:write", "repo:read", description: |
"repo:public_read"' Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public_read"
example: example:
- repo:read - repo:read
items: items:
@ -1605,32 +1562,25 @@ components:
properties: properties:
description: description:
type: string type: string
description: The description of a repository, as displayed below the repository description:
The description of a repository, as displayed below the repository
name. name.
example: Hello World! (an example of minimal Dockerization) example: Hello World! (an example of minimal Dockerization)
full_description: full_description:
type: string type: string
description: The full description displayed on the repository page. Markdown description:
The full description displayed on the repository page. Markdown
accepted. accepted.
example: > example: |
# Quick reference # Quick reference
- Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
* Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
# Example output # Example output
``` ```
$ docker run hello-world $ docker run hello-world
Hello from Docker! Hello from Docker!
This message shows that your installation appears to be working correctly. This message shows that your installation appears to be working correctly.
``` ```
repository: repository:
type: object type: object
@ -1657,24 +1607,15 @@ components:
full_description: full_description:
type: string type: string
description: Description (readme) of the repository, in Markdown description: Description (readme) of the repository, in Markdown
example: >- example: |
# Quick reference # Quick reference
- Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
* Maintained by: [the Docker Community](https://github.com/docker-library/hello-world)
# Example output # Example output
``` ```
$ docker run hello-world $ docker run hello-world
Hello from Docker! Hello from Docker!
This message shows that your installation appears to be working correctly. This message shows that your installation appears to be working correctly.
``` ```