HTTP API v1.3

NOTES:

  • API capability requires an additional WhiteSource license. Contact your CSM for more details.

  • For customers who have enabled vulnerability-based alerting, there are several changes to API version 1.3 -  refer here for details.

  • This page covers APIs for version 1.3. All version 1.3 APIs must include:

Overview

The WhiteSource HTTP API is available for WhiteSource customers who are licensed to use it. The APIs can be accessed by the organization's administrator(s). 

The API is simply an HTTP endpoint implementing a JSON speaking web service and handling POST requests. Like the service itself, communication is secured with SSL.

This document describes the WhiteSource HTTP API v1.3. The API URL can be obtained by copying the WhiteSource Server URL, which can be retrieved from your Profile page on the Server URLs panel. Then, add the path /api/v1.3 to it. For example: https://saas.whitesourcesoftware.com/api/v1.3.

Regarding version numbers, if there are 3 or more version parts, (for example, x.y.z or x.y.z.w) both x and y are considered a major version (x.y).
If there are 2 major parts (x.y), then x is considered a major version.

NOTE: The previous WhiteSource API version is currently still supported, and is documented in the HTTP API v1.2 page.

Note the following about API calls:

  • When performing API calls, the time recorded for the action is in GMT time zone, therefore, this is the time displayed in the relevant reports. 

  • Date format in all responses is "yyyy-MM-dd".

  • The API results are not sorted in any order.

API Execution Scope

Generally, each level of the administrator (Organization, Product) can get/set the API attributes in the API calls that refer to their scope and/or under their scope. For example, Product administrators can execute API calls related to their Projects/Products that are defined in WhiteSource, but they cannot execute Organization-related API calls which are outside their scope. However, there are two API calls that are exceptions to this rule:

  • getProjectVitals – Product administrators can use the Organization level call and get the product/project vitals related to their products/projects.

  • getRequestState – Although an Organization token is required in the call, a product administrator can also execute it.

API URL

The base URL for all API endpoints can be obtained from the Integrate tab (calls to HTTP cannot be redirected to HTTPS).

Only POST requests are accepted. 

Request payload should have: Content-Type =  application/json

API Format

All requests require a token available via the API Integration page in your WhiteSource account, according to the request's context (organization / product / project).

The requestType parameter is mandatory for all requests.

Parameter

Description

Parameter

Description

requestType

For details, see Supported Requests.

orgToken

Your organization API key.

productToken

A unique identifier for your product.

projectToken

A unique identifier for your project.

Character Sets

WhiteSource HTTP API v1.x supports Accept-Charset header.

If the value of the header is a supported character set (see supported values below) the response would be in that character set.
Otherwise, if the value is not supported or if the header isn't sent, the default response character set will be UTF-8.

Supported character sets are:

  • utf-8

  • utf-16

  • iso-8859-1

  • iso-8859-2

  • iso-8859-4

  • iso-8859-5

  • iso-8859-7

  • iso-8859-9

  • us-ascii

Special Characters

The following characters are NOT supported as API input: <, >, % and &

Supported Requests

