harbor/api/v2.0/legacy_swagger.yaml

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
  - text/plain
consumes:
  - application/json
securityDefinitions:
  basicAuth:
    type: basic
security:
  - basicAuth: []
paths:
  /email/ping:
    post:
      summary: Test connection and authentication with email server.
      description: |
        Test connection and authentication with email server.        
      parameters:
        - name: settings
          in: body
          description: 'Email server settings, if some of the settings are not assigned, they will be read from system configuration.'
          required: false
          schema:
            $ref: '#/definitions/EmailServerSetting'
      tags:
        - Products
      responses:
        '200':
          description: Ping email server successfully.
        '400':
          description: Inviald email server settings.
        '401':
          description: User need to login first.
        '403':
          description: Only admin has this authority.
        '415':
          $ref: '#/responses/UnsupportedMediaType'
        '500':
          description: Unexpected internal errors.
  /chartrepo/{repo}/charts/{name}/{version}/labels:
    get:
      summary: Return the attahced labels of chart.
      description: Return the attahced labels of the specified chart version.
      tags:
        - Products
        - Chart Repository
        - Label
      parameters:
        - name: repo
          in: path
          type: string
          required: true
          description: The project name
        - name: name
          in: path
          type: string
          required: true
          description: The chart name
        - name: version
          in: path
          type: string
          required: true
          description: The chart version
      responses:
        '200':
          $ref: '#/definitions/Labels'
        '401':
          $ref: '#/definitions/UnauthorizedChartAPIError'
        '403':
          $ref: '#/definitions/ForbiddenChartAPIError'
        '404':
          $ref: '#/definitions/NotFoundChartAPIError'
        '500':
          $ref: '#/definitions/InternalChartAPIError'
    post:
      summary: Mark label to chart.
      description: Mark label to the specified chart version.
      tags:
        - Products
        - Chart Repository
        - Label
      parameters:
        - name: repo
          in: path
          type: string
          required: true
          description: The project name
        - name: name
          in: path
          type: string
          required: true
          description: The chart name
        - name: version
          in: path
          type: string
          required: true
          description: The chart version
        - name: label
          in: body
          required: true
          schema:
            $ref: '#/definitions/Label'
          description: 'The label being marked to the chart version'
      responses:
        '200':
          description: The label is successfully marked to the chart version.
        '400':
          $ref: '#/definitions/BadRequestFormatedError'
        '401':
          $ref: '#/definitions/UnauthorizedChartAPIError'
        '403':
          $ref: '#/definitions/ForbiddenChartAPIError'
        '404':
          $ref: '#/definitions/NotFoundChartAPIError'
        '409':
          $ref: '#/definitions/ConflictFormatedError'
        '500':
          $ref: '#/definitions/InternalChartAPIError'
  /chartrepo/{repo}/charts/{name}/{version}/labels/{id}:
    delete:
      summary: Remove label from chart.
      description: Remove label from the specified chart version.
      tags:
        - Products
        - Chart Repository
        - Label
      parameters:
        - name: repo
          in: path
          type: string
          required: true
          description: The project name
        - name: name
          in: path
          type: string
          required: true
          description: The chart name
        - name: version
          in: path
          type: string
          required: true
          description: The chart version
        - name: id
          in: path
          type: integer
          required: true
          description: The label ID
      responses:
        '200':
          description: The label is successfully unmarked from the chart version.
        '400':
          $ref: '#/definitions/BadRequestFormatedError'
        '401':
          $ref: '#/definitions/UnauthorizedChartAPIError'
        '403':
          $ref: '#/definitions/ForbiddenChartAPIError'
        '404':
          $ref: '#/definitions/NotFoundChartAPIError'
        '500':
          $ref: '#/definitions/InternalChartAPIError'
  '/system/CVEAllowlist':
    get:
      summary: Get the system level allowlist of CVE.
      description: Get the system level allowlist of CVE.  This API can be called by all authenticated users.
      tags:
        - Products
        - System
      responses:
        '200':
          description: Successfully retrieved the CVE allowlist.
          schema:
            $ref: "#/definitions/CVEAllowlist"
        '401':
          description: User is not authenticated.
        '500':
          description: Unexpected internal errors.
    put:
      summary: Update the system level allowlist of CVE.
      description: This API overwrites the system level allowlist of CVE with the list in request body.  Only system Admin
        has permission to call this API.
      tags:
        - Products
        - System
      parameters:
        - in: body
          name: allowlist
          description: The allowlist with new content
          schema:
            $ref: "#/definitions/CVEAllowlist"
      responses:
        '200':
          description: Successfully updated the CVE allowlist.
        '401':
          description: User is not authenticated.
        '403':
          description: User does not have permission to call this API.
        '500':
          description: Unexpected internal errors.
