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