Skip to main content
API docs by Redocly

ReversingLabs Spectra Assure API (1.0)

Download OpenAPI specification:Download

ReversingLabs Support: support@reversinglabs.com URL: https://www.reversinglabs.com/ License: Proprietary

About the API

ReversingLabs Spectra Assure Portal is a SaaS solution for comprehensive and collaborative software development management. With the Portal, you can scan your software packages, organize them into projects, and automatically compare package versions to detect potentially dangerous behavior changes in the code. The Portal is designed to help you improve security of your development practices and software release processes from start to finish.

The Spectra Assure API is a companion solution to the Portal. It allows you to automate common actions such as creating projects and packages, uploading package versions, and exporting analysis reports in supported formats.

API versioning

The current Spectra Assure API version is v1, which is indicated in all request paths.

Servers

All request paths use the following server URL format:

https://{portalUrl}/api/public/{apiVersion}

where {portalUrl} is the URL of the Portal instance that you want to access from the API.

Typically, the Portal instance will be a subdirectory of my.secure.software, so an example {portalUrl} could be my.secure.software/demo.

With that example, the full server URL would be:

https://my.secure.software/demo/api/public/v1

All requests must be made over HTTPS. This API does not support HTTP.

Authentication

All endpoints in the Software Supply Chain Security (SSCS) Public API require Bearer authentication.

To authenticate to the API, you need to create a Personal Access Token in your Portal account settings.

The Personal Access Token must be provided in the Authorization: Bearer HTTP header of every request.

Make sure to treat your tokens as confidential. If you suspect any of your tokens has been compromised, revoke it in your Portal account settings and generate a new one.

Rate limiting

To ensure safe and stable service operation, ReversingLabs enforces rate limits on all Spectra Assure Portal API endpoints.

Two types of rate limits apply:

  • Sustain limit = maximum allowed volume of continuous requests over a period of time

  • Burst limit = maximum allowed amount of concurrent requests in a short time interval

All rate limits are enforced per user, with each user identified by their Personal Access Token.

Rate limiting is implemented as a "hard stop" on API endpoint usage. Users who exceed a rate limit receive the 429 Too Many Requests error response and cannot make any requests until the service becomes available again. The Retry-After HTTP header in the response indicates how many seconds to wait before sending the request again.

The following table provides an overview of all rate limits that apply to your API usage.

API endpoint Rate limit
All endpoints Sustain limit: 86400 requests in the last 24 hours per user across all endpoints combined.
All endpoints Burst limit: 300 requests / minute per user across all endpoints combined.
Upload and scan a version 30 requests / minute
Show analysis status 10 requests / minute when using the download query parameter to request the file download link.
Export analysis report 30 requests / minute

Rate limits are cumulative - a single request counts towards all rate limits that apply. For example, if the burst limit is 3 requests/minute and the sustain limit is 100 requests within 24 hours, sending 5 requests in under a minute will exceed the burst limit and will count towards the sustain limit.

If you notice the API rate limits may not be properly set for your Spectra Assure Portal account, contact ReversingLabs Support.

Responses and error handling

Successful requests return 2xx status codes.

Errors are indicated by 4xx and 5xx status codes. In some cases, the JSON response will contain a more informative message about the problem in the error key. Expected responses and status codes are listed for every endpoint in this reference documentation.

The following table provides an overview of all expected error responses and suggested resolution steps.

Status code Description
400 Bad request Usually indicates a syntax error in the request. Confirm that all parts of your request are correctly formatted and make sure you're not using any unsupported characters.
401 Not authorized The service is not able to authenticate you with the information provided in the request. This may be caused by a missing, malformed, expired, or revoked token. Make sure you're correctly providing the token in the Authorization: Bearer header in your requests.
402 Insufficient remaining capacity Usually indicates a licensing issue. The service is not able to fulfill your request because it would exceed the capacity configured for your organization and groups in the Portal. Contact your Organization Administrator for help, or review the usage reservations in Settings > Analysis Capacity in the Portal.
403 Forbidden You don't have permission to access the requested resource. This may be because the Portal account associated with your token does not have the correct role assigned to it, or the resource is outside of its scope. Check if you can perform the requested action directly in the Portal instead of with the API. If the issue persists, contact your Organization Administrator for help.
404 Not found The resource you're trying to access doesn't exist in the Portal. Check if the endpoint is correctly formatted in your request, and make sure all required parameters are present. This response is also returned if an unsupported protocol is used in the request (for example, HTTP instead of HTTPS).
409 Resource already exists Project, package, or version you're trying to create already exists in the Portal. Try to change the name of the resource in a new request. For versions, you can use the replace query parameter to overwrite an existing version.
429 Too many requests The service detected an excessive amount of requests from your account in a short period. You may have exceeded the rate limits defined in the "Rate limiting" section. Review the tools and applications you use to work with the API to make sure they're not sending redundant requests.
500 Internal server error Usually indicates an issue with the service itself. Try re-sending your request later. If the issue persists, contact ReversingLabs Support.

