swagger: '2.0' schemes: - https host: hub.docker.com basePath: "/" produces: - application/json consumes: - application/json info: title: Docker HUB API version: 'beta' x-logo: url: https://docs.docker.com/images/logo-docker-main.png description: | 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. Browse through the Docker Hub API documentation to explore the supported endpoints. tags: # Primary objects - name: Authentication x-displayName: Authentication description: | Most Docker Hub API endpoints require you to authenticate using your Docker credentials. 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. 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: Images x-displayName: Advanced image management description: | The Advanced Image Management API endpoints allow you to manage Docker images across all repositories. For more information, see [Advanced Image Management dashboard](https://docs.docker.com/docker-hub/image-management/). - name: Audit Logs x-displayName: Audit Logs description: | 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/docker-hub/audit-log/) definitions: UsersLoginRequest: description: User login details type: object required: [username, password] properties: username: description: The username of the Docker Hub account to authenticate with. type: string example: myusername password: description: The password of the Docker Hub account to authenticate with. type: string example: hunter2 PostUsersLoginSuccessResponse: description: successful user login response type: object properties: token: description: | Created authentication token. This token can be used in the HTTP Authentication header as a JWT to authenticate with the Docker Hub APIs. type: string x-nullable: false example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c PostUsersLoginErrorResponse: description: failed user login response. type: object properties: details: description: Description of the error. type: string x-nullable: false example: Incorrect authentication credentials 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: '#/definitions/ErrorInfo' 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 x-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 x-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 x-nullable: true example: '2021-02-24T22:05:27.526308Z' last_pulled: description: Time when this image was last pulled. Note this is updated at most once per hour. type: string x-nullable: true example: '2021-02-24T23:16:10.200008Z' 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 x-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 x-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: '#/definitions/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: type_url: type: string value: type: string format: byte rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/definitions/protobufAny' AuditLogAction: type: object properties: name: type: string description: Name of audit log action. description: type: string description: Description of audit log action. label: type: string description: Label for audit log action. description: Audit Log action AuditLogActions: type: object properties: actions: type: array items: $ref: '#/definitions/AuditLogAction' description: List of audit log actions. label: type: string description: Grouping label for a particular set of audit log actions. GetAuditActionsResponse: type: object properties: actions: type: object additionalProperties: $ref: '#/definitions/AuditLogActions' description: Map of audit log actions. description: GetAuditActions response. GetAuditLogsResponse: type: object properties: logs: type: array items: $ref: '#/definitions/AuditLog' description: List of audit log events. description: GetAuditLogs response. AuditLog: type: object properties: account: type: string action: type: string name: type: string actor: type: string data: type: object additionalProperties: type: string timestamp: type: string format: date-time action_description: type: string description: Audit log event. paths: /v2/users/login: post: tags: [Authentication] summary: Create authentication token operationId: PostUsersLogin description: | Creates an authentication token that can be used to authenticate with the Docker Hub APIs. The returned token is used in the HTTP Authentication header like `Authentication: JWT {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. parameters: - name: body in: body description: Login details. required: true schema: $ref: '#/definitions/UsersLoginRequest' responses: 200: description: Authentication successful schema: $ref: '#/definitions/PostUsersLoginSuccessResponse' 401: description: Authentication failed schema: $ref: '#/definitions/PostUsersLoginErrorResponse' /v2/namespaces/{namespace}/repositories/{repository}/images-summary: get: tags: [Images] summary: Get summary of repository's images description: | Gets the number of images in a repository and the number of images counted as active and inactive. operationId: GetNamespacesRepositoriesImagesSummary produces: - application/json parameters: - name: namespace in: path required: true description: Namespace of the repository. type: string - name: repository in: path required: true description: Name of the repository. type: string - name: active_from in: query required: false 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 responses: 200: description: Success schema: $ref: '#/definitions/GetNamespaceRepositoryImagesSummaryResponse' 401: description: Unauthorized - user does not have read access to the namespace schema: $ref: '#/definitions/ErrorResponse' /v2/namespaces/{namespace}/repositories/{repository}/images: get: tags: [Images] summary: Get details of repository's images description: Gets details on the images in a repository. operationId: GetNamespacesRepositoriesImages produces: - application/json parameters: - name: namespace in: path required: true description: Namespace of the repository. type: string - name: repository in: path required: true description: Name of the repository. type: string - name: status in: query required: false description: Filters to only show images of this status. type: string enum: [active, inactive] - name: currently_tagged in: query required: false type: boolean description: | Filters to only show images with: * `true`: at least 1 current tag. * `false`: no current tags. - name: ordering in: query required: false description: | Orders the results by this property. Prefixing with `-` sorts by descending order. type: string enum: [last_activity, -last_activity, digest, -digest] - name: active_from in: query required: false 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 - name: page in: query required: false description: Page number to get. Defaults to 1. type: integer - name: page_size in: query required: false description: Number of images to get per page. Defaults to 10. Max of 100. type: integer responses: 200: description: Success schema: $ref: '#/definitions/GetNamespaceRepositoryImagesResponse' 401: description: Unauthorized - user does not have read access to the namespace. schema: $ref: '#/definitions/ErrorResponse' 403: description: Forbidden - this API is only available to users on Pro or Team plans. schema: $ref: '#/definitions/ErrorResponse' /v2/namespaces/{namespace}/repositories/{repository}/images/{digest}/tags: get: tags: [Images] summary: Get image's tags description: Gets current and historical tags for an image. operationId: GetNamespacesRepositoriesImagesTags produces: - application/json parameters: - name: namespace in: path required: true description: Namespace of the repository. type: string - name: repository in: path required: true description: Name of the repository. type: string - name: digest in: path required: true description: Digest of the image. type: string - name: page in: query required: false description: Page number to get. Defaults to 1. type: integer - name: page_size in: query required: false description: Number of images to get per page. Defaults to 10. Max of 100. type: integer responses: 200: description: Success schema: $ref: '#/definitions/GetNamespaceRepositoryImagesTagsResponse' 401: description: Unauthorized - user does not have read access to the namespace schema: $ref: '#/definitions/ErrorResponse' 403: description: Forbidden - this API is only available to users on Pro or Team plans schema: $ref: '#/definitions/ErrorResponse' /v2/namespaces/{namespace}/delete-images: post: tags: [Images] summary: Delete images operationId: PostNamespacesDeleteImages description: | Deletes one or more images within a namespace. This is currently limited to a single repostiory. 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. 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. parameters: - name: namespace in: path required: true description: Namespace of the repository. type: string - description: Delete request. in: body name: body required: true schema: $ref: '#/definitions/PostNamespacesDeleteImagesRequest' responses: 200: description: Deletion completed schema: $ref: '#/definitions/PostNamespacesDeleteImagesResponseSuccess' 400: description: Deletion not possible schema: $ref: '#/definitions/PostNamespacesDeleteImagesResponseError' 403: description: Forbidden - this API is only available to users on Pro or Team plans schema: $ref: '#/definitions/ErrorResponse' /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: description: A successful response. schema: $ref: '#/definitions/GetAuditLogsResponse' examples: application/json: logs: - account: docker action: repo.tag.push name: docker/example actor: docker 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: '' schema: {} examples: application/json: detail: Rate limit exceeded error: false 500: description: '' schema: {} default: description: An unexpected error response. schema: $ref: '#/definitions/rpcStatus' parameters: - name: account description: Namespace to query audit logs for. in: path required: true type: string - name: action description: 'action name one of ["repo.tag.push", ...]. Optional parameter to filter specific audit log actions.' in: query required: false 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.' in: query required: false type: string - name: actor description: actor name. Optional parameter to filter audit log events to the specific user who triggered the event. in: query required: false type: string - name: from description: Start of the time window you wish to query audit events for. in: query required: false type: string format: date-time - name: to description: End of the time window you wish to query audit events for. in: query required: false type: string format: date-time - name: page description: page - specify page number. Page number to get. in: query required: false type: integer format: int32 default: 1 - name: page_size description: page_size - specify page size. Number of events to return per page. in: query required: false type: integer format: int32 default: 25 tags: - "Audit Logs" /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. operationId: AuditLogs_GetAuditActions responses: 200: description: A successful response. schema: $ref: '#/definitions/GetAuditActionsResponse' examples: application/json: actions: org: actions: - name: team.create description: contains team create events label: Team Created - name: team.delete description: contains team delete events label: Team Deleted - name: team.member.add description: contains team member add events label: Team Member Added - name: team.member.remove description: contains team member remove events label: Team Member Removed - name: team.member.invite description: contains team member invite events label: Team Member Invited - name: member.removed description: contains org member remove events label: Organization Member Removed - name: create description: contains organization create events label: Organization Created label: Organization repo: actions: - name: create description: contains repository create events label: Repository Created - name: delete description: contains repository delete events label: Repository Deleted - name: change_privacy description: contains repository privacy change events label: Privacy Changed - name: tag.push description: contains image tag push events label: Tag Pushed - name: tag.delete description: contains image tag delete events label: Tag Deleted label: Repository 429: description: '' schema: {} examples: application/json: detail: Rate limit exceeded error: false 500: description: '' schema: {} default: description: An unexpected error response. schema: $ref: '#/definitions/rpcStatus' parameters: - name: account description: Namespace to query audit log actions for. in: path required: true type: string tags: - "Audit Logs"