SCA (Projects & Releases) API
  • 16 Dec 2022
  • 12 Minutes to read
  • Dark
    Light
  • PDF

SCA (Projects & Releases) API

  • Dark
    Light
  • PDF

The SCA Repository API has Endpoints to query, create, and update projects, releases, and related components on a ProGet instance.

Security & API Keys

To specify an API Key, use the request header (X-ApiKey), querystring (key), or api:«api-key» as the username. See API Key Usage to learn more.

Access Type Requirements
System API Keys Manage Projects & Releases and/or Upload SBOM documents
Feed API Keys not usable
Personal API Key associated user must have one of:
Projects_View
Projects_ResolveIssue
Projects_UploadSbom
Projects_Manage
No API Key anonymous or authenticated user must have at one of the above permissions

Endpoint Specifications

List Projects Endpoint

The List Project Endpoint returns a JSON array of all projects.

List Projects Response

Response Details
200 (Success) body will contain an array of ProjectInfo Objects
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Get Project Endpoint

The Get Project Endpoint returns a JSON object describing a project.

Get Project Response

Response Details
200 (Success) body will contain a ProjectInfo Object
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
404 (Project Not Found) indicates that the specified project does not exist
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Create/Update Project Endpoint

The Create/Update Project Endpoint can create a new project or update properties on an existing project.

Create/Update Project Request

Create/Update Project Response

Response Details
200 (Success) body will contain a ProjectInfo Object
400 (Invalid Input) indicates invalid or missing properties on the ProjectInfo Object; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

List Releases Endpoint

The List Releases Endpoint returns a JSON array of all releases in a project.

List Releases Response

Response Details
200 (Success) body will contain an array of ReleaseInfo Objects
400 (Invalid Input) indicates invalid or missing properties
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Get Release Endpoint

The Get Release Endpoint returns a JSON object describing a release.

  • Request Type: GET
  • Request URL: /api/sca/releases?name=«projectName»&version=«versionNumber»
  • Note that:

Get Release Response

Response Details
200 (Success) body will contain a ReleaseInfo Object
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
404 (Project or Release Not Found) indicates that the specified project or relase does not exist
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Create/Update Release Endpoint

The Create/Update Release Endpoint can create a new release or update properties on an existing release.

Create/Update Release Request

Create/Update Release Response

Response Details
200 (Success) body will contain a ReleaseInfo Object
400 (Invalid Input) indicates invalid or missing properties on the ReleaseInfo Object; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

List Issues Endpoint

The List Issues Endpoint returns a JSON array of all issues in a project release.

  • Request Type: GET
  • Request URL: /api/sca/issues?project=«projectName»&version=«releaseVersion»
  • Note that:

List Issues Response

Response Details
200 (Success) body will contain an array of IssueInfo Objects
400 (Invalid Input) indicates invalid or missing properties
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Resolve Issue Endpoint

The Resolve Issue Endpoint sets the status of an Issue to Resolved.

Resolve Issue Request

  • Request Type: POST
  • Request URL: /api/sca/issues?project=«projectName»&version=«releaseVersion»&resolve=true
  • Note that:

Resolve Issue Response

Response Details
200 (Success) indicates issue was resolved
400 (Invalid Input) indicates invalid or missing arguments; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Delete Issue Endpoint

The Delete Issue Endpoint deletes an Issue.

Delete Issue Request

  • Request Type: DELETE
  • Request URL: /api/sca/issues?project=«projectName»&version=«releaseVersion»&number=«issueNumber»
  • Note that:

Delete Issue Response

Response Details
200 (Success) indicates issue was deleted
400 (Invalid Input) indicates invalid or missing arguments; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

List Comments Endpoint

The List Comments Endpoint returns a JSON array of all comments in a project release.

  • Request Type: GET
  • Request URL: /api/sca/comments?project=«projectName»&version=«releaseVersion»
  • Note that:

List Comments Response

Response Details
200 (Success) body will contain an array of CommentInfo Objects
400 (Invalid Input) indicates invalid or missing properties
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Create/Update Comment Endpoint

The Create/Update Comment Endpoint creates or updates properties on a comment.

Create/Update Comment Request

Create/Update Comment Response

Response Details
200 (Success) body will contain a CommentInfo Object
400 (Invalid Input) indicates invalid or missing properties on the CommentInfo Object; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Delete Comment Endpoint

The Delete Comment Endpoint deletes an Issue.

Delete Comment Request

  • Request Type: DELETE
  • Request URL: /api/sca/comments?project=«projectName»&version=«releaseVersion»&number=«commentNumber»
  • Note that:

Delete Comment Response

Response Details
200 (Success) indicates comment was deleted
400 (Invalid Input) indicates invalid or missing arguments; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Import SBOM Endpoint

The Import SBOM Endpoint can be used to import an existing SBOM document into ProGet and create corresponding project and release information from it.

Import SBOM Request

  • Request Type: POST
  • Request URL: /api/sca/import
  • Content-Type: text/xml or application/json
  • Request Body: SBOM Document in either XML or JSON format depending on the value of the Content-Type header
  • Note that:

Import SBOM Response

Response Details
200 (Success) import was successful
400 (Invalid Input) indicates the submitted SBOM document was not valid
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Export SBOM Endpoint