Version

Endpoints in this category help you work with software package versions in your Portal projects.

Upload and scan a version

Scan a file and add it as a new package version to a project in the Portal. If the project or package specified in the request don't exist in the Portal, they will be automatically created.

If the package version specified in the request already exists in the package, the API returns the 409 error response. You can repeat the request with the replace parameter in the query to overwrite the existing version.

To add a reproducible build artifact to an existing package version, use the build query parameter set to the repro value (?build=repro). If a reproducible build artifact already exists for a package version, the API returns a 400 error response. In this case, you should repeat the request with the replace query parameter set to true.

Only one file (main package version artifact or reproducible build artifact) can be uploaded per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

query Parameters
build
string
Default: "version"
Enum: "repro" "version"

This optional parameter should be used when working with reproducible builds. Specify if the request should apply to the main artifact (version) or to the reproducible build artifact (repro). Only one of the two supported values can be specified per request.

replace
boolean
Default: false

This optional parameter lets you replace (overwrite) an already existing package version in the project with the package version you're uploading. This functionality is equivalent to the --replace option in the rl-secure scan command.

If this parameter is omitted or set to false and the package version you're trying to upload already exists in the specified project, the API returns the 409 error response.

force
boolean
Default: false

In the Portal, a package can only have a limited amount of versions. If a package already has the maximum number of versions, you can use this optional parameter to specify if the oldest version of the package should be deleted to make space for the version you're uploading.

If this parameter is omitted or set to false and the package already has the maximum allowed number of versions, the API returns the 400 error response.

This parameter is incompatible with build=repro.

diff_with
string
Example: diff_with=1.1.0

This optional parameter lets you specify a previous package version against which you want to compare (diff) the version you're uploading. The specified version must exist in the package. This functionality is equivalent to the --diff-with option in the rl-secure report command.

This parameter is incompatible with build=repro.

product
string (VersionMetadataProduct) <= 200 characters
Example: product=Example application

Software product name

publisher
string (VersionMetadataPublisher) <= 200 characters
Example: publisher=Example software publisher

Software publisher

category
string
Default: "Other"
Enum: "Ad" "Administration" "Analytics" "Audio" "Browser" … 32 more

Categorization scheme for software based on their typical use or general purpose.

license
string
Default: "Unknown"
Enum: "3dfx Glide License" "AMD's plpa_map.c License" "ANTLR Software Rights Notice" "ANTLR Software Rights Notice with license fallback" "Abstyles License" … 454 more

SPDX-compliant license name under which the software is distributed.

platform
string
Default: "Other"
Enum: "Browser" "Containers" "Linux" "MacOS" "Mobile" … 2 more

Underlying technology or framework that the software has been developed to run on.

release_date
string <date-time>
Example: release_date=2022-07-15T13:57:39.843631Z

Date and time to set and display as the release date for the software package version in the Portal. When this parameter is omitted from the request, the version is considered unreleased. You can change the release status at any time directly through the Portal interface or through the API with the Modify a version endpoint.

header Parameters
Content-Disposition
required
string
Example: attachment; filename=upload.exe

Specify the name of the uploaded file preceded by the attachment parameter. This file name will be visible in the analysis reports.

Request Body schema: application/octet-stream
string <binary>

File to be uploaded to the Portal.

Responses

Request samples 

curl -L 'https://your-portal-url/api/public/v1/scan/your-organization/your-group/pkg:rl/your-project/your-package@v1?product=7zip&platform=Windows' \
-H 'Authorization: Bearer your-personal-access-token' \
-H 'Content-Type: application/octet-stream' \
-H 'Content-Disposition: attachment; filename=7z1514-x64.msi' \
--data-binary '@/home/armando/software/7z1514-x64.msi' \

Response samples

Content type
text/plain
Created

Show analysis status

Check the analysis status of a package version that was previously uploaded to the Portal. If the version has been successfully analyzed, the response includes a summary of the analysis report.

To retrieve the full analysis report in any of the supported formats, use the Export analysis report endpoint.

By default, this endpoint returns the status of the main (representative) artifact in the version. To check the status of a reproducible build artifact, use the build query parameter set to the repro value. If a reproducible build artifact doesn't exist for the requested package version, the API returns an error response.

Note that this endpoint returns the analysis status of the requested file (either the main package version artifact or the reproducible build artifact). It doesn't include details on the checks that were performed during analysis. To view that information, use the Show performed checks endpoint.

Optionally, this endpoint can return a short-lived download link for the main artifact or the reproducible build artifact if the download query parameter is used. With the build query parameter, specify for which artifact the download link should be generated. If the build parameter is omitted from the request, the download link is generated for the main artifact.

The download link is valid only for 60 seconds, after which it can be requested again. Every time the download link is generated, the Portal Download Capacity is reduced by the artifact's file size, even if the artifact is not downloaded from the link. To download the artifact, the user account that is sending the request must have the appropriate permissions. If the user account doesn't have permission to download files from the Portal, the endpoint responds with an error and the Download Capacity remains unaffected.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

query Parameters
build
string
Default: "version"
Enum: "repro" "version"

This optional parameter should be used when working with reproducible builds. Specify if the request should apply to the main artifact (version) or to the reproducible build artifact (repro). Only one of the two supported values can be specified per request.

download
boolean
Default: false

Returns a short-lived link where you can download the main version artifact or the reproducible build artifact. Use the build parameter in the request to specify the artifact to download. The link is valid for 60 seconds. The link generation affects the Portal Download Capacity even if the artifact is not downloaded.

Responses

Request samples 

curl -L 'https://your-portal-url/api/public/v1/status/your-organization/your-group/pkg:rl/your-project/your-package@v1' \
-H 'Authorization: Bearer your-personal-access-token'

Response samples

Content type
application/json
{
  • "analysis": {
    • "schema": "2",
    • "timestamp": "2019-08-24T14:15:22Z",
    • "version": "5.0.0.0",
    • "duration": "00:07:49.859",
    • "status": "DONE",
    • "report": {
      }
    }
}

Show performed checks

Displays a summary of all checks that were performed by Spectra Assure for the requested package version. This includes software analysis, diff checks (comparison against another package version) and reproducible build checks (comparison of the main package version artifact against a reproducible build artifact).

The response is aligned with the rl-checks report format schema.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Request samples 

curl -L 'https://your-portal-url/api/public/v1/checks/your-organization/your-group/pkg:rl/your-project/your-package@v1' \
-H 'Authorization: Bearer your-personal-access-token'

Response samples

Content type
application/json
{
  • "analysis": {
    • "schema": 2,
    • "timestamp": "2024-03-25T10:07:27Z",
    • "version": "5.0.0.0",
    • "duration": "00:07:49.859",
    • "report": {
      }
    }
}

Export analysis report

Download the analysis report for the specified package version. By default, the endpoint returns the report for the main (representative) artifact in the package version. To download the report for a reproducible build artifact, use the build query parameter set to the repro value.

If a reproducible build artifact does not exist for the requested package version, the API returns a 400 error response.

The following report formats are supported:

Only one report type can be downloaded per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

report_type
required
string
Enum: "cyclonedx" "rl-checks" "rl-cve" "rl-json" "rl-uri" … 2 more

Specify the report type to export and download. The API returns the report as a standalone file. This functionality is equivalent to the --format option in the rl-secure report command.

query Parameters
build
string
Default: "version"
Enum: "repro" "version"

This optional parameter should be used when working with reproducible builds. Specify if the request should apply to the main artifact (version) or to the reproducible build artifact (repro). Only one of the two supported values can be specified per request.

Responses

Request samples 

curl -L 'https://your-portal-url/api/public/v1/report/your-organization/your-group/spdx/pkg:rl/your-project/your-package@v1' \
-H 'Authorization: Bearer your-personal-access-token'

Response samples

Content type
application/octet-stream
Report file to download

Show version details

Display basic information about a package version that was previously uploaded to a project in the Portal. The information includes the current release status of the package version and the details about file approval for third-party risk management workflows.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Response samples

