Table of Contents

maxLevel	3

Overview

This document showcases the API requests and responses for:

creating and deleting products
getting a product’s tags, saving and removing them
creating and deleting projects
getting project tags at the organization, product or project-level
saving a project tag
getting a project’s hierarchy
getting a project’s inventory
getting a project’s state
getting a project’s library source files
getting a project’s library dependencies
defining a project’s setup notification configuration
getting a plugin request state

Product-Level APIs

Create Product

This API request creates a product in an organization with a product token which is its unique identifier.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that creates a product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productName	Name to be assigned to the product.	string	Yes
orgToken	API key which is the unique identifier of the organization.	string	Yes

Request Example

Code Block
{ "requestType" : "createProduct", "userKey": "user_key", "productName" : "new product name", "orgToken" : "organization token" }

...

Code Block
{ "productToken": "new product token", "message": "Successfully created product <new product name>" }

Back to top.

Delete Product

This API request deletes a product in an organization.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that deletes a product.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken	Product token which uniquely identifies the product.	string	Yes
orgToken	API key which is the unique identifier of the organization.	string	Yes

Request Example

Code Block
{ "requestType" : "deleteProduct", "userKey": "user_key", "orgToken" : "organization token", "productToken" :"product token" }

...

Code Block
{ "message": "Successfully deleted product <product name>" }

Back to top.

Product Tags

Product tags are key value pairs that provide additional metadata that enables users to label and search for products according to predefined categories.

Get Product Tags

This API request enables you to get the tags (keys & values) in a product.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns all the keys and values of a product’s tags.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken

API key which is a unique

Unique identifier of the product.

string

Yes

Request Example

Code Block
{ "requestType": "getProductTags", "userKey": "user_key", "productToken": productToken }

...