The Export SBOM Endpoint can be used to generate an SBOM from project and release information in ProGet.

Export SBOM Request

  • Request Type: GET
  • Request URL: /api/sca/export?project=«projectName»&version=«versionNumber»&format=«xml/json»
  • Note that:

Export SBOM Response

Response Details
200 (Success) body will contain the exported SBOM document in the specified format
404 (Project or Release Not Found) indicates that the specified project or release was not found
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Analyze Release Endpoint

Introduced in v2022.10, this input will run an analysis of a single release, similar to clicking the "analyze" button in the user interface, on the release overview page.

Analyze Release Request

  • Request Type: POST
  • Request URL: /api/sca/analyze-release?project=«projectName»&version=«releaseVersion»
  • Note that:

Analyze Release Response

Response Details
200 (Success) analysis was successful
400 (Invalid Input) indicates invalid or missing arguments; the body will provide some details as text
403 (Unauthorized API Key) indicates a missing, unknown, or unathorized API Key; the body will be empty
500 (Server Error) indicates an unexpected error; the body will contain the messsage and stack trace, and this will also be logged

Data Specifications

ProjectInfo Properties

ProjectInfo is a set of key/value pairs that correspond to the fields on a Project. It's used as both input and output data for various endpoints:

  • Output: Create, Update, and List endpoints return ProjectInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives ProjectInfo as a JSON-formatted object; a missing property indicates that the value should not be updated

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Property Format Notes
id int Internal ID of project
name string Must be unique across the system
description string? Markdown-based description of project, shown UI
type string? SBOM Metadata field
url string? SBOM Metadata field

ReleaseInfo Properties

ReleaseInfo is a set of key/value pairs that correspond to the fields on a Release. It's used as both input and output data for various endpoints:

  • Output: Create, Update, and List endpoints return ReleaseInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives ReleaseInfo as a JSON-formatted object; a missing property indicates that the value should not be updated

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Property Format Notes
project string The name of the project
version string The release version number
active bool Indicates whether release is active/inactive
url string? SBOM Metadata field
comments CommentInfo[]? An array of CommentInfo objects
viewReleaseUrl string? Introduced in v2022.10; an absolute URL for the release overview page
viewIssuesUrl string? Introduced in v2022.10; an absolute URL for the release issues page
packages PackageInfo[]? Introduced in v2022.16; An array of PackageInfo objects

IssueInfo Properties

IssueInfo is a set of key/value pairs that correspond to the fields on an Issue. It's used as both input and output data for various endpoints:

  • Output: Create, Update, and List endpoints return IssueInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives IssueInfo as a JSON-formatted object; a missing property indicates that the value should not be updated

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Property Format Notes
project string The name of the project
version string The release version number
number number The issue number
created string The date the issue was created
type string The issue type (V=VulnerablePackage, M=MissingPackage, O=OutdatedPackage, L=LicenseViolation)
purl string The package URL of the package associated with the issue
vulnerability string? The ID of the related vulnerability if type is V

CommentInfo Properties

CommentInfo is a set of key/value pairs that correspond to the fields on a Comment. It's used as both input and output data for various endpoints:

  • Output: Create, Update, and List endpoints return CommentInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives CommentInfo as a JSON-formatted object; only the comment field will be updated

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Property Format Notes
number number The comment number
by string The name of the user that created the comment
date string The date the comment was created
comment string The comment text

PackageInfo Properties

PackageInfo is a set of key/value pairs that correspond to the fields on a Package. It's used as a parameter on a ReleaseInfo object.

Property Format Notes
purl string A package url of the package
vulnerabilities VulnerabilityInfo[]? An array of VulnerabilityInfo objects

VulnerabilityInfo Properties

VulnerabilityInfo is a set of key/value pairs that correspond to the fields on a Vulnerability. It's used as a parameter on a PackageInfo object.

Property Format Notes
id string The ID of the vulnerability
title string The title of the vulnerability
description string The description of the vulnerability
score number? The CSSV score, if one is set on the vulnerability
assessment string? The asessment type, if set

Usage Examples

Import SBOM

curl --header "X-ApiKey: <key>" --header "Content-Type: application/json" --request POST --upload-file bom.json http://proget/api/sca/import

Download SBOM

curl --header "X-ApiKey: <key>" "http://proget/api/sca/export?project=juice-shop&version=11.1.2&format=xml"

Mark a Release as Inactive

curl --header "X-ApiKey: <key>" --header "Content-Type: application/json" --request POST --data "{ \"project\": \"juice-shop\", \"version\": \"10.0.0\", \"active\": false }" http://proget/api/sca/releases

Resolve an Issue

curl --header "X-ApiKey: <key>" --request POST --data ""  "http://proget/api/sca/issues?project=juice-shop&version=11.1.2&number=1000&resolve"

Add a Comment to a Release

curl --header "X-ApiKey: <key>" --header "Content-Type: application/json" --request POST --data "{ \"project\": \"juice-shop\", \"version\": \"11.1.2\", \"comment\": \"I am a new comment.\" }" http://proget/api/sca/comments

Get Issues for a Release

curl --header "X-ApiKey: <key>" "http://proget/api/sca/issues?project=juice-shop&version=11.1.2"

Was this article helpful?