diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 94f3366a544..7d0099ab8a6 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -6,112 +6,104 @@ info: url: https://docs.docker.com/assets/images/logo-docker-main.png href: /reference description: | - Docker Hub is a service provided by Docker for finding and sharing container - images with your team. + Docker Hub is a service provided by Docker for finding and sharing container images with your team. It is the world's largest library and community for container images. - In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), - - Docker provides an API that allows you to interact with Docker Hub. + In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), Docker provides an API that allows you to interact with Docker Hub. Browse through the Docker Hub API documentation to explore the supported endpoints. - +servers: + - description: Docker HUB API + x-audience: public + url: https://hub.docker.com tags: - name: resources x-displayName: Resources description: | The following resources are available to interact with the documented API: - - - Docker Hub CLI tool (currently experimental) + - [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental) - name: rate-limiting x-displayName: Rate Limiting description: | The Docker Hub API is limited on the amount of requests you can perform per minute against it. - If you haven't hit the limit, each request to the API will return the - - following headers in the response. + If you haven't hit the limit, each request to the API will return the following headers in the response. - `X-RateLimit-Limit` - The limit of requests per minute. - `X-RateLimit-Remaining` - The remaining amount of calls within the limit period. - `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 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 - - download, or pull rate limiting. To learn more about Docker Hub pull rate - - limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/). + **Note**: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. + To learn more about Docker Hub pull rate limiting, see [Docker Hub download rate limit](https://docs.docker.com/docker-hub/download-rate-limit/). - name: authentication x-displayName: Authentication description: | - Most Docker Hub API endpoints require you to authenticate using your - Docker credentials before using them. + Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them. - Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending - on your plan (Personal, Pro, or Team) and your account's permissions. + Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, 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). - name: access-tokens x-displayName: Personal Access Tokens description: | - The Personal Access Token endpoints lets you manage personal access tokens. For more - information, see [Access Tokens](https://docs.docker.com/security/for-developers/access-tokens/). + The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/for-developers/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 - For each scope grouping (in this case "repo"), you only need to define 1 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. + For each scope grouping (in this case "repo"), you only need to define 1 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. - ***Treat your personal access token like your password and keep it secret. You cannot retrieve - your token after it is generated.*** + ***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.*** - name: audit-logs x-displayName: Audit Logs description: | - The Audit Logs API endpoints allow you to query audit log events across a - namespace. + The Audit Logs API endpoints allow you to query audit log events across a namespace. For more information, see [Audit Log](https://docs.docker.com/admin/organization/activity-logs/). - name: org-settings x-displayName: Org Settings description: | - The Org Settings API endpoints allow you to manage your organization's - settings. + The Org Settings API endpoints allow you to manage your organization's settings. - name: repositories x-displayName: Repositories description: | - The repository endpoints allow you to access your repository's - tags. + The repository endpoints allow you to access your repository's tags. + - name: orgs + x-displayName: Organizations + x-audience: public + description: | + The organization endpoints allow you to interact with and manage your organizations. + + For more information, see [Organization administration overview](https://docs.docker.com/admin/organization/). + - name: groups + x-displayName: Groups (Teams) + x-audience: public + description: | + The groups endpoints allow you to manage your organization's teams and their members. + + For more information, seee [Create and manage a team](https://docs.docker.com/admin/organization/manage-a-team/). + - name: invites + x-displayName: Invites + x-audience: public + description: | + The invites endpoints allow you to manage invites for users to join your Docker organization. + + For more information, see [Invite members](https://docs.docker.com/admin/organization/members/#invite-members). - name: scim x-displayName: SCIM + x-audience: public description: | SCIM is a provisioning system that lets you manage users within your identity provider (IdP). + For more information, see [System for Cross-domain Identity management](https://docs.docker.com/security/for-admins/provisioning/scim/). -x-tagGroups: - - name: General - tags: - - resources - - rate-limiting - - name: API - tags: - - authentication - - access-tokens - - images - - audit-logs - - org-settings - - repositories - - scim paths: /v2/users/login: post: @@ -120,36 +112,33 @@ paths: summary: Create an authentication token operationId: PostUsersLogin description: | - 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}`. - Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list - images in a private repository. - - _**As of Monday, September 16, 2024, this route requires a PAT instead of a password if your organization has - SSO enforced.**_ + Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. + + _**As of September 16, 2024, this route requires a PAT instead of a password if your organization has SSO enforced.**_ requestBody: content: application/json: schema: - $ref: "#/components/schemas/UsersLoginRequest" + $ref: '#/components/schemas/UsersLoginRequest' description: Login details. required: true responses: - 200: + '200': description: Authentication successful content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + $ref: '#/components/schemas/PostUsersLoginSuccessResponse' + '401': description: Authentication failed or second factor required content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginErrorResponse" + $ref: '#/components/schemas/PostUsersLoginErrorResponse' /v2/users/2fa-login: post: tags: @@ -157,8 +146,7 @@ paths: summary: Second factor authentication operationId: PostUsers2FALogin description: | - When a user has two-factor authentication (2FA) enabled, this is the second call to perform after - `/v2/users/login` call. + When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/users/login` call. Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. @@ -169,22 +157,22 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/Users2FALoginRequest" + $ref: '#/components/schemas/Users2FALoginRequest' description: Login details. required: true responses: - 200: + '200': description: Authentication successful content: application/json: schema: - $ref: "#/components/schemas/PostUsersLoginSuccessResponse" - 401: + $ref: '#/components/schemas/PostUsersLoginSuccessResponse' + '401': description: Authentication failed or second factor required content: application/json: schema: - $ref: "#/components/schemas/PostUsers2FALoginErrorResponse" + $ref: '#/components/schemas/PostUsers2FALoginErrorResponse' /v2/access-tokens: post: summary: Create a personal access token @@ -195,19 +183,19 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/createAccessTokenRequest" + $ref: '#/components/schemas/createAccessTokenRequest' required: true responses: - 201: + '201': description: Created content: application/json: schema: - $ref: "#/components/schemas/createAccessTokensResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/createAccessTokensResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' get: summary: Get a list of personal access tokens description: Returns a paginated list of personal access tokens. @@ -225,16 +213,16 @@ paths: type: number default: 10 responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/getAccessTokensResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/getAccessTokensResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' /v2/access-tokens/{uuid}: parameters: - in: path @@ -245,49 +233,48 @@ paths: patch: summary: Update a personal access token description: | - Updates a personal access token partially. You can either update the - token's label or enable/disable it. + Updates a personal access token partially. You can either update the token's label or enable/disable it. tags: - access-tokens requestBody: content: application/json: schema: - $ref: "#/components/schemas/patchAccessTokenRequest" + $ref: '#/components/schemas/patchAccessTokenRequest' required: true responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/patchAccessTokenResponse" - 400: - $ref: "#/components/responses/BadRequest" - 401: - $ref: "#/components/responses/Unauthorized" + $ref: '#/components/schemas/patchAccessTokenResponse' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' get: summary: Get a personal access token description: Returns a personal access token by UUID. tags: - access-tokens responses: - 200: + '200': description: OK content: application/json: schema: allOf: - - $ref: "#/components/schemas/accessToken" + - $ref: '#/components/schemas/accessToken' - type: object properties: token: type: string - example: "" - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + example: '' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' delete: summary: Delete a personal access token description: | @@ -295,24 +282,24 @@ paths: tags: - access-tokens responses: - 204: + '204': description: A successful response. - 401: - $ref: "#/components/responses/Unauthorized" - 404: - $ref: "#/components/responses/NotFound" + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' /v2/auditlogs/{account}: get: summary: Returns list of audit log events description: Get audit log events for a given namespace. operationId: AuditLogs_GetAuditLogs responses: - 200: + '200': description: A successful response. content: application/json: schema: - $ref: "#/components/schemas/GetAuditLogsResponse" + $ref: '#/components/schemas/GetAuditLogsResponse' examples: response: value: @@ -324,12 +311,11 @@ paths: data: digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa tag: latest - timestamp: 2021-02-19T01:34:35Z - action_description: - pushed the tag latest with the digest - sha256:c1ae9c435032a to the repository docker/example - 429: - description: "" + timestamp: '2021-02-19T01:34:35Z' + action_description: | + pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example + '429': + description: '' content: application/json: schema: {} @@ -338,8 +324,8 @@ paths: value: detail: Rate limit exceeded error: false - 500: - description: "" + '500': + description: '' content: application/json: schema: {} @@ -348,7 +334,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: '#/components/schemas/rpcStatus' parameters: - name: account description: Namespace to query audit logs for. @@ -357,27 +343,22 @@ paths: schema: type: string - name: action - description: - action name one of ["repo.tag.push", ...]. Optional parameter to - filter specific audit log actions. + description: | + action name one of ["repo.tag.push", ...]. Optional parameter to filter specific audit log actions. in: query required: false schema: type: string - name: name - description: - name. Optional parameter to filter audit log events to a specific - name. For repository events, this is the name of the repository. For - organization events, this is the name of the organization. For team - member events, this is the username of the team member. + description: | + name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member. in: query required: false schema: type: string - name: actor - description: - actor name. Optional parameter to filter audit log events to the - specific user who triggered the event. + description: | + actor name. Optional parameter to filter audit log events to the specific user who triggered the event. in: query required: false schema: @@ -417,17 +398,16 @@ paths: /v2/auditlogs/{account}/actions: get: summary: Returns list of audit log actions - description: - Get audit log actions for a namespace to be used as a filter for - querying audit events. + description: | + Get audit log actions for a namespace to be used as a filter for querying audit events. operationId: AuditLogs_GetAuditActions responses: - 200: + '200': description: A successful response. content: application/json: schema: - $ref: "#/components/schemas/GetAuditActionsResponse" + $ref: '#/components/schemas/GetAuditActionsResponse' examples: response: value: @@ -474,8 +454,8 @@ paths: description: contains image tag delete events label: Tag Deleted label: Repository - 429: - description: "" + '429': + description: '' content: application/json: schema: {} @@ -484,8 +464,8 @@ paths: value: detail: Rate limit exceeded error: false - 500: - description: "" + '500': + description: '' content: application/json: schema: {} @@ -494,7 +474,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/rpcStatus" + $ref: '#/components/schemas/rpcStatus' parameters: - name: account description: Namespace to query audit log actions for. @@ -519,23 +499,22 @@ paths: tags: - org-settings responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/orgSettings" - 401: - $ref: "#/components/responses/Unauthorized" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + $ref: '#/components/schemas/orgSettings' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' put: summary: Update organization settings description: | - Updates an organization's settings. Some settings are only used when the - organization is on a business plan. + Updates an organization's settings. Some settings are only used when the organization is on a business plan. ***Only users with administrative privileges for the organization (owner role) can modify these settings.*** @@ -552,7 +531,7 @@ paths: properties: restricted_images: allOf: - - $ref: "#/components/schemas/restricted_images" + - $ref: '#/components/schemas/restricted_images' - type: object required: - enabled @@ -560,194 +539,713 @@ paths: - allow_verified_publishers required: true responses: - 200: + '200': description: OK content: application/json: schema: - $ref: "#/components/schemas/orgSettings" - 401: - $ref: "#/components/responses/Unauthorized" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - - + $ref: '#/components/schemas/orgSettings' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' /v2/namespaces/{namespace}/repositories/{repository}/tags: parameters: - - $ref: "#/components/parameters/namespace" - - $ref: "#/components/parameters/repository" + - $ref: '#/components/parameters/namespace' + - $ref: '#/components/parameters/repository' get: - summary: "List repository tags" - tags: [ repositories ] + summary: List repository tags + tags: + - repositories parameters: - - $ref: "#/components/parameters/page" - - $ref: "#/components/parameters/page_size" + - in: query + name: page + required: false + schema: + type: integer + description: Page number to get. Defaults to 1. + - in: query + name: page_size + required: false + schema: + type: integer + description: Number of items to get per page. Defaults to 10. Max of 100. responses: - 200: - $ref: "#/components/responses/list_tags" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + '200': + $ref: '#/components/responses/list_tags' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' head: - summary: "Check repository tags" - tags: [ repositories ] + summary: Check repository tags + tags: + - repositories responses: - 200: - description: "Repository contains tags" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - + '200': + description: Repository contains tags + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}: parameters: - - $ref: "#/components/parameters/namespace" - - $ref: "#/components/parameters/repository" - - $ref: "#/components/parameters/tag" + - $ref: '#/components/parameters/namespace' + - $ref: '#/components/parameters/repository' + - $ref: '#/components/parameters/tag' get: - summary: "Read repository tag" - tags: [ repositories ] + summary: Read repository tag + tags: + - repositories responses: - 200: - $ref: "#/components/responses/get_tag" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" + '200': + $ref: '#/components/responses/get_tag' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' head: - summary: "Check repository tag" - tags: [ repositories ] + summary: Check repository tag + tags: + - repositories responses: - 200: - description: "Repository tag exists" - 403: - $ref: "#/components/responses/Forbidden" - 404: - $ref: "#/components/responses/NotFound" - - + '200': + description: Repository tag exists + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' + /v2/orgs/{org_name}/members: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/search' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - $ref: '#/components/parameters/invites' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/role' + get: + summary: List org members + description: | + Returns a list of members for an organization" + tags: + - orgs + responses: + '200': + description: List of members + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/org_member_paginated' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/members/export: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: Export org members CSV + description: | + Export members of an organization as a CSV + tags: + - orgs + responses: + '200': + description: Exported members + content: + text/csv: + schema: + type: array + items: + type: object + required: + - Name + - Username + - Email + - Type + - Role + - Date Joined + properties: + Name: + type: string + description: First and last name of the member + Username: + type: string + description: Username of the member + Email: + type: string + description: Email address of the member + Type: + type: string + description: Type of the member + enum: + - Invitee + - User + Permission: + type: string + description: Permission of the member + enum: + - Owner + - Member + Teams: + type: string + description: Comma-separated list of teams the member is part of + example: team-1, team-2 + Date Joined: + type: string + description: Date the member joined the organization + example: 2020-01-01 15:00:51.193355 +0000 UTC + headers: + Content-Disposition: + schema: + type: string + example: attachment;filename="{org_name}-members-{timestamp}.csv" + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/members/{username}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/username' + put: + summary: Update org member (role) + description: | + Updates the role of a member in the organization. + ***Only users in the "owners" group of the organization can use this endpoint.*** + tags: + - orgs + requestBody: + required: true + content: + application/json: + schema: + required: + - role + properties: + role: + type: string + description: Role of the member + enum: + - owner + - editor + - member + responses: + '200': + description: Member role updated + content: + application/json: + schema: + $ref: '#/components/schemas/org_member' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + delete: + summary: Remove member from org + description: | + Removes the member from the org, ie. all groups in the org, unless they're the last owner + tags: + - orgs + responses: + '204': + description: Member removed successfully + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/invites: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: List org invites + description: | + Return all pending invites for a given org, only team owners can call this endpoint + tags: + - invites + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/invite' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/groups: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + get: + summary: Get groups of an organization + tags: + - groups + parameters: + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - in: query + name: username + schema: + type: string + description: Get groups for the specified username in the organization. + - in: query + name: search + schema: + type: string + description: Get groups for the specified group in the organization. + responses: + '200': + description: '' + content: + application/json: + schema: + properties: + count: + type: number + example: 1 + next: + type: string + example: null + previous: + type: string + example: null + results: + type: array + items: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + post: + summary: Create a new group + description: Create a new group within an organization. + tags: + - groups + requestBody: + content: + application/json: + schema: + required: + - name + properties: + name: + type: string + description: + type: string + responses: + '201': + description: Group created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + /v2/orgs/{org_name}/groups/{group_name}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + get: + summary: Get a group of an organization + tags: + - groups + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + put: + summary: Update the details for an organization group + tags: + - groups + requestBody: + content: + application/json: + schema: + required: + - name + properties: + name: + type: string + description: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + patch: + summary: Update some details for an organization group + tags: + - groups + requestBody: + content: + application/json: + schema: + properties: + name: + type: string + description: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/org_group' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + delete: + summary: Delete an organization group + tags: + - groups + responses: + '204': + description: Group deleted successfully + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/orgs/{org_name}/groups/{group_name}/members: + x-audience: public + get: + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/page_size' + - in: query + name: search + schema: + type: string + description: Search members by username, full_name or email. + summary: List members of a group + description: | + List the members (users) that are in a group. + If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails. + tags: + - groups + responses: + '200': + description: '' + content: + application/json: + schema: + properties: + count: + type: number + example: 1 + next: + type: string + example: null + previous: + type: string + example: null + results: + type: array + items: + $ref: '#/components/schemas/group_member' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + post: + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + summary: Adds a member to a group + tags: + - groups + requestBody: + $ref: '#/components/requestBodies/add_member_to_org_group' + responses: + '200': + description: OK + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '500': + $ref: '#/components/responses/internal_error' + /v2/orgs/{org_name}/groups/{group_name}/members/{username}: + x-audience: public + parameters: + - $ref: '#/components/parameters/org_name' + - $ref: '#/components/parameters/group_name' + - $ref: '#/components/parameters/username' + delete: + summary: Removes a user from a group + tags: + - groups + responses: + '204': + description: User removed successfully + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/{id}: + x-audience: public + parameters: + - in: path + name: id + required: true + schema: + type: string + delete: + summary: Cancel an invite + description: | + Mark the invite as cancelled so it doesn't show up on the list of pending invites + tags: + - invites + responses: + '204': + description: '' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/{id}/resend: + x-audience: public + parameters: + - in: path + name: id + schema: + type: string + required: true + patch: + summary: Resend an invite + description: | + Resend a pending invite to the user, any org owner can resend an invite + tags: + - invites + responses: + '204': + description: '' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + /v2/invites/bulk: + x-audience: public + parameters: + - $ref: '#/components/parameters/bulk_invite' + post: + summary: Bulk create invites + description: | + Create multiple invites by emails or DockerIDs. Only a team owner can create invites. + tags: + - invites + requestBody: + $ref: '#/components/requestBodies/bulk_invite_request' + responses: + '202': + description: Accepted + content: + application/json: + schema: + type: object + properties: + invitees: + $ref: '#/components/schemas/bulk_invite' + '400': + $ref: '#/components/responses/bad_request' + '409': + $ref: '#/components/responses/conflict' /v2/scim/2.0/ServiceProviderConfig: + x-audience: public get: summary: Get service provider config description: | Returns a service provider config for Docker's configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: + '200': $ref: '#/components/responses/scim_get_service_provider_config_resp' - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/ResourceTypes: + x-audience: public get: summary: List resource types description: | Returns all resource types supported for the SCIM configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_resource_types_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_resource_types_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/ResourceTypes/{name}: + x-audience: public get: summary: Get a resource type description: | Returns a resource type by name. - tags: [ scim ] + tags: + - scim parameters: - name: name in: path schema: type: string example: User + required: true security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_resource_type_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_resource_type_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Schemas: + x-audience: public get: summary: List schemas description: | Returns all schemas supported for the SCIM configuration. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_schemas_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_schemas_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Schemas/{id}: + x-audience: public get: summary: Get a schema description: | Returns a schema by ID. - tags: [ scim ] + tags: + - scim parameters: - name: id in: path schema: type: string example: urn:ietf:params:scim:schemas:core:2.0:User + required: true security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_schema_resp" - 401: - $ref: "#/components/responses/scim_unauthorized" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_schema_resp' + '401': + $ref: '#/components/responses/scim_unauthorized' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Users: + x-audience: public get: summary: List users description: | - List users, returns paginated users for an organization. Use `startIndex` - and `count` query parameters to receive paginated results. + Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results. + + **Sorting:** - **Sorting:**
- Sorting lets you specify the order of returned resources by specifying - a combination of `sortBy` and `sortOrder` query parameters. + Sorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters. - The `sortBy` parameter specifies the attribute whose value will be used - to order the returned responses. The `sortOrder` parameter defines the - order in which the `sortBy` parameter is applied. Allowed values are - "ascending" and "descending". + The `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are "ascending" and "descending". - **Filtering:**
- You can request a subset of resources by specifying the `filter` query - parameter containing a filter expression. Attribute names and attribute - operators used in filters are case insensitive. The filter parameter - must contain at least one valid expression. Each expression must contain - an attribute name followed by an attribute operator and an optional - value. + **Filtering:** + + You can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value. Supported operators are listed below. @@ -759,16 +1257,17 @@ paths: - `or` Logical "or" - `not` "Not" function - `()` Precedence grouping - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] parameters: - name: startIndex in: query schema: type: integer minimum: 1 - description: "" + description: '' example: 1 - name: count in: query @@ -776,15 +1275,15 @@ paths: type: integer minimum: 1 maximum: 200 - description: "" + description: '' example: 10 - name: filter in: query schema: type: string - description: "" + description: '' example: userName eq "jon.snow@docker.com" - - $ref: "#/components/parameters/scim_attributes" + - $ref: '#/components/parameters/scim_attributes' - name: sortOrder in: query schema: @@ -796,100 +1295,96 @@ paths: in: query schema: type: string - description: "User attribute to sort by." + description: User attribute to sort by. example: userName responses: - 200: - $ref: "#/components/responses/scim_get_users_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" - + '200': + $ref: '#/components/responses/scim_get_users_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' post: summary: Create user description: | - Creates a user. If the user already exists by email, they are assigned - to the organization on the "company" team. - tags: [ scim ] + Creates a user. If the user already exists by email, they are assigned to the organization on the "company" team. + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] requestBody: - $ref: "#/components/requestBodies/scim_create_user_request" + $ref: '#/components/requestBodies/scim_create_user_request' responses: - 201: - $ref: "#/components/responses/scim_create_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 409: - $ref: "#/components/responses/scim_conflict" - 500: - $ref: "#/components/responses/scim_error" - + '201': + $ref: '#/components/responses/scim_create_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '409': + $ref: '#/components/responses/scim_conflict' + '500': + $ref: '#/components/responses/scim_error' /v2/scim/2.0/Users/{id}: + x-audience: public parameters: - - $ref: "#/components/parameters/scim_user_id" + - $ref: '#/components/parameters/scim_user_id' get: summary: Get a user description: | Returns a user by ID. - tags: [ scim ] + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] responses: - 200: - $ref: "#/components/responses/scim_get_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 500: - $ref: "#/components/responses/scim_error" + '200': + $ref: '#/components/responses/scim_get_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '500': + $ref: '#/components/responses/scim_error' put: summary: Update a user description: | - Updates a user. Use this route to change the user's name, activate, - and deactivate the user. - tags: [ scim ] + Updates a user. This route is used to change the user's name, activate, and deactivate the user. + tags: + - scim security: - - bearerSCIMAuth: [ ] + - bearerSCIMAuth: [] requestBody: - $ref: "#/components/requestBodies/scim_update_user_request" + $ref: '#/components/requestBodies/scim_update_user_request' responses: - 200: - $ref: "#/components/responses/scim_update_user_resp" - 400: - $ref: "#/components/responses/scim_bad_request" - 401: - $ref: "#/components/responses/scim_unauthorized" - 403: - $ref: "#/components/responses/scim_forbidden" - 404: - $ref: "#/components/responses/scim_not_found" - 409: - $ref: "#/components/responses/scim_conflict" - 500: - $ref: "#/components/responses/scim_error" - - -servers: - - url: https://hub.docker.com/ + '200': + $ref: '#/components/responses/scim_update_user_resp' + '400': + $ref: '#/components/responses/scim_bad_request' + '401': + $ref: '#/components/responses/scim_unauthorized' + '403': + $ref: '#/components/responses/scim_forbidden' + '404': + $ref: '#/components/responses/scim_not_found' + '409': + $ref: '#/components/responses/scim_conflict' + '500': + $ref: '#/components/responses/scim_error' components: responses: BadRequest: @@ -897,100 +1392,144 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ValueError" + $ref: '#/components/schemas/ValueError' Unauthorized: description: Unauthorized content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: - $ref: "#/components/schemas/Error" + $ref: '#/components/schemas/Error' NotFound: description: Not Found content: application/json: schema: - $ref: "#/components/schemas/Error" - + $ref: '#/components/schemas/Error' + list_tags: + description: list repository tags + content: + application/json: + schema: + $ref: '#/components/schemas/paginated_tags' + get_tag: + description: repository tag + content: + application/json: + schema: + $ref: '#/components/schemas/tag' + bad_request: + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/error' + unauthorized: + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/error' + forbidden: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/error' + not_found: + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/error' + conflict: + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/error' + internal_error: + description: Internal + content: + application/json: + schema: + $ref: '#/components/schemas/error' scim_bad_request: description: Bad Request content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "400" + example: '400' scimType: type: string - description: Some types of errors will return this per the - specification. + description: Some types of errors will return this per the specification. scim_unauthorized: description: Unauthorized content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "401" + example: '401' scim_forbidden: description: Forbidden content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "403" + example: '403' scim_not_found: description: Not Found content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "404" + example: '404' scim_conflict: description: Conflict content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "409" + example: '409' scim_error: description: Internal Error content: application/scim+json: schema: allOf: - - $ref: "#/components/schemas/scim_error" + - $ref: '#/components/schemas/scim_error' - properties: status: - example: "500" - + example: '500' scim_get_service_provider_config_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_service_provider_config" - + $ref: '#/components/schemas/scim_service_provider_config' scim_get_resource_types_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1000,24 +1539,22 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: - $ref: "#/components/schemas/scim_resource_type" - + $ref: '#/components/schemas/scim_resource_type' scim_get_resource_type_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_resource_type" - + $ref: '#/components/schemas/scim_resource_type' scim_get_schemas_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1027,24 +1564,22 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: - $ref: "#/components/schemas/scim_schema" - + $ref: '#/components/schemas/scim_schema' scim_get_schema_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_schema" - + $ref: '#/components/schemas/scim_schema' scim_get_users_resp: - description: "" + description: '' content: application/scim+json: schema: @@ -1054,7 +1589,8 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 @@ -1067,43 +1603,25 @@ components: resources: type: array items: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_create_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_get_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - + $ref: '#/components/schemas/scim_user' scim_update_user_resp: - description: "" + description: '' content: application/scim+json: schema: - $ref: "#/components/schemas/scim_user" - - list_tags: - description: "list repository tags" - content: - application/json: - schema: - $ref: "#/components/schemas/paginated_tags" - - get_tag: - description: "repository tag" - content: - application/json: - schema: - $ref: "#/components/schemas/tag" - + $ref: '#/components/schemas/scim_user' schemas: UsersLoginRequest: description: User login details @@ -1117,11 +1635,10 @@ components: type: string example: myusername password: - description: - The password or personal access token (PAT) of the Docker Hub - account to authenticate with. + description: | + The password or personal access token (PAT) of the Docker Hub account to authenticate with. type: string - example: hunter2 + example: p@ssw0rd PostUsersLoginSuccessResponse: description: successful user login response type: object @@ -1129,7 +1646,6 @@ components: token: description: | Created authentication token. - This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c @@ -1146,10 +1662,8 @@ components: example: Incorrect authentication credentials nullable: false login_2fa_token: - 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 - enabled. + 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 enabled. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c nullable: true @@ -1165,9 +1679,8 @@ components: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c code: - description: - The Time-based One-Time Password of the Docker Hub account to - authenticate with. + description: | + The Time-based One-Time Password of the Docker Hub account to authenticate with. type: string example: 123456 PostUsers2FALoginErrorResponse: @@ -1179,369 +1692,6 @@ components: type: string example: Incorrect authentication credentials nullable: false - ErrorInfo: - description: Context information for an error used for diagnostics. - type: object - properties: - api_call_docker_id: - description: ID of docker user. - type: string - api_call_name: - description: Name of the API operation called. - type: string - api_call_start: - description: Date/time of call start. - type: string - api_call_txnid: - description: Unique ID for this call. - type: string - ErrorResponse: - description: Represents an error. - type: object - properties: - txnid: - description: Unique ID for this call. - type: string - message: - description: The error message. - type: string - errinfo: - $ref: "#/components/schemas/ErrorInfo" - ErrorDetail: - description: Error with a detail field. - type: object - properties: - detail: - description: The error message. - type: string - GetNamespaceRepositoryImagesSummaryResponse: - description: Summary information for images in a repository. - type: object - properties: - active_from: - description: - Time from which an image must have been pushed or pulled to be - counted as active. - type: string - example: 2021-01-25T14:25:37.076343059Z - statistics: - type: object - properties: - total: - description: Number of images in this repository. - type: integer - example: 3 - active: - description: Number of images counted as active in this repository. - type: integer - example: 2 - inactive: - description: Number of images counted as inactive in this repository. - type: integer - example: 1 - GetNamespaceRepositoryImagesResponse: - description: Paginated list of images in a repository. - type: object - properties: - count: - description: Total count of images in the repository. - type: integer - example: 100 - next: - description: - Link to the next page with the same query parameters if there are - more images. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=4&page_size=20 - nullable: true - previous: - description: - Link to the previous page with the same query parameters if not on - first page. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images?&page=2&page_size=20 - nullable: true - results: - type: array - description: Image details. - items: - type: object - properties: - namespace: - description: The repository namespace. - type: string - example: mynamespace - repository: - description: The repository name. - type: string - example: myrepo - digest: - description: The image's digest. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - tags: - description: The current and historical tags for this image. - type: array - items: - type: object - properties: - tag: - description: The tag. - type: string - example: latest - is_current: - description: | - `true` if the tag currently points to this image. - - `false` if it has been overwritten to point at a different image. - type: boolean - example: true - last_pushed: - description: Time when this image was last pushed. - type: string - example: 2021-02-24T22:05:27.526308Z - nullable: true - last_pulled: - description: - Time when this image was last pulled. Note this is updated at - most once per hour. - type: string - example: 2021-02-24T23:16:10.200008Z - nullable: true - status: - description: - The status of the image based on its last activity against the - `active_from` time. - type: string - enum: - - active - - inactive - example: active - GetNamespaceRepositoryImagesTagsResponse: - description: Paginated list of tags for this repository. - type: object - properties: - count: - description: Total count of tags for this image. - type: integer - example: 100 - next: - description: Link to the next page if there are more tags. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images/sha256:mydigest/tags?&page=4&page_size=20 - nullable: true - previous: - description: Link to the previous page if not on first page. - type: string - example: https://hub.docker.com/v2/namespaces/mynamespace/repositories/myrepo/images/sha256:mydigest/tags?&page=2&page_size=20 - nullable: true - results: - description: The current and historical tags for this image. - type: array - items: - type: object - properties: - tag: - description: The tag. - type: string - example: latest - is_current: - description: | - `true` if the tag currently points to this image. - - `false` if it has been overwritten to point at a different image. - type: boolean - example: true - PostNamespacesDeleteImagesRequest: - description: Delete images request. - type: object - properties: - dry_run: - description: - If `true` then will check and return errors and unignored warnings - for the deletion request but will not delete any images. - type: boolean - example: false - active_from: - description: | - Sets the time from which an image must have been pushed or pulled to - be counted as active. - - Defaults to 1 month before the current time. - type: string - example: 2020-12-01T12:00:00Z - manifests: - description: Image manifests to delete. - type: array - items: - type: object - required: - - repository - - digest - properties: - repository: - description: Name of the repository to delete the image from. - type: string - example: myrepo - digest: - description: Digest of the image to delete. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - ignore_warnings: - description: | - Warnings to ignore. If a warning is not ignored then no deletions will happen and the - warning is returned in the response. - - These warnings include: - - - 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. - - Warnings can be copied from the response to the request. - type: array - items: - type: object - required: - - repository - - digest - - warning - properties: - repository: - description: Name of the repository of the image to ignore the warning for. - type: string - example: myrepo - digest: - description: Digest of the image to ignore the warning for. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - warning: - description: Warning to ignore. - type: string - enum: - - is_active - - current_tag - example: current_tag - tags: - description: Current tags to ignore. - type: array - items: - type: string - example: latest - PostNamespacesDeleteImagesResponseSuccess: - description: Successful delete images response. - type: object - properties: - dry_run: - description: Whether the request was a dry run or not. - type: boolean - example: false - metrics: - type: object - properties: - manifest_deletes: - description: Number of manifests deleted. - type: integer - example: 3 - manifest_errors: - description: Number of manifests that failed to delete. - type: integer - example: 0 - tag_deletes: - description: Number of tags deleted. - type: integer - example: 1 - tag_errors: - description: Number of tags that failed to delete. - type: integer - example: 0 - PostNamespacesDeleteImagesResponseError: - description: Deletion not possible. - type: object - properties: - txnid: - description: Unique ID for this call. - type: string - message: - description: The error message. - type: string - errinfo: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - type: - description: Type of error. - type: string - example: validation - details: - type: object - properties: - errors: - description: - Errors from validating delete request. These cannot be - ignored. - type: array - items: - type: object - properties: - repository: - description: - Name of the repository of the image that caused - the error. - type: string - example: myrepo - digest: - description: Digest of the image that caused the error. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - error: - description: Error type. - type: string - enum: - - not_found - - unauthorized - - child_manifest - example: not_found - warnings: - description: | - Warnings that can be ignored. - - These warnings include: - - - 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. - - Warnings can be copied from the response to the request. - type: array - items: - type: object - properties: - repository: - description: - Name of the repository of the image that caused - the warning. - type: string - example: myrepo - digest: - description: Digest of the image that caused the warning. - type: string - example: sha256:1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr - warning: - description: Warning type. - type: string - enum: - - is_active - - current_tag - example: current_tag - tags: - description: Current tags if warning is `current_tag`. - type: array - items: - type: string - example: latest protobufAny: type: object properties: @@ -1561,7 +1711,7 @@ components: details: type: array items: - $ref: "#/components/schemas/protobufAny" + $ref: '#/components/schemas/protobufAny' AuditLogAction: type: object properties: @@ -1581,7 +1731,7 @@ components: actions: type: array items: - $ref: "#/components/schemas/AuditLogAction" + $ref: '#/components/schemas/AuditLogAction' description: List of audit log actions. label: type: string @@ -1592,7 +1742,7 @@ components: actions: type: object additionalProperties: - $ref: "#/components/schemas/AuditLogActions" + $ref: '#/components/schemas/AuditLogActions' description: Map of audit log actions. description: GetAuditActions response. GetAuditLogsResponse: @@ -1601,7 +1751,7 @@ components: logs: type: array items: - $ref: "#/components/schemas/AuditLog" + $ref: '#/components/schemas/AuditLog' description: List of audit log events. description: GetAuditLogs response. AuditLog: @@ -1659,7 +1809,7 @@ components: example: some user agent created_at: type: string - example: 2021-07-20T12:00:00.000000Z + example: '2021-07-20T12:00:00.000000Z' last_used: type: string example: null @@ -1703,7 +1853,7 @@ components: items: type: string createAccessTokensResponse: - $ref: "#/components/schemas/accessToken" + $ref: '#/components/schemas/accessToken' getAccessTokensResponse: type: object properties: @@ -1723,12 +1873,12 @@ components: type: array items: allOf: - - $ref: "#/components/schemas/accessToken" + - $ref: '#/components/schemas/accessToken' - type: object properties: token: type: string - example: "" + example: '' patchAccessTokenRequest: type: object properties: @@ -1741,12 +1891,12 @@ components: type: boolean example: false patchAccessTokenResponse: - $ref: "#/components/schemas/accessToken" + $ref: '#/components/schemas/accessToken' orgSettings: type: object properties: restricted_images: - $ref: "#/components/schemas/restricted_images" + $ref: '#/components/schemas/restricted_images' restricted_images: type: object properties: @@ -1767,29 +1917,29 @@ components: properties: digest: type: string - description: "image layer digest" + description: image layer digest nullable: true size: type: integer - description: "size of the layer" + description: size of the layer instruction: type: string - description: "Dockerfile instruction" + description: Dockerfile instruction image: type: object properties: architecture: type: string - description: "CPU architecture" + description: CPU architecture features: type: string - description: "CPU features" + description: CPU features variant: type: string - description: "CPU variant" + description: CPU variant digest: type: string - description: "image digest" + description: image digest nullable: true layers: type: array @@ -1797,80 +1947,83 @@ components: $ref: '#/components/schemas/layer' os: type: string - description: "operating system" + description: operating system os_features: type: string - description: "OS features" + description: OS features os_version: type: string - description: "OS version" + description: OS version size: type: integer - description: "size of the image" + description: size of the image status: type: string - enum: ["active", "inactive"] - description: "Status of the image" + enum: + - active + - inactive + description: Status of the image last_pulled: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last pull" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last pull nullable: true last_pushed: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last push" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last push nullable: true tag: type: object properties: id: type: integer - description: "tag ID" + description: tag ID images: type: object $ref: '#/components/schemas/image' creator: type: integer - description: "ID of the user that pushed the tag" + description: ID of the user that pushed the tag last_updated: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last update" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last update nullable: true last_updater: type: integer - description: "ID of the last user that updated the tag" + description: ID of the last user that updated the tag last_updater_username: type: string - description: "Hub username of the user that updated the tag" + description: Hub username of the user that updated the tag name: type: string - description: "name of the tag" + description: name of the tag repository: type: integer - description: "repository ID" + description: repository ID full_size: type: integer - description: "compressed size (sum of all layers) of the tagged image" + description: compressed size (sum of all layers) of the tagged image v2: type: string - description: "repository API version" + description: repository API version status: type: string - enum: ["active", "inactive"] - description: "whether a tag has been pushed to or pulled in the past month" + enum: + - active + - inactive + description: whether a tag has been pushed to or pulled in the past month tag_last_pulled: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last pull" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last pull nullable: true tag_last_pushed: type: string - example: "2021-01-05T21:06:53.506400Z" - description: "datetime of last push" + example: '2021-01-05T21:06:53.506400Z' + description: datetime of last push nullable: true - paginated_tags: allOf: - $ref: '#/components/schemas/page' @@ -1894,7 +2047,118 @@ components: type: string description: link to previous page of results if any nullable: true - + scim_schema_attribute: + type: object + properties: + name: + type: string + example: userName + type: + enum: + - string + - boolean + - complex + type: string + example: string + multiValued: + type: boolean + example: false + description: + type: string + example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. + required: + type: boolean + example: true + caseExact: + type: boolean + example: false + mutability: + type: string + example: readWrite + returned: + type: string + example: default + uniqueness: + type: string + example: server + scim_schema_parent_attribute: + allOf: + - $ref: '#/components/schemas/scim_schema_attribute' + - type: object + properties: + subAttributes: + type: array + items: + $ref: '#/components/schemas/scim_schema_attribute' + invite: + type: object + properties: + id: + type: string + description: uuid representing the invite id + example: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: + type: string + example: moby + invitee: + type: string + description: can either be a dockerID for registred users or an email for non-registred users + example: invitee@docker.com + org: + type: string + description: name of the org to join + example: docker + team: + type: string + description: name of the team (user group) to join + example: owners + created_at: + type: string + example: '2021-10-28T18:30:19.520861Z' + bulk_invite: + type: object + properties: + invitees: + type: array + description: A list of invitees + items: + type: object + properties: + invitee: + type: string + description: invitee email or Docker ID + status: + type: string + description: status of the invite or validation error + invite: + description: Invite data if successfully invited + $ref: '#/components/schemas/invite' + example: + invitees: + - invitee: invitee@docker.com + status: invited + invite: + id: e36eca69-4cc8-4f17-9845-ae8c2b832691 + inviter_username: moby + invitee: invitee@docker.com + org: docker + team: owners + created_at: '2021-10-28T18:30:19.520861Z' + - invitee: invitee2@docker.com + status: existing_org_member + - invitee: invitee3@docker.com + status: invalid_email_or_docker_id + error: + type: object + properties: + errinfo: + type: object + items: + type: string + detail: + type: string + message: + type: string scim_error: type: object properties: @@ -1909,7 +2173,180 @@ components: detail: type: string description: Details about why the request failed. - + user: + type: object + properties: + id: + type: string + example: 0ab70deb065a43fcacd55d48caa945d8 + description: The UUID trimmed + company: + type: string + example: Docker Inc + date_joined: + type: string + example: '2021-01-05T21:06:53.506400Z' + full_name: + type: string + example: Jon Snow + gravatar_email: + type: string + gravatar_url: + type: string + location: + type: string + profile_url: + type: string + type: + type: string + enum: + - User + - Org + example: User + username: + type: string + example: dockeruser + org_member: + allOf: + - $ref: '#/components/schemas/user' + properties: + email: + type: string + description: User's email address + example: example@docker.com + role: + type: string + description: User's role in the Organization + enum: + - Owner + - Member + - Invitee + example: Owner + groups: + type: array + description: Groups (Teams) that the user is member of + items: + type: string + example: + - developers + - owners + is_guest: + type: boolean + description: If the organization has verfied domains, members that have email addresses outside of those domains will be flagged as Guest member + example: false + primary_email: + type: string + description: User's email primary address + example: example@docker.com + deprecated: true + org_member_paginated: + type: object + properties: + count: + type: number + description: The total number of items that match with the search. + example: 120 + previous: + type: string + description: The URL or link for the previous page of items. + example: https://hub.docker.com/v2/some/resources/items?page=1&page_size=20 + next: + type: string + description: The URL or link for the next page of items. + example: https://hub.docker.com/v2/some/resources/items?page=3&page_size=20 + results: + type: array + description: List of accounts. + items: + $ref: '#/components/schemas/org_member' + org_group: + type: object + properties: + id: + type: number + example: 10 + description: Group ID + uuid: + type: string + description: UUID for the group + name: + type: string + example: mygroup + description: Name of the group + description: + type: string + example: Groups description + description: Description of the group + member_count: + type: number + example: 10 + description: Member count of the group + group_member: + type: object + properties: + id: + type: string + example: 0ab70deb065a43fcacd55d48caa945d8 + description: The UUID trimmed + company: + type: string + example: Docker Inc + date_joined: + type: string + example: '2021-01-05T21:06:53.506400Z' + full_name: + type: string + example: John Snow + gravatar_email: + type: string + gravatar_url: + type: string + location: + type: string + profile_url: + type: string + type: + type: string + enum: + - User + - Org + example: User + username: + type: string + example: dockeruser + email: + type: string + example: dockeruser@docker.com + email_address: + type: object + properties: + id: + type: number + user_id: + type: number + email: + type: string + example: dockeruser@docker.com + verified: + type: boolean + primary: + type: boolean + legacy_email_address: + allOf: + - $ref: '#/components/schemas/email_address' + - type: object + properties: + user: + type: string + example: dockeruser + email_with_username: + allOf: + - $ref: '#/components/schemas/email_address' + - type: object + properties: + username: + type: string + example: dockeruser scim_service_provider_config: type: object properties: @@ -1917,10 +2354,11 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ] + example: + - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig documentationUri: type: string - example: "" + example: '' patch: properties: supported: @@ -1974,11 +2412,10 @@ components: example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. specUri: type: string - example: "http://tools.ietf.org/html/rfc6750" + example: http://tools.ietf.org/html/rfc6750 type: type: string example: oauthbearertoken - scim_resource_type: type: object properties: @@ -1986,7 +2423,8 @@ components: type: array items: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:ResourceType" + example: + - urn:ietf:params:scim:schemas:core:2.0:ResourceType id: type: string example: User @@ -1998,57 +2436,10 @@ components: example: User endpoint: type: string - example: "/Users" + example: /Users schema: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:User" - - scim_schema_attribute: - type: object - properties: - name: - type: string - example: userName - type: - enum: - - string - - boolean - - complex - type: string - example: string - multiValued: - type: boolean - example: false - description: - type: string - example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. - required: - type: boolean - example: true - caseExact: - type: boolean - example: false - mutability: - type: string - example: readWrite - returned: - type: string - example: default - uniqueness: - type: string - example: server - - - scim_schema_parent_attribute: - allOf: - - $ref: "#/components/schemas/scim_schema_attribute" - - type: object - properties: - subAttributes: - type: array - items: - $ref: "#/components/schemas/scim_schema_attribute" - + example: urn:ietf:params:scim:schemas:core:2.0:User scim_schema: type: object properties: @@ -2056,7 +2447,8 @@ components: type: array items: type: string - example: [ "urn:ietf:params:scim:schemas:core:2.0:Schema" ] + example: + - urn:ietf:params:scim:schemas:core:2.0:Schema id: type: string example: urn:ietf:params:scim:schemas:core:2.0:User @@ -2068,10 +2460,9 @@ components: example: User Account attributes: type: array - example: [ ] + example: [] items: - $ref: "#/components/schemas/scim_schema_parent_attribute" - + $ref: '#/components/schemas/scim_schema_parent_attribute' scim_email: type: object properties: @@ -2084,22 +2475,19 @@ components: primary: type: boolean example: true - scim_group: type: object properties: value: type: string - example: "nightswatch" + example: nightswatch display: type: string - example: "nightswatch" - + example: nightswatch scim_user_username: type: string description: The user's email address. This must be reachable via email. example: jon.snow@docker.com - scim_user_name: type: object properties: @@ -2109,48 +2497,44 @@ components: familyName: type: string example: Snow - scim_user_display_name: type: string description: The username in Docker. Also known as the "Docker ID". example: jonsnow - scim_user_schemas: type: array items: type: string - example: "urn:ietf:params:scim:schemas:core:2.0:User" + example: urn:ietf:params:scim:schemas:core:2.0:User minItems: 1 - scim_user_id: type: string example: d80f7c79-7730-49d8-9a41-7c42fb622d9c description: The unique identifier for the user. A v4 UUID. - scim_user: type: object properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' id: - $ref: "#/components/schemas/scim_user_id" + $ref: '#/components/schemas/scim_user_id' userName: - $ref: "#/components/schemas/scim_user_username" + $ref: '#/components/schemas/scim_user_username' name: - $ref: "#/components/schemas/scim_user_name" + $ref: '#/components/schemas/scim_user_name' displayName: - $ref: "#/components/schemas/scim_user_display_name" + $ref: '#/components/schemas/scim_user_display_name' active: type: boolean example: true emails: type: array items: - $ref: "#/components/schemas/scim_email" + $ref: '#/components/schemas/scim_email' groups: type: array items: - $ref: "#/components/schemas/scim_group" + $ref: '#/components/schemas/scim_group' meta: type: object properties: @@ -2162,31 +2546,13 @@ components: example: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c created: type: string - description: The creation date for the user as a RFC3339 formatted - string. - example: 2022-05-20T00:54:18Z + description: The creation date for the user as a RFC3339 formatted string. + example: '2022-05-20T00:54:18Z' lastModified: type: string - description: The date the user was last modified as a RFC3339 - formatted string. - example: 2022-05-20T00:54:18Z - + description: The date the user was last modified as a RFC3339 formatted string. + example: '2022-05-20T00:54:18Z' parameters: - scim_attributes: - in: query - name: attributes - schema: - type: string - description: Comma delimited list of attributes to limit to in the - response. - example: userName,displayName - scim_user_id: - name: id - in: path - schema: - type: string - description: The user ID. - example: "d80f7c79-7730-49d8-9a41-7c42fb622d9c" namespace: in: path name: namespace @@ -2205,22 +2571,132 @@ components: required: true schema: type: string + org_name: + in: path + name: org_name + description: Name of the organization (namespace). + schema: + type: string + example: myorganization + required: true + group_name: + in: path + name: group_name + description: Name of the group (team) in the organization. + schema: + type: string + example: developers + required: true + username: + in: path + name: username + description: Username, identifier for the user (namespace, DockerID). + schema: + type: string + example: jonsnow + required: true page: in: query name: page - required: false + description: Page number (starts on 1). schema: type: integer - description: "Page number to get. Defaults to 1." page_size: in: query name: page_size - required: false + description: Number of items (rows) per page. schema: type: integer - description: "Number of items to get per page. Defaults to 10. Max of 100." - + invites: + in: query + name: invites + description: Include invites in the response. + schema: + type: boolean + search: + in: query + name: search + schema: + type: integer + description: Search term. + scim_attributes: + in: query + name: attributes + schema: + type: string + description: Comma delimited list of attributes to limit to in the response. + example: userName,displayName + scim_user_id: + name: id + in: path + schema: + type: string + description: The user ID. + example: d80f7c79-7730-49d8-9a41-7c42fb622d9c + required: true + type: + in: query + name: type + schema: + type: string + enum: + - all + - invitee + - member + example: all + role: + in: query + name: role + schema: + type: string + enum: + - owner + - editor + - member + example: owner + bulk_invite: + in: header + name: X-Analytics-Client-Feature + description: Optional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web') + schema: + type: string requestBodies: + bulk_invite_request: + required: true + content: + application/json: + schema: + type: object + required: + - org + - invitees + properties: + org: + type: string + description: organization name + example: docker + team: + type: string + description: team name + example: owners + role: + type: string + description: role for invitees + example: member + invitees: + type: array + description: list of invitees emails or Docker Ids + items: + type: string + description: invitee email or Docker ID + example: + - invitee1DockerId + - invitee2@docker.com + - invitee3@docker.com + dry_run: + type: boolean + description: Optional, run through validation but don't actually change data. + example: true scim_create_user_request: required: true content: @@ -2232,12 +2708,11 @@ components: - userName properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' userName: - $ref: "#/components/schemas/scim_user_username" + $ref: '#/components/schemas/scim_user_username' name: - $ref: "#/components/schemas/scim_user_name" - + $ref: '#/components/schemas/scim_user_name' scim_update_user_request: required: true content: @@ -2248,15 +2723,41 @@ components: - schemas properties: schemas: - $ref: "#/components/schemas/scim_user_schemas" + $ref: '#/components/schemas/scim_user_schemas' name: allOf: - - $ref: "#/components/schemas/scim_user_name" - - description: If this is omitted from the request, the - update will skip the update on it. We will only ever - change the name, but not clear it. + - $ref: '#/components/schemas/scim_user_name' + - description: If this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it. enabled: type: boolean default: false - description: If this is omitted from the request, it will - default to false resulting in a deactivated user. + description: If this is omitted from the request, it will default to false resulting in a deactivated user. + add_member_to_org_group: + required: true + content: + application/json: + schema: + type: object + required: + - member + properties: + member: + type: string + example: jonsnow +x-tagGroups: + - name: General + tags: + - resources + - rate-limiting + - name: API + tags: + - authentication + - access-tokens + - images + - audit-logs + - org-settings + - repositories + - scim + - orgs + - groups + - invites