Code Block
{ "productTags":[ { "name": "My Product A", "token": "product_token", "tags": { "newKey": [ "newValue", "newValue2" ], "tagKeyA": [ "tagValueA" ] } } ]

Back to top.

Get Organization Product Tags

This API request enables you to get the product tags (keys & values) of all products in an organization.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns all the product tags in an organization. NOTE: Products without tags are also returned.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes

Request Example

Code Block
{ "requestType": "getOrganizationProductTags", "userKey": "user_key", "orgToken": "orgToken" }

...

Code Block

{
    "productTags": [
        {
            "name": "productA",
            "token": " productAToken",
            "tags": {
                "newKey": [
                    "newValue",
                    "newValue2"
                ],
                "tagKeyA": [
                    "tagValueA"
                ]
            }
        },
        {
            "name": " productB",
            "token": " productBToken",
            "tags": {}
        }
    ]
}

Back to top.

Save a Product Tag

This API request enables you to save a product’s tag: key, value.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that saves a product’s tag.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken

API key which is a unique

Unique identifier of the product.	string	Yes
tagKey	Label that describes the tag.	string	Yes
tagValue	Value assigned to the tag.	string	Yes

Request Example

Code Block
{ "requestType": "saveProductTag", "userKey": "user_key", "productToken": "productToken", "tagKey": "newKey", "tagValue": "newValue" }

...

Code Block
{ "productTagsInfo": { "name": "productA", "token": {productToken}, "tags": { "newKey": "newValue" } } }

Back to top.

Remove a Product Tag

This API request enables you to remove a product’s tag: key, value.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that removes a product’s tag.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken

API key which is a unique

Unique identifier of the product.	string	Yes
tagKey	Label that describes the tag.	string	Yes
tagValue	Value assigned to the tag.	string	Yes

Request Example

Code Block
{ "requestType" : "removeProductTag", "userKey": "user_key", "productToken" : "product_token", "tagKey": "newKey", "tagValue": "newValue" }

...

Code Block
{ "message": "Successfully removed product tag" }

Back to top.

Project-Level APIs

Create Project

This API request creates a new project within an existing product. A project token is generated which unique identifies the project.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that creates a project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken	Name of the product within which to create the project.	string	Yes
projectName	Name to be assigned to the project.	string	Yes
projectDescription	A description of the new project (optional field).	string	No

Request Example

Code Block
{ "requestType" : "createProject", "userKey": "user_key", "productToken": "product_token", "projectName": "my new project", "projectDescription" : "optional field. Not mandatory" }

...

Code Block
{ "projectToken": "new project token here", "message": "Successfully created project my new project" }

Back to top.

Delete Project

This API request deletes a project in an product.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that deletes a project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken	Product token which identifies the product in which the project resides.	string	Yes
projectToken	Project token of the project to be deleted.	string	Yes

Request Example

Code Block
{ "requestType" : "deleteProject", "userKey": "user_key", "productToken" : "parent product token", "projectToken": "token of the project to be deleted" }

...

Code Block
{ "message": "Successfully deleted project <project name>" }

Back to top.

Project Tags

Project tags are key value pairs that provide additional metadata that enables users to label and search for projects according to predefined categories.

Get Organization Project Tags

This API request enables you to get the project tags (keys & values) of all projects in an organization.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns all the project tags in an organization. NOTE: Products without tags are also returned.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes

Request Example

Code Block
{ "requestType" : "getOrganizationProjectTags", "userKey": "user_key", "orgToken" : "organization_api_key" }

...

Code Block

{
    "projectTags": [
        {
            "name": "Edge Services - 1.29.0",
            "token": "project_token",
            "tags": {}
        },
       
            {
            "name": "WST_464",
            "token": "project_token",
            "tags": {
                "AlertsTag1": [
                    "Production"
                ],
                "AlertsTag2": [
                    "Development"
                ]
            }
        },
                {
            "name": "docker-maven-plugin",
            "token": "project_token",
            "tags": {
                "status": [
                    "production"
                ]
            }

Back to top.

Get Product Project Tags

This API request enables you to get the project tags (keys & values) of all projects in a product.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns all the project tags in a product. NOTE: Products without tags are also returned.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
productToken

API key which is a unique

Unique identifier of the product.

string

Yes

Request Example

Code Block
{ "requestType" : "getProductProjectTags", "userKey": "user_key", "productToken" : "product_token" }

...

Code Block

{
    "projectTags": [
        {
            "name": "NewPy",
            "token": "project_token",
            "tags": {}
        },
        {
            "name": "maven-simple",
            "token": "project_token",
            "tags": {}
        },
        {
            "name": "docker-maven-plugin",
            "token": "project_token",
            "tags": {
                "status": [
                    "production"
                ]
            }
        }
    ]
}

Back to top.

Get Project Tags

This API request enables you to get the project tags (keys & values) in a project.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns all the keys and values of a project’s tags. NOTE: Projects without tags are also returned.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

API key which is a unique

Unique identifier of the project.

string

Yes

Request Example

Code Block
{ "requestType" : "getProjectTags", "userKey": "user_key", "projectToken" : "project_token" }

...

Code Block
{ "projectTags":[ { "name": "My Project 1", "token": "project_token_1", "tags":{ "Component": "Database", "Module": "Server" } }, { "name": "My Project 2", "token": "project_token_2", "tags":{} } ] }

Back to top.

Save a Project Tag

This API request enables you to save a project’s tag: key, value.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that saves a project’s tag.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

API key which is a unique

Unique identifier of the project.	string	Yes
tagKey	Label that describes the tag.	string	Yes
tagValue	Value assigned to the tag.	string	Yes

Request Example

Code Block
{ "requestType" : "saveProjectTag", "userKey": "user_key", "projectToken" : "project_token", "tagKey":"key1", "tagValue":"value1" }

...

Code Block
{ "projectTags": { "name": "My Project 1", "token": "project_token_1", "tags": { "key1": "value1" } } }

Back to top.

Get Project Hierarchy

This API request returns a hierarchy of the libraries in a project including In-House library data if required.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that gets a hierarchy of the libraries in a project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

Project token which identifies

Unique identifier of the project.	string	Yes
includeInHouseData	Set to “true” (default value) when you want in-house library data to be included in the API response. When set to ‘false’, in-house library data is not returned in the API response.	boolean	No

Request Example

Code Block
{ "requestType" : "getProjectHierarchy", "userKey": "user_key", "projectToken" : "project token", "includeInHouseData" : true }

...

Code Block

{
  "libraries": [
    {
      "keyUuid": "1f9ee6ec-eded-45d3-8fdb-2d0d735e5b14",
      "keyId": 43,
      "filename": "log4j-1.2.17.jar",
      "name": "log4j",
      "groupId": "log4j",
      "artifactId": "log4j",
      "version": "1.2.17",
      "sha1": "5af35056b4d257e4b64b9e8069c0746e8b08629f",
      "type": "UNKNOWN_ARTIFACT",
      "coordinates": "log4j:log4j:1.2.17"
    },
    {
      "keyUuid": "f362c53f-ce25-4d0c-b53b-ee2768b32d1a",
      "keyId": 45,
      "filename": "akka-actor_2.11-2.5.2.jar",
      "name": "akka-actor",
      "groupId": "com.typesafe.akka",
      "artifactId": "akka-actor_2.11",
      "version": "2.5.2",
      "sha1": "183ccaed9002bfa10628a5df48e7bac6f1c03f7b",
      "type": "MAVEN_ARTIFACT",
      "coordinates": "com.typesafe.akka:akka-actor_2.11:2.5.2",
      "dependencies": [
        {
          "keyUuid": "49c6840d-bf96-470f-8892-6c2a536c91eb",
          "keyId": 44,
          "filename": "scala-library-2.11.11.jar",
          "name": "Scala Library",
          "groupId": "org.scala-lang",
          "artifactId": "scala-library",
          "version": "2.11.11",
          "sha1": "e283d2b7fde6504f6a86458b1f6af465353907cc",
          "type": "MAVEN_ARTIFACT",
          "coordinates": "org.scala-lang:scala-library:2.11.11"
        },
        {
          "keyUuid": "426c0056-f180-4cac-a9dd-c266a76b32c9",
          "keyId": 47,
          "filename": "config-1.3.1.jar",
          "name": "config",
          "groupId": "com.typesafe",
          "artifactId": "config",
          "version": "1.3.1",
          "sha1": "2cf7a6cc79732e3bdf1647d7404279900ca63eb0",
          "type": "UNKNOWN_ARTIFACT",
          "coordinates": "com.typesafe:config:1.3.1"
        }
      ]
    },
    {
      "keyUuid": "25a8ceaa-4548-4fe4-9819-8658b8cbe9aa",
      "keyId": 48,
      "filename": "kafka-clients-0.10.2.1.jar",
      "name": "Apache Kafka",
      "groupId": "org.apache.kafka",
      "artifactId": "kafka-clients",
      "version": "0.10.2.1",
      "sha1": "3dd2aa4c9f87ac54175d017bcb63b4bb5dca63dd",
      "type": "MAVEN_ARTIFACT",
      "coordinates": "org.apache.kafka:kafka-clients:0.10.2.1",
      "dependencies": [
        {
          "keyUuid": "71065ffb-e509-4e2d-88bc-9184bc50888d",
          "keyId": 49,
          "filename": "lz4-1.3.0.jar",
          "name": "LZ4 and xxHash",
          "groupId": "net.jpountz.lz4",
          "artifactId": "lz4",
          "version": "1.3.0",
          "sha1": "c708bb2590c0652a642236ef45d9f99ff842a2ce",
          "type": "MAVEN_ARTIFACT",
          "coordinates": "net.jpountz.lz4:lz4:1.3.0"
        },
        {
          "keyUuid": "e44ab569-de95-4562-8efa-a2ebfe808471",
          "keyId": 50,
          "filename": "slf4j-api-1.7.21.jar",
          "name": "SLF4J API Module",
          "groupId": "org.slf4j",
          "artifactId": "slf4j-api",
          "version": "1.7.21",
          "sha1": "139535a69a4239db087de9bab0bee568bf8e0b70",
          "type": "MAVEN_ARTIFACT",
          "coordinates": "org.slf4j:slf4j-api:1.7.21"
       }
      ]
    }
  ]
}

Back to top.

Get Project Inventory

This API request returns an inventory (BOM - Bill of Materials) of all the libraries in a project, including In-House library data if required.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that gets an inventory of the libraries in a project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

Project token which identifies

Unique identifier of the project.	string	Yes
includeInHouseData	Set to “true” (default value) when you want in-house library data to be included in the API response. When set to ‘false’, in-house library data is not returned in the API response.	boolean	No

Request Example

Code Block
{ "requestType" : "getProjectInventory", "userKey": "user_key", "projectToken" : "project_token", "includeInHouseData" : true }

...

Code Block

{"projectVitals":{
"productName": "fsa",
"name": "fsa",
"token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"creationDate": "2017-06-17 07:12:29",
"lastUpdatedDate": "2017-06-17 07:34:31"
},
"libraries":[
{
"keyUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"keyId": 24559109,
"name": "comm-2.0.3.jar",
"artifactId": "comm-2.0.3.jar",
"type": "MAVEN_ARTIFACT",
"licenses":[],
"vulnerabilities":[],
"outdated": false,
"matchType": "FILENAME"
}]}

Back to top.

Get Project State

This API request returns the current status of a project including the last process that was performed on the project and its date, and whether the process is currently in progress.

The projectState response can have one of the following values:

SETUP: Initializing project
DIFF: Calculating inventory changes
UPDATE: Updating inventory
CHANGE_EXCLUSIONS: Updating dependency exclusions
CHANGE_LOCAL_PATHS: Updating library paths
REMOVE: Removing libraries
PARTNER_UPDATE: Updating inventory
UPDATE_ALERTS: Updating alerts
CREATE_ISSUES: Creating external tickets

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that gets the current state of a project.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

Project token which identifies

Unique identifier of the project.

string

Yes

Request Example

Code Block
{ "requestType":"getProjectState", "userKey": "user_key", "projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

...

Code Block
{ "projectState": { "lastProcess": "SETUP", "inProgress": false, "date": "2020-03-09" } }

Back to top.

Get Project Library Source Files

This API request returns the source files of a library in a project.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that gets a library’s source files.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

Project token which identifies

Unique identifier of the project.	integer	Yes
keyUuid	Unique ID of the library containing the source files.	integer	Yes

Request Example

Code Block
{ "requestType":"getLibrarySourceFiles", "userKey": "user_key", "projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "keyUuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

...

Code Block

{"sourceFiles":[{
	"sha1":"6bf3b8ddfecac64a916ba69de50e9faac70992ba",
	"name":"x509_obj.c",
	"path":"C:\\Users\\Work1\\Documents\\FSA\\GITHUB-downloads\\openssl_openssl_OpenSSL_0_9_4_openssl_openssl_OpenSSL_0_9_4_crypto_x509_x509_obj.c"}]
}

Back to top.

Get Project Library Dependencies

This API request returns the dependencies of a library in a project.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that gets a library’s dependencies.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
projectToken

Project token which identifies

Unique identifier of the project.	integer	Yes
keyUuid	Unique ID of the library containing the dependencies.	integer	Yes

Request Example

Code Block
{ "requestType":"getProjectLibraryDependencies", "userKey": "user_key", "projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "keyUuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

...

Code Block

{
   "dependencies":[
     [
      {
         "keyUuid":"0b6a3818-ed95-4190-b40d-0d0d9ca51166",
         "name":"CDI APIs",
         "groupId":"javax.enterprise",
         "artifactId":"cdi-api",
         "version":"1.0",
         "classifier":"",
         "scope":"COMPILE",
         "extension":"jar",
         "sha1":"44c453f60909dfc223552ace63e05c694215156b",
         "dependencies":[
            {
               "keyUuid":"e8d725f6-081c-4e7d-b09c-3fadcb861a35",
               "name":"JSR-250 Common Annotations for the JavaTM Platform",
               "groupId":"javax.annotation",
               "artifactId":"jsr250-api",
               "version":"1.0",
               "classifier":"",
               "scope":"COMPILE",
               "extension":"jar",
               "sha1":"5025422767732a1ab45d93abfea846513d742dcf",
               "dependencies":[
               ],
               "licenses":[
                  {
                     "name":"CDDL 1.0",
                     "url":"http://www.opensource.org/licenses/CDDL-1.0"
                  }
               ]
            }
         ],
         "licenses":[
            {
               "name":"Apache 2.0",
               "url":"http://www.opensource.org/licenses/Apache-2.0"
            }
         ]
      },
      {
         "keyUuid":"b4264d26-09ca-4266-97ba-0bec7318d984",
         "name":"org.eclipse.sisu.inject",
         "groupId":"org.eclipse.sisu",
         "artifactId":"org.eclipse.sisu.inject",
         "version":"0.3.2",
         "classifier":"",
         "scope":"COMPILE",
         "extension":"jar",
         "sha1":"59044b92ec27cc6fda7a2d24b2cd6cec23f31d5b",
         "dependencies":[
         ],
         "licenses":[
            {
               "name":"Eclipse 1.0",
               "url":"http://www.opensource.org/licenses/EPL-1.0"
            }
         ]
      }
    ]
  ]
}

Back to top.

Define Project Setup Notification Configuration

This API request enables you to define and edit the configuration of the project’s email notifications rules on setup (such as, “Notify on Project Setup Completion”).

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that defines the project setup notification configuration.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes
action	The action that describes the type of notification: Custom, Enabled, or Disabled.	string	Yes
projectTagKeyRegex	The project tag key pattern that describes the notification rule. Must be a formatted regex valid string. Notifications will be sent when the projectTagKeyRegex and projectTagValueRegex patterns are in accordance with the defined project tags.	string	Required only if the action is Custom.
projectTagValueRegex	The project tag value pattern that describes the notification rule. Must be a formatted regex valid string. Notifications will be sent when the projectTagKeyRegex and projectTagValueRegex patterns are in accordance with the defined project tags.	string	Mandatory only if the action is Custom.

Request Example

Code Block

{ 
  "requestType" : "setProjectSetupNotificationConfig", 
  "orgToken" : "organization_api_key", 
  "userKey" : "user_api_key", 
  "action": "CUSTOM", 
  "projectTagKeyRegex" : "^[0-9]*$", 
  "projectTagValueRegex" : "^(ProjectTagValue)" 
}

...

Code Block
{ "message": "Successfully changed project setup completion notification configuration" }

Back to top.

Get Plugin Request State

This API request returns the current status of a plugin request and its date and time.

NOTE: Although an Organization token is required in the API request, a product administrator can also execute it.

QUERY PARAMETERS

Parameter	Description	Type	Required
requestType	API request type that returns the current progress of a request.	string	Yes
userKey	The ID of the user’s profile, which uniquely identifies the user in WhiteSource.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes
requestToken	Token that identifies the plugin request. Also called "support_token" - can be found in the data of the response returned from the server.	string	Yes

Request Example

Code Block
{ "requestType" : "getRequestState", "userKey": "user_key", "orgToken" : "organization_api_key", "requestToken" : "support_token" }

...

The timestamp field refers to GMT time.

Back to top.

Page Comparison

Versions Compared

Old Version 21

New Version 25

Key

Overview

Product-Level APIs

Create Product

QUERY PARAMETERS

Delete Product

QUERY PARAMETERS

Product Tags

Get Product Tags

QUERY PARAMETERS

Get Organization Product Tags

QUERY PARAMETERS

Save a Product Tag

QUERY PARAMETERS

Remove a Product Tag

QUERY PARAMETERS

Project-Level APIs

Create Project

QUERY PARAMETERS

Delete Project

QUERY PARAMETERS

Project Tags

Get Organization Project Tags

QUERY PARAMETERS

Get Product Project Tags

QUERY PARAMETERS

Get Project Tags

QUERY PARAMETERS

Save a Project Tag

QUERY PARAMETERS

Get Project Hierarchy

QUERY PARAMETERS

Get Project Inventory

QUERY PARAMETERS

Get Project State

QUERY PARAMETERS

Get Project Library Source Files

QUERY PARAMETERS

Get Project Library Dependencies

QUERY PARAMETERS

Define Project Setup Notification Configuration

QUERY PARAMETERS

Get Plugin Request State

QUERY PARAMETERS