# Reports API - Asynchronous

# Overview

This set of APIs generates reports asynchronously. There are API’s for the organization, products and individual projects.

The type of report to be generated is set with the **reportType** parameter in each API.

Additional parameters available with some of the **reportTypes** can be included in the API request by using the optional **filter** parameter, as shown in the examples.

> **Note:** Not only reports can be generated asynchronously. The `changeOriginLibrary` API request can be generated asynchronously to prevent timeouts in large organizations with many projects.
For details, see [Licenses and Libraries API | Change Origin Library](https://api-docs.mend.io/1.4/licenses-and-libraries-api#change-origin-library).


## generateOrganizationReportAsync

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | generateOrganizationReportAsync | string | Yes |
| **orgToken** | API key which is a unique identifier of the organization. | string | Yes |
| **userKey** | The ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **reportType** | OrgHistoryReport, OrgInventoryReport, OrgLicensesReport, OrgSourceFileInventoryReport, OrgClusterInventoryReport, OrgAlertsReport, OrgIgnoreAlertsReport, OrgResolvedAlertsReport, OrgSecurityAlertsReport, OrgLibrarySecurityAlertsReport, OrgVulnerabilityReport, OrgContainerVulnerabilityReport, OrgBugsReport, OrgMembersReport, OrgAttributesReport, OrgEffectiveLicensesReport, RiskReport, OrgInHouseReport, OrgLibraryLocationReport, PluginPolicyViolationReport, PluginRequestHistoryReport, ChangeLogReport, OrgLicenseAndComplianceAlertReport, OrgEarlyWarningsAlertReport, OrgEarlyWarningsReport, OrgEffectiveUsageAnalysisReport | string | Yes |
| **format** | json, xlsx, xml, pdf (where **xlsx** is available, it is also the default)Not all formats are available for all report types. Refer to the synchronous counterpart of each report to see which formats are available for it. | string | Yes |
| **filter** | Any additional parameters, as listed individually for each reportType on the synchronous reports page | object | No |


#### **Request Example**


```
{
    "requestType" : "generateOrganizationReportAsync",
    "orgToken" : "organization_api_key",
    "userKey": "user_key",
    "reportType": "OrgLibrarySecurityAlertsReport",
    "format" : "json",
    "filter" : {
        "status": “active”
    }
}
```

**Response**


```
{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "DOMAIN",
        "processType":  "DOMAIN_VULNERABILITIES",
        "userEmail":  "adam.smith@whitesourcesoftware.com",
        "messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
        "status": "PENDING",
        "created":  "2022-4-15 11:45:20",
        "modified":  "2022-4-15 11:45:20",
    }
}
```

## generateProductReportAsync

#### PARAMETERS

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | generateProductReportAsync | string | Yes |
| **productToken** | API key which is a unique identifier of the product. | string | Yes |
| **userKey** | The ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **reportType** | ProductHistoryReport, ProductInventoryReport, ProductLicenseCompatibilityReport, ProductLicensesReport, ProductSourceFileInventoryReport, ProductClusterInventoryReport, ProductAlertsReport, ProductIgnoreAlertsReport, ProductResolvedAlertsReport, ProductSecurityAlertsReport, ProductLibrarySecurityAlertsReport, ProductVulnerabilityReport, ProductContainerVulnerabilityReport, ProductBugsReport, ProductMembersReport, ProductAttributesReport, ProductEffectiveLicensesReport, ProductDiffReport, RiskReport, ProductAttributionReport, ProductInHouseReport, ProductLibraryLocationReport, ProductLicenseAndComplianceAlertReport, ProductEarlyWarningsAlertReport, ProductEarlyWarningsReport, ProductSBOMReport | string | Yes |
| **format** | json, xlsx, xml, pdf (where **xlsx** is available, it is also the default)> [!INFO]> Note:> *   Not all formats are available for all report types. Refer to the synchronous counterpart of each report to see which formats are available for it. | string | Yes |
| **filter** | Any additional parameters, as listed individually for each reportType on the synchronous reports page | object | No |


#### **Request Example**


```
{
    "requestType" : "generateProductReportAsync",
    "productToken" : "product_api_key",
    "userKey": "user_key",
    "reportType": "ProductAttributesReport",
    "format" : "xlsx",
    "filter" : {
        "reportingScope": “licenses”,
        "reportingAggregationMode": "BY_PROJECT"
    }
}
```

**Response**


```
{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "DOMAIN",
        "processType":  "DOMAIN_VULNERABILITIES",
        "userEmail":  "adam.smith@whitesourcesoftware.com",
        "messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
        "status": "PENDING",
        "created":  "2022-4-15 11:45:20",
        "modified":  "2022-4-15 11:45:20",
    }
}
```

## generateProjectReportAsync

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | generateProjectReportAsync | string | Yes |
| **projectToken** | API key which is a unique identifier of the project. | string | Yes |
| **userKey** | The ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **reportType** | ProjectHistoryReport, ProjectInventoryReport, ProjectLicenseCompatibilityReport, ProjectLicensesReport, ProjectSourceFileInventoryReport, ProjectAlertsReport, ProjectIgnoreAlertsReport, ProjectResolvedAlertsReport, ProjectSecurityAlertsReport, ProjectLibrarySecurityAlertsReport, ProjectVulnerabilityReport, ProjectContainerVulnerabilityReport, ProjectBugsReport, ProjectMembersReport, ProjectDiffReport, RiskReport, AttributionReport, ProjectInHouseReport, ProjectLibraryLocationReport, ProjectLicenseAndComplianceAlertReport, ProjectEarlyWarningsAlertReport, ProjectEarlyWarningsReport, ProjectSBOMReport | string | Yes |
| **format** | json, xlsx, xml, pdf (where **xlsx** is available it is also the default)Not all formats are available for all report types. Refer to the synchronous counterpart of each report to see which formats are available for it. | string | Yes |
| **filter** | Any additional parameters, as listed individually for each reportType on the synchronous reports page | object | No |


#### **Request Example**


```
{
    "requestType" : "generateProjectReportAsync",
    "projectToken" : "project_api_key",
    "userKey": "user_key",
    "reportType": "ProjectInventoryReport",
    "format" : "pdf",
    "filter" : {
        "reportingScope": “summary”,
        "includeVersions": "true"
    }
}
```

**Response Example**


```
{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "DOMAIN",
        "processType":  "DOMAIN_VULNERABILITIES",
        "userEmail":  "adam.smith@whitesourcesoftware.com",
        "messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
        "status": "PENDING",
        "created":  "2022-4-15 11:45:20",
        "modified":  "2022-4-15 11:45:20",
    }
}
```

## SBOM Reporting

This is a new report type that collects the various options for SBOM reporting into a single API request based on scope (product or project).

### ProductSBOMReport

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | generateProductReportAsync | string | Yes |
| **projectToken** | API key which is a unique identifier of the product.. | string | Yes |
| **userKey** | The ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **reportType** | ProductSBOMReport | string | Yes |
| **standard** | SPDX (case insensitive)CycloneDX (case insensitive) | string | Yes |
| **version** | The SBOM standard version. The available values for SPDX: “2.2” (default) or “2.3”. For CycloneDX “1.4” (default) or “1.5”. | string | No |
| **format** | SPDX: XML, YAML, JSON, TV, XLSX (case insensitive),CycloneDX: XML, JSON (case insensitive) | string | Yes |
| **maxDepthLevel** | The depth in the dependency tree to include in the report. Where the top level is 0.> [!INFO]> **Note:** Only supported by the CycloneDX standard. | number | Default: 0  (top level only) |
| **includeVulnerabilities** | A boolean parameter that controls whether or not to include vulnerabilities in the SBOM report. | boolean | No (Default: true) |


#### **Request Example**


```
{
    "requestType": "generateProductReportAsync",
    "productToken": "<productToken>",
    "userKey": "<userKey>",
    "reportType":"ProductSBOMReport",
    "standard":"cyclonedx",
    "includeVulnerabilities":"false",
    "format":"json"
}
```

#### **Response**

The response is the requested report file.

### ProjectSBOMReport

| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | generateProjectReportAsync | string | Yes |
| **projectToken** | API key which is a unique identifier of the project. | string | Yes |
| **userKey** | the ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **reportType** | ProjectSBOMReport | string | Yes |
| **standard** | SPDX (case insensitive)CycloneDX (case insensitive) | string | Yes |
| **version** | The SBOM standard version. The available values for SPDX: “2.2” (default) or “2.3”. For CycloneDX “1.4” (default) or “1.5”. | string | No |
| **format** | SPDX: XML, YAML, JSON, TV, XLSX (case insensitive),CycloneDX: XML, JSON (case insensitive) | string | Yes |
| **maxDepthLevel** | The depth in the dependency tree to include in the report. Where the top level is 0.> [!INFO]> **Note:** Only supported by the CycloneDX standard. | number | default: 0  (top level only) |
| **includeVulnerabilities** | A boolean parameter that controls whether or not to include vulnerabilities in the SBOM report. | boolean | No (Default: true) |


#### **Request Example**


```
{
    "requestType": "generateProjectReportAsync",
    "projectToken": "<projectToken>",
    "userKey": "<userKey>",
    "reportType":"ProjectSBOMReport",
    "standard":"spdx",
    "format":"json"
}
```

#### **Response**


```
{
    "asyncProcessStatus": {
        "uuid": "527cd6d7-74f9-4f3c-9a25-16e01550db86",
        "requestToken": "24460c1f47b544f039804ef039762265d1678743921551",
        "contextId": 1538167,
        "contextType": "PROJECT",
        "processType": "PROJECT_SBOM_REPORT",
        "userEmail": "adam.smith@whitesourcesoftware.com",
        "messageContentSha1": "a830df5dcbee9d36045d9f2ec90496bd31a2cf30",
        "status": "PENDING",
        "created": "2023-03-13 21:45:21",
        "modified": "2023-03-13 21:45:21"
    }
}
```

## getAsyncProcessStatus

The **status** of the requested report is checked using **getAsyncProcessStatus**. The **status** parameter will contain one of these four values:

* PENDING
* IN_PROGRESS
* FAILED
* SUCCESS


| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | getAsyncProcessStatus | string | Yes |
| **orgToken** | API key which is a unique identifier of the organization. | string | Yes |
| **userKey** | The ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **uuid** | The UUID returned in the response from one of the “**GenerateXXReportAsync**” APIs | string | Yes |


#### **Request Example**


```
{
    "requestType" : "getAsyncProcessStatus",
    "orgToken" : "organization_api_key",
    "userKey": "user_key",
    "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9"
}
```

**Response**


```
{
    "asyncProcessStatus": {
        "uuid": "36466e69-bda1-43d3-9962-6f3a341720b9",
        "requestToken": "1231620fd0f8940c4bd03a866ef12cacd1599886073438",
        "contextId": "244934",
        "contextType": "DOMAIN",
        "processType":  "DOMAIN_VULNERABILITIES",
        "userEmail":  "adam.smith@whitesourcesoftware.com",
        "messageContentSha1": "b480c892e59a2f05954ce727bd3f2a4e882f9e13",
        "status": "SUCCESS",
        "created":  "2022-4-15 11:45:20",
        "modified":  "2022-4-15 11:45:20",
    }
}
```

Once the **status** of the report returns **SUCCESS**, the report is ready for download using the **downloadAsyncReport** API.

## downloadAsyncReport

> **Note:** All of the APIs and their responses in this article have the “uuid” flag as “uuid”, **except for downloadAsyncReport**, which calls for a “**reportStatusUUID**” instead of “uuid” value. This value is the same as the “uuid” value, the naming is just different.


| **Parameter** | **Description** | **Type** | **Required** |
|  --- | --- | --- | --- |
| **requestType** | downloadAsyncReport | string | Yes |
| **orgToken** | API key which is a unique identifier of the organization. | string | Yes |
| **userKey** | The ID of the user’s profile, which uniquely identifies the user in Mend. | string | Yes |
| **reportStatusUUID** | The UUID returned in the response from one of the “**GenerateXXReportAsync**” APIs | string | Yes |


#### **Request Example**


```
{
  "requestType" : "downloadAsyncReport",
  "orgToken" : {{orgToken}},
  "userKey" : {{userKey}},
  "reportStatusUUID" :{{asyncProcessStatus.uuid}}
}
```

#### **Response**

The response is the requested report file.

> **Notes**:
* The report is downloaded as a ZIP file that contains the actual report file.
* For very large reports, multiple files will be included in the exported ZIP.