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"
