swagger: '2.0'
info:
  title: Harbor API
  description: These APIs provide services for manipulating Harbor project.
  version: '2.0'
host: localhost
schemes:
  - http
  - https
basePath: /api/v2.0
produces:
  - application/json
consumes:
  - application/json
securityDefinitions:
  basicAuth:
    type: basic
security:
  - basicAuth: []
paths:
  /projects/{project_name}/repositories/{repository_name}/artifacts:
    get:
      summary: List artifacts
      description: List artifacts under the specific project and repository.
      tags:
        - artifact
      operationId: listArtifacts
      parameters:
        - $ref: '#/parameters/requestId'
        - $ref: '#/parameters/projectName'
        - $ref: '#/parameters/repositoryName'
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/pageSize'
        - name: type
          in: query
          description: Query the artifacts by type. Valid values can be "IMAGE", "CHART", etc.
          type: string
          required: false
        - name: with_tag
          in: query
          description: Specify whether the tags are inclued inside the returning artifacts
          type: boolean
          required: false
          default: true
        - name: with_label
          in: query
          description: Specify whether the labels are inclued inside the returning artifacts
          type: boolean
          required: false
          default: false
        - name: with_scan_overview
          in: query
          description: Specify whether the scan overview is inclued inside the returning artifacts
          type: boolean
          required: false
          default: false
        # should be in tag level
        - name: with_signature
          in: query
          description: Specify whether the signature is inclued inside the returning artifacts
          type: boolean
          required: false
          default: false
        - name: with_immutable_status
          in: query
          description: Specify whether the immutable status is inclued inside the tags of the returning artifacts. Only works when setting "with_tag=true"
          type: boolean
          required: false
          default: false
        # TODO add other query string: type, ....
      responses:
        '200':
          description: Success
          headers:
            X-Total-Count:
              description: The total count of artifacts
              type: integer
            Link:
              description: Link refers to the previous page and next page
              type: string
          schema:
            type: array
            items:
              $ref: '#/definitions/Artifact'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
  /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}:
    get:
      summary: Get the specific artifact
      description: Get the artifact specified by the reference under the project and repository. The reference can be digest or tag.
      tags:
        - artifact
      operationId: getArtifact
      parameters:
        - $ref: '#/parameters/requestId'
        - $ref: '#/parameters/projectName'
        - $ref: '#/parameters/repositoryName'
        - $ref: '#/parameters/reference'
        - name: with_tag
          in: query
          description: Specify whether the tags are inclued inside the returning artifacts
          type: boolean
          required: false
          default: true
        - name: with_label
          in: query
          description: Specify whether the labels are inclued inside the returning artifacts
          type: boolean
          required: false
          default: false
        - name: with_scan_overview
          in: query
          description: Specify whether the scan overview is inclued inside the returning artifacts
          type: boolean
          required: false
          default: false
        # should be in tag level
        - name: with_signature
          in: query
          description: Specify whether the signature is inclued inside the returning artifacts
          type: boolean
          required: false
          default: false
        - name: with_immutable_status
          in: query
          description: Specify whether the immutable status is inclued inside the tags of the returning artifacts. Only works when setting "with_tag=true"
          type: boolean
          required: false
          default: false
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Artifact'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
    delete:
      summary: Delete the specific artifact
      description: Delete the artifact specified by the reference under the project and repository. The reference can be digest or tag
      tags:
        - artifact
      operationId: deleteArtifact
      parameters:
        - $ref: '#/parameters/requestId'
        - $ref: '#/parameters/projectName'
        - $ref: '#/parameters/repositoryName'
        - $ref: '#/parameters/reference'
      responses:
        '200':
          $ref: '#/responses/200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
  /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/tags:
    post:
      summary: Create tag
      description: Create a tag for the specified artifact
      tags:
        - artifact
      operationId: createTag
      parameters:
        - $ref: '#/parameters/requestId'
        - $ref: '#/parameters/projectName'
        - $ref: '#/parameters/repositoryName'
        - $ref: '#/parameters/reference'
        - name: tag
          in: body
          description: The JSON object of tag.
          required: true
          schema:
            $ref: '#/definitions/Tag'
      responses:
        '201':
          $ref: '#/responses/201'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '409':
          $ref: '#/responses/409'
        '500':
          $ref: '#/responses/500'
  /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/tags/{tag_name}:
    delete:
      summary: Delete tag
      description: Delete the tag of the specified artifact
      tags:
        - artifact
      operationId: deleteTag
      parameters:
        - $ref: '#/parameters/requestId'
        - $ref: '#/parameters/projectName'
        - $ref: '#/parameters/repositoryName'
        - $ref: '#/parameters/reference'
        - $ref: '#/parameters/tagName'
      responses:
        '200':
          $ref: '#/responses/200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