WhiteSource HTTP API v1.3 supports the following requests:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210         "addGlobalOrganizationPolicy",         "addOrganizationPolicy",         "addProductPolicy",         "addProjectPolicy",         "addUsersToGroups",         "changeOriginLibrary",         "clearOrganizationSourceFileMatchingResults",         "clearProductSourceFileMatchingResults",         "clearProjectSourceFileMatchingResults",         "createGlobalOrg",         "createGroup",         "createProduct",         "createProject",         "createServiceUser",         "createUser",         "deleteProduct",         "deleteProject",         "fetchProjectPolicyIssues",         "getAggregatedFix",         "getAggregatedLibraryDetails",         "getAlertsByProjectTag",         "getAllGroups",         "getAllOrganizations",         "getAllProducts",         "getAllProjects",         "getAllUsers",         "getChangeLogHistoryReport",         "getChangesReport",         "getClusterVulnerabilityReportRequest",         "getCopyrightsTextFile",         "getDirectDependencyVersion",         "getGlobalLicenses",         "getGlobalOrganizationPolicies",         "getIntegrationActivationToken",         "getIntegrationWorkflowRules",         "getLibraryInfo",         "getLibraryLicenses",         "getLibrarySourceFiles",         "getLibraryVulnerabilities",         "getLicensesByPackageCoordinates",         "getLicensesTextZip",         "getNoticesTextFile",         "getOrganizationAlerts",         "getOrganizationAlertsByType",         "getOrganizationAlertsReport",         "getOrganizationAssignments",         "getOrganizationAttributesReport",         "getOrganizationBugsReport",         "getOrganizationCapabilities",         "getOrganizationContainerVulnerabilityReportRequest",         "getOrganizationCustomAttributeValues",         "getOrganizationDetails",         "getOrganizationDueDiligenceReport",         "getOrganizationEarlyWarningAlertReport",         "getOrganizationEarlyWarningReport",         "getOrganizationEffectiveLicensesReport",         "getOrganizationEffectiveUsageAnalysis",         "getOrganizationFileClustersReport",         "getOrganizationIgnoredAlerts",         "getOrganizationIgnoredAlertsReport",         "getOrganizationInHouseLibraries",         "getOrganizationInHouseReport",         "getOrganizationInventoryReport",         "getOrganizationLastModifiedProjects",         "getOrganizationLibraryLocationReport",         "getOrganizationLicenseAndComplianceAlertReport",         "getOrganizationLicenseHistogram",         "getOrganizationLicenses",         "getOrganizationMembersReport",         "getOrganizationPolicies",         "getOrganizationProductTags",         "getOrganizationProductVitals",         "getOrganizationProjectTags",         "getOrganizationProjectVitals",         "getOrganizationRequestHistoryReport",         "getOrganizationResolvedAlertsReport",         "getOrganizationRiskReport",         "getOrganizationSecurityAlertsByLibraryReport",         "getOrganizationSecurityAlertsByVulnerabilityReport",         "getOrganizationServiceUsers",         "getOrganizationSourceFileInventoryReport",         "getOrganizationVulnerabilityReport",         "getPluginRequestHistoryReport",         "getPolicyMatchesConfiguration",         "getPolicyViolationHistoryReport",         "getProductAlerts",         "getProductAlertsByType",         "getProductAlertsReport",         "getProductAssignments",         "getProductAttributesReport",         "getProductAttributionReport",         "getProductBugsReport",         "getProductComparisonReport",         "getProductCustomAttributeValues",         "getProductDueDiligenceReport",         "getProductEarlyWarningAlertReport",         "getProductEarlyWarningReport",         "getProductEffectiveLicensesReport",         "getProductFileClustersReport",         "getProductIgnoredAlerts",         "getProductIgnoredAlertsReport",         "getProductInHouseLibraries",         "getProductInHouseReport",         "getProductInventoryReport",         "getProductLibraryLocationReport",         "getProductLibraryLocations",         "getProductLicenseAndComplianceAlertReport",         "getProductLicenseCompatibilityReport",         "getProductLicenseHistogram",         "getProductLicenses",         "getProductMembersReport",         "getProductPolicies",         "getProductProjectTags",         "getProductProjectVitals",         "getProductRequestHistoryReport",         "getProductResolvedAlertsReport",         "getProductRiskReport",         "getProductSecurityAlertsByLibraryReport",         "getProductSecurityAlertsByVulnerabilityReport",         "getProductServiceUsers",         "getProductSourceFileInventoryReport",         "getProductTags",         "getProductVulnerabilityReport",         "getProjectAlerts",         "getProjectAlertsByType",         "getProjectAlertsReport",         "getProjectAttributionReport",         "getProjectBugsReport",         "getProjectComparisonReport",         "getProjectCopyrightsTextFile",         "getProjectCustomAttributeValues",         "getProjectDirectDependencies",         "getProjectDueDiligenceReport",         "getProjectEarlyWarningAlertReport",         "getProjectEarlyWarningReport",         "getProjectHierarchy",         "getProjectIgnoredAlerts",         "getProjectIgnoredAlertsReport",         "getProjectInHouseLibraries",         "getProjectInHouseReport",         "getProjectInventory",         "getProjectInventoryReport",         "getProjectLibrariesInfo",         "getProjectLibraryDependencies",         "getProjectLibraryLocations",         "getProjectLicenseAndComplianceAlertReport",         "getProjectLicenseCompatibilityReport",         "getProjectLicenseHistogram",         "getProjectLicenses",         "getProjectLicensesTextZip",         "getProjectMembersReport",         "getProjectPolicies",         "getProjectRequestHistoryReport",         "getProjectResolvedAlertsReport",         "getProjectRiskReport",         "getProjectSecurityAlertsByLibraryReport",         "getProjectSecurityAlertsByVulnerabilityReport",         "getProjectSourceFileInventoryReport",         "getProjectState",         "getProjectTags",         "getProjectVitals",         "getProjectVulnerabilityReport",         "getRequestSchema",         "getRequestState",         "getServerCapabilities",         "getSupportedRequests",         "getVulnerabilitiesByFilename",         "getVulnerabilitiesByHashes",         "getVulnerabilitiesByPackageCoordinates",         "getVulnerabilityProfiles",         "hasBlockPolicy",         "ignoreAlerts",         "inviteUserToWebAdvisor",         "inviteUsers",         "librarySearch",         "reassignPendingTasksAndConditions",         "regenerateUserKey",         "removeGlobalOrganizationPolicies",         "removeOrganizationPolicies",         "removeProductPolicies",         "removeProductTag",         "removeProjectPolicies",         "removeProjectTag",         "removeUserFromGroup",         "removeUserFromOrganization",         "renameProduct",         "reorderGlobalOrganizationPolicyPriorities",         "reorderOrganizationPolicyPriorities",         "reorderProductPolicyPriorities",         "reorderProjectPolicyPriorities",         "saveProductTag",         "saveProjectTag",         "setAlertsStatus",         "setGlobalOrganizationPolicyStates",         "setLibraryNotice",         "setOrganizationAssignments",         "setOrganizationPolicyStates",         "setProductAssignments",         "setProductPolicyStates",         "setProjectPolicyStates",         "setProjectSetupNotificationConfig",         "unmarkManualInHouseLibrary",         "updateExternalIntegrationIssues",         "updateGlobalOrganizationPolicy",         "updateGlobalSamlIntegration",         "updateMavenDependencyResolutionSettings",         "updateOrganizationPolicy",         "updateOrganizationSamlIntegration",         "updateProductPolicy",         "updateProjectPolicy"

Documentation of Supported API Requests

For documentation of API requests that relate to: