ReversingLabs Spectra Assure API (1.0)
Download OpenAPI specification:Download
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.
The current Spectra Assure API version is v1, which is indicated in all request paths.
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.
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.
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.
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. |
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 |
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 |
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 |
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 ( |
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 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 |
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 This parameter is incompatible with |
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 |
Request Body schema: application/octet-stream
File to be uploaded to the Portal.
Responses
Request samples
- Shell
- Python - Requests
- NodeJS - Request
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
- 201
- 400
- 401
- 402
- 403
- 404
- 409
- 429
- 500
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 |
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 |
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 |
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 ( |
download | boolean Default: false Returns a short-lived link where you can download the main version artifact or the reproducible build artifact. Use the |
Responses
Request samples
- Shell
- Python - Requests
- NodeJS - Request
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
- 200
- 400
- 401
- 403
- 404
- 429
- 500
{- "analysis": {
- "schema": "2",
- "timestamp": "2019-08-24T14:15:22Z",
- "version": "5.0.0.0",
- "duration": "00:07:49.859",
- "status": "DONE",
- "report": {
- "info": {
- "file": {
- "hashes": [
- [
- "md5",
- "ff0fd1e7a5df8a22d0c921ebe7b1b793"
], - [
- "sha1",
- "d63932d669fe6da664b4183d8e1d5a33a9492b9f"
], - [
- "sha256",
- "4430b43199a020b9a1f3bcfa9c55fcc207aea79ec4731def885e89980b8fe880"
]
]
}, - "statistics": {
- "components": 9,
- "extracted": 363,
- "quality": {
- "status": "fail",
- "priority": 0,
- "metrics": {
- "high": 17,
- "medium": 14,
- "low": 0
}
}
}, - "portal": {
- "instance": "playground",
- "reference": "reports/group/57f70f86-71ea-43f8-b443-515d911c8d4a/report/example-project/example-package/v1/?build=version",
}
}, - "metadata": {
- "assessments": {
- "licenses": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail"
}, - "malware": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail"
}, - "hardening": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail"
}, - "secrets": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail"
}, - "tampering": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail"
}, - "vulnerabilities": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail"
}
}
}
}
}
}
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 |
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 |
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 |
Responses
Request samples
- Shell
- Python - Requests
- NodeJS - Request
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
- 200
- 202
- 401
- 403
- 404
- 429
- 500
{- "analysis": {
- "schema": 2,
- "timestamp": "2024-03-25T10:07:27Z",
- "version": "5.0.0.0",
- "duration": "00:07:49.859",
- "report": {
- "info": {
- "summary": {
- "scan_status": "fail",
- "scan_label": "RB:FAIL",
- "reproducible": "repro-check-fail",
- "pass_checks": 2,
- "fail_checks": 2
}, - "properties": [ ]
}, - "scans": {
- "scan-repro": {
- "artifact": {
- "classification": {
- "result": "",
- "status": "Malicious"
}, - "format": "GZIP",
- "hashes": [
- [
- "md5",
- "ff0fd1e7a5df8a22d0c921ebe7b1b793"
], - [
- "sha1",
- "d63932d669fe6da664b4183d8e1d5a33a9492b9f"
], - [
- "sha256",
- "4430b43199a020b9a1f3bcfa9c55fcc207aea79ec4731def885e89980b8fe880"
]
], - "name": "my_file",
- "path": "",
- "size": 210812,
- "subtype": "Archive",
- "type": "Binary",
- "version": "Generic"
}, - "assessments": {
- "licenses": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "malware": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "hardening": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "secrets": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "tampering": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "vulnerabilities": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}
}, - "checks": [
- {
- "final": true,
- "label": "L5:FAIL",
- "reference": "ab0f2461-58a9-49ea-99ee-042487921e43",
- "status": "fail",
- "type": "artifact-check"
}
], - "final": true,
- "inhibitors": {
- "customized": false,
- "exclusions": {
- "SQ31102": 4
}, - "next_level": 5,
- "scan_level": 3
}, - "statistics": {
- "components": 9,
- "extracted": 363,
- "quality": {
- "metrics": {
- "high": 8,
- "low": 0,
- "medium": 3,
- "total": 11,
- "fail": 5,
- "pass": 34,
- "warning": 0
}, - "priority": 0,
- "status": "fail",
- "issues": {
- "fail": 5,
- "high": 8,
- "low": 0,
- "medium": 3,
- "pass": 34,
- "total": 11,
- "warning": 0
}
}, - "vulnerabilities": {
- "critical": 0,
- "high": 4,
- "low": 0,
- "malware": 0,
- "mandate": 0,
- "medium": 0,
- "named": 0,
- "total": 7,
- "triaged": 3,
- "exploit": 6,
- "fixable": 4
}
}
}, - "scan-version": {
- "artifact": {
- "classification": {
- "result": "",
- "status": "Malicious"
}, - "format": "GZIP",
- "hashes": [
- [
- "md5",
- "ff0fd1e7a5df8a22d0c921ebe7b1b793"
], - [
- "sha1",
- "d63932d669fe6da664b4183d8e1d5a33a9492b9f"
], - [
- "sha256",
- "4430b43199a020b9a1f3bcfa9c55fcc207aea79ec4731def885e89980b8fe880"
]
], - "name": "my_file",
- "path": "",
- "size": 210812,
- "subtype": "Archive",
- "type": "Binary",
- "version": "Generic"
}, - "assessments": {
- "licenses": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "malware": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "hardening": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "secrets": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "tampering": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}, - "vulnerabilities": {
- "count": 17,
- "final": true,
- "label": "string",
- "status": "fail",
- "violations": [
- "SQ30107",
- "SQ30108",
- "SQ30110"
]
}
}, - "checks": [
- {
- "final": true,
- "label": "L5:FAIL",
- "reference": "ab0f2461-58a9-49ea-99ee-042487921e43",
- "status": "fail",
- "type": "artifact-check"
}
], - "final": true,
- "inhibitors": {
- "customized": false,
- "exclusions": {
- "SQ31102": 4
}, - "next_level": 5,
- "scan_level": 3
}, - "statistics": {
- "components": 9,
- "extracted": 363,
- "quality": {
- "metrics": {
- "high": 8,
- "low": 0,
- "medium": 3,
- "total": 11,
- "fail": 5,
- "pass": 34,
- "warning": 0
}, - "priority": 0,
- "status": "fail",
- "issues": {
- "fail": 5,
- "high": 8,
- "low": 0,
- "medium": 3,
- "pass": 34,
- "total": 11,
- "warning": 0
}
}, - "vulnerabilities": {
- "critical": 0,
- "high": 4,
- "low": 0,
- "malware": 0,
- "mandate": 0,
- "medium": 0,
- "named": 0,
- "total": 7,
- "triaged": 3,
- "exploit": 6,
- "fixable": 4
}
}
}
}
}
}
}
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 |
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 |
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 |
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 |
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 ( |
Responses
Request samples
- Shell
- Python - Requests
- NodeJS - Request
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
- 200
- 202
- 400
- 401
- 403
- 404
- 429
- 500
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 |
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 |
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 |
Responses
Response samples
- 200
- 401
- 403
- 404
- 429
- 500
{- "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 |
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 |
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 |
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 |
Responses
Request samples
- Payload
- Shell
- Python - Requests
- NodeJS - Request
{- "is_released": true,
- "product": "Example application",
- "publisher": "Example software publisher",
- "category": "Ad",
- "license": "3dfx Glide License",
- "platform": "Browser",
- "release_date": "string"
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
- 500
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 |
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 |
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 |
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 ( |
Responses
Response samples
- 204
- 401
- 403
- 404
- 429
- 500
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 |
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 |
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 |
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
- Payload
{- "reason": "No failing policy checks identified during analysis"
}
Response samples
- 400
- 401
- 403
- 404
- 429
- 500
{- "error": "Only a version with the 'Undetermined' and 'Rejected' approval statuses can be 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 |
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 |
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 |
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
- Payload
{- "reason": "Alternate software selected for approval that poses less security risk"
}
Response samples
- 400
- 401
- 403
- 404
- 429
- 500
{- "error": "Only a version with the 'Undetermined' approval status can be rejected"
}
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 |
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 |
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 |
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
- Payload
{- "reason": "Fixing inadvertent or incorrect approval of software"
}
Response samples
- 400
- 401
- 403
- 404
- 429
- 500
{- "error": "Only a version with the 'Approved' approval status can be revoked"
}
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. Sending a file to reanalysis does not count towards the monthly analysis capacity.
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 |
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 |
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 |
Responses
Response samples
- 401
- 403
- 404
- 429
- 500
{- "error": "Authentication credentials were not provided"
}
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 |
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
- Payload
- Shell
- Python - Requests
- NodeJS - Request
{- "description": "An example project"
}
Response samples
- 201
- 400
- 401
- 403
- 404
- 409
- 429
- 500
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 |
Request Body schema: application/json
name | string Example: "New project name" Name to associate with the project. Project names are case-sensitive. Special characters |
description | string Example: "New short project description" Optional brief description to associate with the project. |
Responses
Request samples
- Payload
{- "name": "New project name",
- "description": "New short project description"
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 500
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 |
Responses
Response samples
- 204
- 401
- 403
- 404
- 429
- 500
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 |
Responses
Response samples
- 200
- 401
- 403
- 404
- 429
- 500
{- "name": "My Project",
- "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
- "description": "This is an example project used for testing purposes",
- "packages": [
- {
- "name": "Demo package",
- "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83"
}
]
}
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 |
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 |
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
- Payload
- Shell
- Python - Requests
- NodeJS - Request
{- "description": "This is my new package"
}
Response samples
- 201
- 400
- 401
- 403
- 404
- 409
- 429
- 500
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 |
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 |
Request Body schema: application/json
name | string Example: "New package name" Name to associate with the package. Package names are case-sensitive. Special characters |
description | string Example: "New short package description" Optional brief description to associate with the package. |
Responses
Request samples
- Payload
{- "name": "New package name",
- "description": "New short package description"
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 500
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 |
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 |
Responses
Response samples
- 204
- 401
- 403
- 404
- 429
- 500
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 |
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 |
Responses
Response samples
- 200
- 401
- 403
- 404
- 429
- 500
{- "name": "ZoomInstaller",
- "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
- "description": "Windows packages for Zoom",
- "versions": [
- {
- "version": "5.12"
}
]
}
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
- 200
- 401
- 403
- 404
- 429
- 500
{- "groups": [
- {
- "name": "My group",
- "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
- "description": "This is an example group used for testing purposes",
- "member_count": 3,
- "is_default": false
}
]
}
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
- 200
- 401
- 403
- 404
- 429
- 500
{- "name": "My group",
- "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83",
- "projects": [
- {
- "name": "My project",
- "name_id": "593ea5fd-a588-4790-bb60-ce5648d19a83"
}
]
}
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 |
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 |
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 |
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
- Payload
{- "reason": "No failing policy checks identified during analysis"
}
Response samples
- 400
- 401
- 403
- 404
- 429
- 500
{- "error": "Only a version with the 'Undetermined' and 'Rejected' approval statuses can be 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 |
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 |
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 |
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
- Payload
{- "reason": "Alternate software selected for approval that poses less security risk"
}
Response samples
- 400
- 401
- 403
- 404
- 429
- 500
{- "error": "Only a version with the 'Undetermined' approval status can be rejected"
}
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 |
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 |
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 |
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
- Payload
{- "reason": "Fixing inadvertent or incorrect approval of software"
}
Response samples
- 400
- 401
- 403
- 404
- 429
- 500
{- "error": "Only a version with the 'Approved' approval status can be revoked"
}