openapi: 3.2.0
info:
  title: Harbor scan data export API
  description: These APIs provide services for manipulating Harbor project.
  version: '2.0'
servers:
- url: http://localhost/api/v2.0
- url: https://localhost/api/v2.0
security:
- basic: []
- {}
tags:
- name: scan data export
paths:
  /export/cve:
    post:
      summary: Export scan data for selected projects
      tags:
      - scan data export
      operationId: exportScanData
      parameters:
      - $ref: '#/components/parameters/requestId'
      - $ref: '#/components/parameters/scanDataType'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanDataExportJob'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanDataExportRequest'
        description: The criteria for the export
        required: true
  /export/cve/execution/{execution_id}:
    get:
      summary: Get the specific scan data export execution
      description: Get the scan data export execution specified by ID
      tags:
      - scan data export
      operationId: getScanDataExportExecution
      parameters:
      - $ref: '#/components/parameters/requestId'
      - $ref: '#/components/parameters/executionId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanDataExportExecution'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /export/cve/executions:
    get:
      summary: Get a list of specific scan data export execution jobs for a specified user
      tags:
      - scan data export
      operationId: getScanDataExportExecutionList
      parameters:
      - $ref: '#/components/parameters/requestId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanDataExportExecutionList'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /export/cve/download/{execution_id}:
    get:
      summary: Download the scan data export file
      description: Download the scan data report. Default format is CSV
      tags:
      - scan data export
      operationId: downloadScanData
      parameters:
      - $ref: '#/components/parameters/requestId'
      - $ref: '#/components/parameters/executionId'
      - name: format
        in: query
        required: false
        description: The format of the data to be exported. e.g. CSV or PDF
        schema:
          type: string
      responses:
        '200':
          description: Data file containing the export data
          headers:
            Content-Disposition:
              description: Value is a CSV formatted file; filename=export.csv
              schema:
                type: string
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '403':
      description: Forbidden. The caller does not have sufficient permission to perform the requested operation.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '500':
      description: Internal server error. Inspect the `errors` array in the response body for details.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '409':
      description: Conflict. The resource already exists or the current state prevents the operation.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '405':
      description: Method not allowed.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '401':
      description: Unauthorized. Authentication is required to access this resource.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '400':
      description: Bad request. The request body or query parameters are invalid. Inspect the `errors` array in the response body for details.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '404':
      description: Not found. The requested resource does not exist.
      headers:
        X-Request-Id:
          description: The ID of the corresponding request for the response
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
  schemas:
    ScanDataExportJob:
      type: object
      description: The metadata associated with the scan data export job
      properties:
        id:
          type: integer
          format: int64
          description: The id of the scan data export job
    ScanDataExportRequest:
      type: object
      description: The criteria to select the scan data to export.
      properties:
        job_name:
          type: string
          description: Name of the scan data export job
        projects:
          type: array
          items:
            type: integer
            format: int64
          description: A list of one or more projects for which to export the scan data, currently only one project is supported due to performance concerns, but define as array for extension in the future.
        labels:
          type: array
          items:
            type: integer
            format: int64
          description: A list of one or more labels for which to export the scan data, defaults to all if empty
        repositories:
          type: string
          description: A list of repositories for which to export the scan data, defaults to all if empty
        cveIds:
          type: string
          description: CVE-IDs for which to export data. Multiple CVE-IDs can be specified by separating using ',' and enclosed between '{}'. Defaults to all if empty
        tags:
          type: string
          description: A list of tags enclosed within '{}'. Defaults to all if empty
    ScanDataExportExecutionList:
      type: object
      description: The list of scan data export executions
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ScanDataExportExecution'
          description: The list of scan data export executions
    ScanDataExportExecution:
      type: object
      description: The replication execution
      properties:
        id:
          type: integer
          description: The ID of the execution
        user_id:
          type: integer
          description: The ID if the user triggering the export job
        status:
          type: string
          description: The status of the execution
        trigger:
          type: string
          description: The trigger mode
        start_time:
          type: string
          format: date-time
          description: The start time
        end_time:
          type: string
          format: date-time
          description: The end time
        status_text:
          type: string
          x-omitempty: false
          description: The status text
        user_name:
          type: string
          x-omitempty: false
          description: The name of the user triggering the job
        file_present:
          type: boolean
          x-omitempty: false
          description: Indicates whether the export artifact is present in registry
    Errors:
      description: The error array that describe the errors got during the handling of request
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    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
      example:
        code: NOT_FOUND
        message: artifact library/hello-world:latest not found
  parameters:
    scanDataType:
      name: X-Scan-Data-Type
      description: The type of scan data to export
      in: header
      required: true
      schema:
        type: string
    executionId:
      name: execution_id
      in: path
      description: Execution ID
      required: true
      schema:
        type: integer
    requestId:
      name: X-Request-Id
      description: An unique ID for the request
      in: header
      required: false
      schema:
        type: string
        minLength: 1
  securitySchemes:
    basic:
      type: http
      scheme: basic