Content type
application/json
{
  • "version": "5.5.8",
  • "is_released": true,
  • "software_info": {
    • "product": "Inno Setup",
    • "version": "5.5.8",
    • "publisher": "jrsoftware.org",
    • "category": "Other",
    • "license": "Unknown",
    • "platform": "Windows",
    • "release_date": "string"
    },
  • "approval_status": "ApprovalRejected",
  • "approval_information": {
    • "reason": "Rejected because of valid reasons",
    • "timestamp": "2022-07-15T13:57:39.843631Z",
    • "user": "user@foo.bar",
    • "role": "GroupOwner"
    }
}

Modify a version

Update the information about a package version that was previously uploaded to a project in the Portal. With this endpoint, you can change the release status of a package version and modify parts of the package version metadata (product name, publisher name, software category, license, platform, and release date). Only one package version can be modified per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
is_released
boolean

Indicates whether the software package version should be displayed as released or not in the Portal interface.

product
string (VersionMetadataProduct) <= 200 characters
Example: "Example application"

Software product name

publisher
string (VersionMetadataPublisher) <= 200 characters
Example: "Example software publisher"

Software publisher

category
string (SoftwareCategory)
Enum: "Ad" "Administration" "Analytics" "Audio" "Browser" … 32 more

Categorization scheme for software based on their typical use or general purpose.

license
string (SoftwareLicense)
Enum: "3dfx Glide License" "AMD's plpa_map.c License" "ANTLR Software Rights Notice" "ANTLR Software Rights Notice with license fallback" "Abstyles License" … 454 more

SPDX-compliant license name under which the software is distributed.

platform
string (SoftwarePlatform)
Enum: "Browser" "Containers" "Linux" "MacOS" "Mobile" … 2 more

Underlying technology or framework that the software has been developed to run on.

release_date
string <date-time>
Example: "2022-07-15T13:57:39.843631Z"

Date and time to set and display as the release date for the software package version in the Portal. If is_released is set to true and this parameter is omitted, the release date is automatically set to Unix time 0 (midnight UTC, 1 January 1970).

Responses

Request samples

Content type
application/json
{
  • "is_released": true,
  • "product": "Example application",
  • "publisher": "Example software publisher",
  • "category": "Ad",
  • "license": "3dfx Glide License",
  • "platform": "Browser",
  • "release_date": "string"
}

Response samples

Content type
text/plain
OK

Delete a version

Delete a package version that was previously uploaded to a project in the Portal. When you delete a package version, all its metadata is removed from the Portal, including analysis reports and any reproducible build artifacts.

If a package version has a reproducible build artifact, you can use the build query parameter set to the repro value to remove only that artifact without removing anything else. In this case, the main package version artifact and its metadata will be preserved.

To preserve analysis reports for the package version, use the Export analysis report endpoint to download the reports before deleting the version.

Only one package version can be deleted per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

query Parameters
build
string
Default: "version"
Enum: "repro" "version"

This optional parameter should be used when working with reproducible builds. Specify if the request should apply to the main artifact (version) or to the reproducible build artifact (repro). Only one of the two supported values can be specified per request.

Responses

Response samples

Content type
text/plain
Deleted

Approve a version

Set the approval status for the requested package version to Approved. The request will be successful only if the package version currently has one of the following approval statuses: Requires Approval, Rejected. Revoked package versions cannot be approved again.

Your user account must have one of the following roles to be able to approve package versions: Organization Administrator, Organization Security, Group Owner.

For auditing purposes, you can optionally specify the reason for approving the package version in the request body.

By default, all package versions uploaded to the Portal have the Requires Approval status.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
reason
string
Example: "No failing policy checks identified during analysis"

Optional reason for changing the approval status for the package version

Responses

Request samples

Content type
application/json
{
  • "reason": "No failing policy checks identified during analysis"
}

Response samples

Content type
text/plain
Approved

Reject a version

Set the approval status for the requested package version to Rejected. The request will be successful only if the package version currently has the Requires Approval status. Revoked package versions cannot have their status changed to Rejected.

For auditing purposes, you can optionally specify the reason for rejecting the package version in the request body.

Your user account must have one of the following roles to be able to reject package versions: Organization Administrator, Organization Security, Group Owner.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
reason
string
Example: "Alternate software selected for approval that poses less security risk"

Optional reason for changing the approval status for the package version

Responses

Request samples

Content type
application/json
{
  • "reason": "Alternate software selected for approval that poses less security risk"
}

Response samples

Content type
text/plain
Rejected approval

Revoke approval

Set the approval status for the requested package version to Revoked. The request will be successful only if the package version currently has the Approved status. When the approval status is set to Revoked, you can no longer change it back to Approved or Rejected.