responses:
  OK:
    description: 'Success'
  Created:
    description: 'Created'
    headers:
      Location:
        type: string
        description: The URL of the created resource
  BadRequest:
    description: 'Bad Request'
  Unauthorized:
    description: 'Unauthorized'
  Forbidden:
    description: 'Forbidden'
  NotFound:
    description: 'Not Found'
  Conflict:
    description: 'Conflict'
  PreconditionFailed:
    description: 'Precondition Failed'
  UnsupportedMediaType:
    description: 'The Media Type of the request is not supported, it has to be "application/json"'
  InternalServerError:
    description: 'Internal Server Error'
definitions:
  Role:
    type: object
    properties:
      role_id:
        type: integer
        format: int32
        description: ID in table.
      role_code:
        type: string
        description: Description of permissions for the role.
      role_name:
        type: string
        description: Name the the role.
      role_mask:
        type: string
  RoleParam:
    type: object
    properties:
      roles:
        type: array
        items:
          type: integer
          format: int32
        description: Role ID for updating project role member.
      username:
        type: string
        description: Username relevant to a project role member.
  LdapConf:
    type: object
    properties:
      ldap_url:
        type: string
        description: The url of ldap service.
      ldap_search_dn:
        type: string
        description: The search dn of ldap service.
      ldap_search_password:
        type: string
        description: The search password of ldap service.
      ldap_base_dn:
        type: string
        description: The base dn of ldap service.
      ldap_filter:
        type: string
        description: The serach filter of ldap service.
      ldap_uid:
        type: string
        description: The serach uid from ldap service attributes.
      ldap_scope:
        type: integer
        format: int64
        description: The serach scope of ldap service.
      ldap_connection_timeout:
        type: integer
        format: int64
        description: The connect timeout of ldap service(second).
  LdapUsers:
    type: object
    properties:
      ldap_username:
        type: string
        description: search ldap user name based on ldapconf.
      ldap_realname:
        type: string
        description: system will try to guess the user realname form "uid" or "cn" attribute.
      ldap_email:
        type: string
        description: system will try to guess the user email address form "mail" or "email" attribute.
  LdapImportUsers:
    type: object
    properties:
      ldap_uid_list:
        type: array
        description: selected uid list
        items:
          type: string
  LdapFailedImportUsers:
    type: object
    properties:
      ldap_uid:
        type: string
        description: the uid can't add to system.
      error:
        type: string
        description: fail reason.
  EmailServerSetting:
    type: object
    properties:
      email_host:
        type: string
        description: The host of email server.
      email_port:
        type: integer
        description: The port of email server.
      email_username:
        type: string
        description: The username of email server.
      email_password:
        type: string
        description: The password of email server.
      email_ssl:
        type: boolean
        description: Use ssl/tls or not.
      email_identity:
        type: string
        description: The dentity of email server.
  ComponentOverviewEntry:
    type: object
    properties:
      severity:
        type: integer
        description: '1-None/Negligible, 2-Unknown, 3-Low, 4-Medium, 5-High'
      count:
        type: integer
        description: number of the components with certain severity.
  Configurations:
    type: object
    properties:
      auth_mode:
        type: string
        description: 'The auth mode of current system, such as "db_auth", "ldap_auth"'
      count_per_project:
        type: string
        description: The default count quota for the new created projects.
      email_from:
        type: string
        description: The sender name for Email notification.
      email_host:
        type: string
        description: The hostname of SMTP server that sends Email notification.
      email_port:
        type: integer
        description: The port of SMTP server.
      email_identity:
        type: string
        description: By default it's empty so the email_username is picked.
      email_username:
        type: string
        description: The username for authenticate against SMTP server.
      email_ssl:
        type: boolean
        description: 'When it''s set to true the system will access Email server via TLS by default.  If it''s set to false, it still will handle "STARTTLS" from server side.'
      email_insecure:
        type: boolean
        description: Whether or not the certificate will be verified when Harbor tries to access the email server.
      ldap_url:
        type: string
        description: The URL of LDAP server.
      ldap_base_dn:
        type: string
        description: The Base DN for LDAP binding.
      ldap_filter:
        type: string
        description: The filter for LDAP binding.
      ldap_scope:
        type: integer
        description: '0-LDAP_SCOPE_BASE, 1-LDAP_SCOPE_ONELEVEL, 2-LDAP_SCOPE_SUBTREE'
      ldap_uid:
        type: string
        description: 'The attribute which is used as identity for the LDAP binding, such as "CN" or "SAMAccountname"'
      ldap_search_dn:
        type: string
        description: The DN of the user to do the search.
      ldap_timeout:
        type: integer
        description: timeout in seconds for connection to LDAP server.
      ldap_group_attribute_name:
        type: string
        description: 'The attribute which is used as identity of the LDAP group, default is cn.'
      ldap_group_base_dn:
        type: string
        description: The base DN to search LDAP group.
      ldap_group_search_filter:
        type: string
        description: The filter to search the ldap group.
      ldap_group_search_scope:
        type: integer
        description: 'The scope to search ldap. ''0-LDAP_SCOPE_BASE, 1-LDAP_SCOPE_ONELEVEL, 2-LDAP_SCOPE_SUBTREE'''
      ldap_group_admin_dn:
        type: string
        description: Specify the ldap group which have the same privilege with Harbor admin.
      oidc_client_id:
        type: string
        description: The client id of the OIDC.
      oidc_client_secret:
        type: string
        description: The client secret of the OIDC.
      oidc_endpoint:
        type: string
        description: The URL of an OIDC-complaint server, must start with 'https://'.
      oidc_name:
        type: string
        description: The name of the OIDC provider.
      oidc_scope:
        type: string
        description: The scope sent to OIDC server during authentication, should be separated by comma. It has to contain “openid”, and “offline_access”. If you are using google, please remove “offline_access” from this field.
      oidc_verify_cert:
        type: boolean
        description: Whether verify your OIDC server certificate, disable it if your OIDC server is hosted via self-hosted certificate.
      project_creation_restriction:
        type: string
        description: This attribute restricts what users have the permission to create project.  It can be "everyone" or "adminonly".
      quota_per_project_enable:
        type: boolean
        description: This attribute indicates whether quota per project enabled in harbor
      read_only:
        type: boolean
        description: '''docker push'' is prohibited by Harbor if you set it to true.   '
      self_registration:
        type: boolean
        description: 'Whether the Harbor instance supports self-registration.  If it''s set to false, admin need to add user to the instance.'
      storage_per_project:
        type: string
        description: The default storage quota for the new created projects.
      token_expiration:
        type: integer
        description: 'The expiration time of the token for internal Registry, in minutes.'
      verify_remote_cert:
        type: boolean
        description: Whether or not the certificate will be verified when Harbor tries to access a remote Harbor instance for replication.
      scan_all_policy:
        type: object
        properties:
          type:
            type: string
            description: 'The type of scan all policy, currently the valid values are "none" and "daily"'
          parameter:
            type: object
            properties:
              daily_time:
                type: integer
                description: 'The offset in seconds of UTC 0 o''clock, only valid when the policy type is "daily"'
            description: 'The parameters of the policy, the values are dependant on the type of the policy.'
  ConfigurationsResponse:
    type: object
    properties:
      auth_mode:
        $ref: '#/definitions/StringConfigItem'
        description: 'The auth mode of current system, such as "db_auth", "ldap_auth"'
      count_per_project:
        $ref: '#/definitions/IntegerConfigItem'
        description: The default count quota for the new created projects.
      email_from:
        $ref: '#/definitions/StringConfigItem'
        description: The sender name for Email notification.
      email_host:
        $ref: '#/definitions/StringConfigItem'
        description: The hostname of SMTP server that sends Email notification.
      email_port:
        $ref: '#/definitions/IntegerConfigItem'
        description: The port of SMTP server.
      email_identity:
        $ref: '#/definitions/StringConfigItem'
        description: By default it's empty so the email_username is picked.
      email_username:
        $ref: '#/definitions/StringConfigItem'
        description: The username for authenticate against SMTP server.
      email_ssl:
        $ref: '#/definitions/BoolConfigItem'
        description: 'When it''s set to true the system will access Email server via TLS by default.  If it''s set to false, it still will handle "STARTTLS" from server side.'
      email_insecure:
        $ref: '#/definitions/BoolConfigItem'
        description: Whether or not the certificate will be verified when Harbor tries to access the email server.
      ldap_url:
        $ref: '#/definitions/StringConfigItem'
        description: The URL of LDAP server.
      ldap_base_dn:
        $ref: '#/definitions/StringConfigItem'
        description: The Base DN for LDAP binding.
      ldap_filter:
        $ref: '#/definitions/StringConfigItem'
        description: The filter for LDAP binding.
      ldap_scope:
        type: integer
        description: '0-LDAP_SCOPE_BASE, 1-LDAP_SCOPE_ONELEVEL, 2-LDAP_SCOPE_SUBTREE'
      ldap_uid:
        $ref: '#/definitions/StringConfigItem'
        description: 'The attribute which is used as identity for the LDAP binding, such as "CN" or "SAMAccountname"'
      ldap_search_dn:
        type: string
        description: The DN of the user to do the search.
      ldap_timeout:
        $ref: '#/definitions/IntegerConfigItem'
        description: timeout in seconds for connection to LDAP server.
      ldap_group_attribute_name:
        $ref: '#/definitions/StringConfigItem'
        description: 'The attribute which is used as identity of the LDAP group, default is cn.'
      ldap_group_base_dn:
        $ref: '#/definitions/StringConfigItem'
        description: The base DN to search LDAP group.
      ldap_group_search_filter:
        $ref: '#/definitions/StringConfigItem'
        description: The filter to search the ldap group.
      ldap_group_search_scope:
        $ref: '#/definitions/IntegerConfigItem'
        description: 'The scope to search ldap. ''0-LDAP_SCOPE_BASE, 1-LDAP_SCOPE_ONELEVEL, 2-LDAP_SCOPE_SUBTREE'''
      ldap_group_admin_dn:
        $ref: '#/definitions/StringConfigItem'
        description: Specify the ldap group which have the same privilege with Harbor admin.
      oidc_client_id:
        $ref: '#/definitions/StringConfigItem'
        description: The client id of the OIDC.
      oidc_endpoint:
        $ref: '#/definitions/StringConfigItem'
        description: The URL of an OIDC-complaint server, must start with 'https://'.
      oidc_name:
        $ref: '#/definitions/StringConfigItem'
        description: The name of the OIDC provider.
      oidc_scope:
        $ref: '#/definitions/StringConfigItem'
        description: The scope sent to OIDC server during authentication, should be separated by comma. It has to contain “openid”, and “offline_access”. If you are using google, please remove “offline_access” from this field.
      oidc_verify_cert:
        $ref: '#/definitions/BoolConfigItem'
        description: Whether verify your OIDC server certificate, disable it if your OIDC server is hosted via self-hosted certificate.
      project_creation_restriction:
        $ref: '#/definitions/StringConfigItem'
        description: This attribute restricts what users have the permission to create project.  It can be "everyone" or "adminonly".
      quota_per_project_enable:
        $ref: '#/definitions/BoolConfigItem'
        description: This attribute indicates whether quota per project enabled in harbor
      read_only:
        $ref: '#/definitions/BoolConfigItem'
        description: '''docker push'' is prohibited by Harbor if you set it to true.   '
      self_registration:
        $ref: '#/definitions/BoolConfigItem'
        description: 'Whether the Harbor instance supports self-registration.  If it''s set to false, admin need to add user to the instance.'
      storage_per_project:
        $ref: '#/definitions/IntegerConfigItem'
        description: The default storage quota for the new created projects.
      token_expiration:
        $ref: '#/definitions/IntegerConfigItem'
        description: 'The expiration time of the token for internal Registry, in minutes.'
      verify_remote_cert:
        $ref: '#/definitions/BoolConfigItem'
        description: Whether or not the certificate will be verified when Harbor tries to access a remote Harbor instance for replication.
      scan_all_policy:
        type: object
        properties:
          type:
            type: string
            description: 'The type of scan all policy, currently the valid values are "none" and "daily"'
          parameter:
            type: object
            properties:
              daily_time:
                type: integer
                description: 'The offset in seconds of UTC 0 o''clock, only valid when the policy type is "daily"'
            description: 'The parameters of the policy, the values are dependant on the type of the policy.'
  Label:
    type: object
    properties:
      id:
        type: integer
        description: The ID of label.
      name:
        type: string
        description: The name of label.
      description:
        type: string
        description: The description of label.
      color:
        type: string
        description: The color of label.
      scope:
        type: string
        description: 'The scope of label, g for global labels and p for project labels.'
      project_id:
        type: integer
        description: The project ID if the label is a project label.
      creation_time:
        type: string
        description: The creation time of label.
      update_time:
        type: string
        description: The update time of label.
      deleted:
        type: boolean
        description: The label is deleted or not.
  ProjectMemberEntity:
    type: object
    properties:
      id:
        type: integer
        description: the project member id
      project_id:
        type: integer
        description: the project id
      entity_name:
        type: string
        description: the name of the group member.
      role_name:
        type: string
        description: the name of the role
      role_id:
        type: integer
        description: the role id
      entity_id:
        type: integer
        description: 'the id of entity, if the member is a user, it is user_id in user table. if the member is a user group, it is the user group''s ID in user_group table.'
      entity_type:
        type: string
        description: 'the entity''s type, u for user entity, g for group entity.'
  ProjectMember:
    type: object
    properties:
      role_id:
        type: integer
        description: 'The role id 1 for projectAdmin, 2 for developer, 3 for guest, 4 for maintainer'
      member_user:
        $ref: '#/definitions/UserEntity'
      member_group:
        $ref: '#/definitions/UserGroup'
  RoleRequest:
    type: object
    properties:
      role_id:
        type: integer
        description: 'The role id 1 for projectAdmin, 2 for developer, 3 for guest, 4 for maintainer'
  UserEntity:
    type: object
    properties:
      user_id:
        type: integer
        description: The ID of the user.
      username:
        type: string
        description: The name of the user.
  UserGroup:
    type: object
    properties:
      id:
        type: integer
        description: The ID of the user group
      group_name:
        type: string
        description: The name of the user group
      group_type:
        type: integer
        description: 'The group type, 1 for LDAP group, 2 for HTTP group.'
      ldap_group_dn:
        type: string
        description: The DN of the LDAP group if group type is 1 (LDAP group).
  StringConfigItem:
    type: object
    properties:
      value:
        type: string
        description: The string value of current config item
      editable:
        type: boolean
        description: The configure item can be updated or not
  BoolConfigItem:
    type: object
    properties:
      value:
        type: boolean
        description: The boolean value of current config item
      editable:
        type: boolean
        description: The configure item can be updated or not
  IntegerConfigItem:
    type: object
    properties:
      value:
        type: integer
        description: The integer value of current config item
      editable:
        type: boolean
        description: The configure item can be updated or not
  ChartAPIError:
    description: The error object returned by chart repository API
    type: object
    required:
      - error
    properties:
      error:
        type: string
        description: The error message returned by the chart API
  UnauthorizedChartAPIError:
    description: Unauthorized
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  ForbiddenChartAPIError:
    description: Operation is forbidden or quota exceeded
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  InternalChartAPIError:
    description: Internal server error occurred
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  NotFoundChartAPIError:
    description: Not found
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  InsufficientStorageChartAPIError:
    description: Insufficient storage
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  BadRequestFormatedError:
    description: Bad request
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  ConflictFormatedError:
    description: Conflicts
    type: object
    allOf:
      - $ref: '#/definitions/ChartAPIError'
  ChartMetadata:
    type: object
    description: The metadata of chart version
    required:
      - name
      - version
      - engine
      - icon
      - apiVersion
      - appVersion
    properties:
      name:
        type: string
        description: The name of the chart
      home:
        type: string
        description: The URL to the relevant project page
      sources:
        type: array
        description: The URL to the source code of chart
        items:
          type: string
      version:
        type: string
        description: A SemVer 2 version of chart
      description:
        type: string
        description: A one-sentence description of chart
      keywords:
        type: array
        description: A list of string keywords
        items:
          type: string
      engine:
        type: string
        description: The name of template engine
      icon:
        type: string
        description: The URL to an icon file
      apiVersion:
        type: string
        description: The API version of this chart
      appVersion:
        type: string
        description: The version of the application enclosed in the chart
      deprecated:
        type: boolean
        description: Whether or not this chart is deprecated
  ChartVersion:
    type: object
    description: A specified chart entry
    allOf:
      - $ref: '#/definitions/ChartMetadata'
      - type: object
        properties:
          created:
            type: string
            description: The created time of the chart entry
          removed:
            type: boolean
            description: A flag to indicate if the chart entry is removed
          digest:
            type: string
            description: The digest value of the chart entry
          urls:
            type: array
            description: The urls of the chart entry
            items:
              type: string
    properties:
      labels:
        $ref: '#/definitions/Labels'
  Labels:
    type: array
    description: A list of label
    items:
      $ref: '#/definitions/Label'
  Permission:
    type: object
    description: The permission
    properties:
      resource:
        type: string
        description: The permission resoruce
      action:
        type: string
        description: The permission action
  Namespace:
    type: object
    description: The namespace of registry
    properties:
      name:
        type: string
        description: The name of namespace
      metadata:
        type: object
        description: The metadata of namespace
  CVEAllowlist:
    type: object
    description: The CVE Allowlist for system or project
    properties:
      id:
        type: integer
        description: ID of the allowlist
      project_id:
        type: integer
        description: ID of the project which the allowlist belongs to.  For system level allowlist this attribute is zero.
      expires_at:
        type: integer
        description: the time for expiration of the allowlist, in the form of seconds since epoch.  This is an optional attribute, if it's not set the CVE allowlist does not expire.
      items:
        type: array
        items:
          $ref: "#/definitions/CVEAllowlistItem"
  CVEAllowlistItem:
    type: object
    description: The item in CVE allowlist
    properties:
      cve_id:
        type: string
        description: The ID of the CVE, such as "CVE-2019-10164"

  QuotaSwitcher:
    type: object
    properties:
      enabled:
        type: boolean
        description: The quota is enable or disable

parameters:
  query:
    name: q
    description: Query string to query resources. Supported query patterns are "exact match(k=v)", "fuzzy match(k=~v)", "range(k=[min~max])", "list with union releationship(k={v1 v2 v3})" and "list with intersetion relationship(k=(v1 v2 v3))". The value of range and list can be string(enclosed by " or '), integer or time(in format "2020-04-09 02:36:00"). All of these query patterns should be put in the query string "q=xxx" and splitted by ",". e.g. q=k1=v1,k2=~v2,k3=[min~max]
    in: query
    type: string
    required: false