parameters:
  requestId:
    name: X-Request-Id
    description: An unique ID for the request
    in: header
    type: string
    required: false
    minLength: 1
  projectName:
    name: project_name
    in: path
    description: The name of the project
    required: true
    type: string
  repositoryName:
    name: repository_name
    in: path
    description: The name of the repository
    required: true
    type: string
  reference:
    name: reference
    in: path
    description: The reference of the artifact, can be digest or tag
    required: true
    type: string
  tagName:
    name: tag_name
    in: path
    description: The name of the tag
    required: true
    type: string
  page:
    name: page
    in: query
    type: integer
    format: int64
    required: false
    description: The page number
    default: 1
  pageSize:
    name: page_size
    in: query
    type: integer
    format: int64
    required: false
    description: The size of per page
    default: 10
responses:
  '200':
    description: Success
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
  '201':
    description: Created
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
  '400':
    description: Bad request
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
    schema:
      $ref: '#/definitions/Error'
  '401':
    description: Unauthorized
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
    schema:
      $ref: '#/definitions/Error'
  '403':
    description: Forbidden
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
    schema:
      $ref: '#/definitions/Error'
  '404':
    description: Not found
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
    schema:
      $ref: '#/definitions/Error'
  '409':
    description: Conflict
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
    schema:
      $ref: '#/definitions/Error'
  '500':
    description: Internal server error
    headers:
      X-Request-Id:
        description: The ID of the corresponding request for the response
        type: string
    schema:
      $ref: '#/definitions/Error'
definitions:
  Error:
    description: a model for all the error response coming from harbor
    type: object
    properties:
      code:
        type: string
        description: The error code
      message:
        type: string
        description: The error message
    x-go-type:
      import:
        package: "github.com/goharbor/harbor/src/internal/error"
        alias: "ierrors"
      type: "Error"
  Artifact:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: The ID of the artifact
      type:
        type: string
        description: The type of the artifact, e.g. image, chart, etc
      media_type:
        type: string
        description: The media type of the artifact
      manifest_media_type:
        type: string
        description: The manifest media type of the artifact
      project_id:
        type: integer
        format: int64
        description: The ID of the project that the artifact belongs to
      repository_id:
        type: integer
        format: int64
        description: The ID of the repository that the artifact belongs to
      digest:
        type: string
        description: The digest of the artifact
      size:
        type: integer
        format: int64
        description: The size of the artifact
      push_time:
        type: string
        format: date-time
        description: The push time of the artifact
      pull_time:
        type: string
        format: date-time
        description: The latest pull time of the artifact
      extra_attrs:
        $ref: '#/definitions/ExtraAttrs'
      annotations:
        $ref: '#/definitions/Annotations'
      references:
        type: array
        items:
          $ref: '#/definitions/Reference'
      tags:
        type: array
        items:
          $ref: '#/definitions/Tag'
      sub_resource_links:
        $ref: '#/definitions/SubResourceLinks'
  Tag:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: The ID of the tag
      repository_id:
        type: integer
        format: int64
        description: The ID of the repository that the tag belongs to
      artifact_id:
        type: integer
        format: int64
        description: The ID of the artifact that the tag attached to
      name:
        type: string
        description: The name of the tag
      push_time:
        type: string
        format: date-time
        description: The push time of the tag
      pull_time:
        type: string
        format: date-time
        description: The latest pull time of the tag
  ExtraAttrs:
    type: object
    additionalProperties:
      type: object
  Annotations:
    type: object
    additionalProperties:
      type: string
  SubResourceLinks:
    type: object
    additionalProperties:
      type: array
      items:
        $ref: '#/definitions/ResourceLink'
  ResourceLink:
    type: object
    properties:
      href:
        type: string
        description: The link of the resource
      absolute:
        type: boolean
        description: Determine whether the link is an absolute URL or not
  Reference:
    type: object
    properties:
      parent_id:
        type: integer
        format: int64
        description: The parent ID of the reference
      child_id:
        type: integer
        format: int64
        description: The child ID of the reference
      platform:
        $ref: '#/definitions/Platform'
  Platform:
    type: object
    properties:
      architecture:
        type: string
        description: The architecture that the artifact applys to
      os:
        type: string
        description: The OS that the artifact applys to
      os.version:
        type: string
        description: The version of the OS that the artifact applys to
      os.features:
        type: array
        description: The features of the OS that the artifact applys to
        items:
          type: string
      variant:
        type: string
        description: The variant of the CPU