For auditing purposes, you can optionally specify the reason for revoking approval in the request body.

Your user account must have one of the following roles to be able to revoke approval for package versions: Organization Administrator, Organization Security, Group Owner.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
reason
string
Example: "Fixing inadvertent or incorrect approval of software"

Optional reason for changing the approval status for the package version

Responses

Request samples

Content type
application/json
{
  • "reason": "Fixing inadvertent or incorrect approval of software"
}

Response samples

Content type
text/plain
Revoked approval

Sync version

Rescans the existing package version to synchronize it with the updated configuration or with the latest engine update. This action is equivalent to the Reanalyze action on the Portal.

Reanalyzing a package version does not count towards the monthly analysis capacity.

When you request reanalysis from this endpoint, the Portal automatically detects configuration changes or engine updates that would require synchronization. If there haven't been any changes, reanalysis is skipped and the API returns the 200 response. This means you don't need to manually check for configuration changes or engine updates prior to requesting reanalysis.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Response samples

Content type
text/plain
Version already in sync

Project

Endpoints in this category help you manage your projects in the Portal.

Create project

Create a new project in the specified Portal organization and group. The account you're using must have the appropriate permissions in the Portal organization to be able to create projects. Only one project can be created per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
description
string <= 500 characters
Example: "An example project"

Optional brief description to associate with the new project.

Responses

Request samples

Content type
application/json
{
  • "description": "An example project"
}

Response samples

Content type
text/plain
Created

Modify project details

Update the information about a project that was previously created in the Portal. With this endpoint, you can change the project name and the project description. The project name must be unique in the specified group. Only one project can be modified per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
name
string
Example: "New project name"

Name to associate with the project. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

description
string
Example: "New short project description"

Optional brief description to associate with the project.

Responses

Request samples

Content type
application/json
{
  • "name": "New project name",
  • "description": "New short project description"
}

Response samples

Content type
text/plain
OK

Delete a project

Delete a project that was previously created in the Portal. When you delete a project, all packages and package versions in the project are removed from the Portal along with their metadata. To preserve analysis reports for package versions in the project, use the Export analysis report endpoint to download them before deleting the project. Only one project can be deleted per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Response samples

Content type
text/plain
Deleted

List packages in a project

Display basic information about a project that was previously created in the Portal, along with the names of all packages in the project.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Response samples

Content type
application/json
{
  • "name": "My Project",
  • "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
  • "description": "This is an example project used for testing purposes",
  • "packages": [
    • {
      }
    ]
}

Package

Endpoints in this category help you manage software packages in your Portal projects.

Create package

Create a new package in the specified Portal organization, group, and project. If the project specified in the request doesn't already exist in the Portal, it will be automatically created.

All projects in a Portal organization can jointly contain at most 10,000 packages. The account you're using must have the appropriate permissions in the Portal organization to be able to create packages.

Only one package can be created per request. To add a version to the package, use the Upload package version endpoint.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
description
string <= 500 characters
Example: "This is my new package"

Optional brief description to associate with the new package.

Responses

Request samples

Content type
application/json
{
  • "description": "This is my new package"
}

Response samples

Content type
text/plain
Created

Modify package details

Update the information about a package that was previously created in a project in the Portal. With this endpoint, you can change the package name and description. The package name must be unique in the specified project. Only one package can be modified per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
name
string
Example: "New package name"

Name to associate with the package. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

description
string
Example: "New short package description"

Optional brief description to associate with the package.

Responses

Request samples

Content type
application/json
{
  • "name": "New package name",
  • "description": "New short package description"
}

Response samples

Content type
text/plain
OK

Delete a package from a project

Delete a package that was previously created in a project in the Portal. When you delete a package, all versions of that package are removed from the Portal along with their metadata. To preserve analysis reports for package versions, use the Export analysis report endpoint to download them before deleting the package. Only one package can be deleted per request.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Response samples

Content type
text/plain
Deleted

List package versions

Display basic information about a package that was previously created in a project in the Portal, along with all versions associated with the package.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

Responses

Response samples

Content type
application/json
{
  • "name": "ZoomInstaller",
  • "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
  • "description": "Windows packages for Zoom",
  • "versions": [
    • {
      }
    ]
}

Group

Endpoints in this category make it easier to work with groups in the Portal.

List groups in the organization

Return a list of groups that the requesting user has the permission to access. In the response, groups are listed in alphabetical order.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

Responses

Response samples

Content type
application/json
{
  • "groups": [
    • {
      }
    ]
}

List projects in a group

Return a list of all projects created in the requested group. Projects are listed in chronological order, from the oldest to the most recently created.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

Responses

Response samples

Content type
application/json
{
  • "name": "My group",
  • "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
  • "projects": [
    • {
      }
    ]
}

Approval

Endpoints in this category help you manage the approval status for software package versions in the Portal.

The following table explains which approval flows are supported by these API endpoints.

Approval flow API Details
Requires Approval -> Approved ✔️ By default, all package versions await approval and can be approved.
Requires Approval -> Rejected ✔️ By default, all package versions await approval and can be rejected.
Requires Approval -> Revoked ❌ There is nothing to revoke if the package version has not been approved yet.
Approved -> Revoked ✔️ A previously approved package version can have its approval status revoked.
Approved -> Rejected ❌ Contradictory action; use the revoke option instead.
Approved -> Requires Approval ❌ Approval status cannot be reset to the initial (undetermined) state.
Rejected -> Approved ✔️ A previously rejected package version can be approved.
Rejected -> Revoked ❌ There is nothing to revoke if the package version is not approved.
Rejected -> Requires Approval ❌ Approval status cannot be reset to the initial (undetermined) state.
Revoked -> Approved ❌ Revoked package versions cannot be approved again.
Revoked -> Rejected ❌ Revoked package versions cannot be rejected.
Revoked -> Requires Approval ❌ Approval status cannot be reset to the initial (undetermined) state.

Approve a version

Set the approval status for the requested package version to Approved. The request will be successful only if the package version currently has one of the following approval statuses: Requires Approval, Rejected. Revoked package versions cannot be approved again.

Your user account must have one of the following roles to be able to approve package versions: Organization Administrator, Organization Security, Group Owner.

For auditing purposes, you can optionally specify the reason for approving the package version in the request body.

By default, all package versions uploaded to the Portal have the Requires Approval status.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
reason
string
Example: "No failing policy checks identified during analysis"

Optional reason for changing the approval status for the package version

Responses

Request samples

Content type
application/json
{
  • "reason": "No failing policy checks identified during analysis"
}

Response samples

Content type
text/plain
Approved

Reject a version

Set the approval status for the requested package version to Rejected. The request will be successful only if the package version currently has the Requires Approval status. Revoked package versions cannot have their status changed to Rejected.

For auditing purposes, you can optionally specify the reason for rejecting the package version in the request body.

Your user account must have one of the following roles to be able to reject package versions: Organization Administrator, Organization Security, Group Owner.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
reason
string
Example: "Alternate software selected for approval that poses less security risk"

Optional reason for changing the approval status for the package version

Responses

Request samples

Content type
application/json
{
  • "reason": "Alternate software selected for approval that poses less security risk"
}

Response samples

Content type
text/plain
Rejected approval

Revoke approval

Set the approval status for the requested package version to Revoked. The request will be successful only if the package version currently has the Approved status. When the approval status is set to Revoked, you can no longer change it back to Approved or Rejected.

For auditing purposes, you can optionally specify the reason for revoking approval in the request body.

Your user account must have one of the following roles to be able to revoke approval for package versions: Organization Administrator, Organization Security, Group Owner.

path Parameters
organization
required
string
Example: example-organization

Specify the name of a Portal organization to use in the request. The user account that is sending the request must be a member of the specified organization and have the appropriate permissions to perform the requested operation. Organization names are case-sensitive.

group
required
string
Example: example-group

Specify the name of a Portal group to use in the request. The group must exist in the specified Portal organization. Group names are case-sensitive.

project
required
string
Example: example-project

Specify the name of a Portal project to use in the request. Project names are case-sensitive. Special characters \/:*?"<>| are not supported.

package
required
string
Example: example-package

Specify the name of a Portal package to use in the request. Package names are case-sensitive. Special characters \/:*?"<>| are not supported.

version
required
string
Example: 1.2.0

Specify the name of a Portal package version to use in the request. Version names are case-sensitive. Special characters \/:*?"<>| are not supported.

Request Body schema: application/json
reason
string
Example: "Fixing inadvertent or incorrect approval of software"

Optional reason for changing the approval status for the package version

Responses

Request samples

Content type
application/json
{
  • "reason": "Fixing inadvertent or incorrect approval of software"
}

Response samples

Content type
text/plain
Revoked approval