Issues API
Definitions
What follows are definitions of the types used across the Issues API.
Note while request parameter shapes are shown in JSON for readability, they are actually issued as URL query parameters. See Request Parameter Encoding for more information.
Scope
The scope determines whether to query for issues across the entire organization (Global), for a specific Project, or for a specific Revision of a Project.
When omitted, the scope defaults to Global Scope.
Global Scope (Default)
{
type: 'global'
}
Project Scope
If revision
is omitted, the latest revision is used.
{
type: 'project',
id: string (this will be a project locator),
revision: string (optional) (this will be the revision id)
}
Category
The Issue category being queried. These are directly translatable to the issue pages on the FOSSA UI.
licensing
quality
vulnerability
Status
The status of an individual issue on a project. When omitted, the status defaults to 'active'
.
active
defaultignored
Ticketed
Whether the issue has an associated Jira ticket.
has_ticket | This issue has an associated ticket. |
no_ticket | This issue does not have an associated ticket. |
Depth
The depth of the dependency with the issue.
direct | This is a direct dependency. |
deep | This is a transitive dependency. |
Severity (Vulnerability Issues Only)
Severity of a vulnerability issue.
critical
high
medium
low
unknown
Issue Types
These are issue types used in the type
query parameter in many Issues queries.
Vulnerability issues have only a single type, queries for Vulnerability issues don't have a
type
query parameter.
Licensing
policy_conflict
policy_flag
unlicensed_dependency
Quality
outdated_dependency
blacklisted_dependency
risk_abandonware
risk_empty-package
risk_native-code
Sort
Sorting options for the returned list of issues. When omitted, the sort defaults to created_at_desc
for licensing, quality, and risk, and to severity_desc
for vulnerability.
package_asc | Sort by dependency name (A to Z). |
package_desc | Sort by dependency name (Z to A). |
created_at_asc | Sort by when the issue was last found (Oldest to newest) Default for licensing, quality, and risk |
created_at_desc | Sort by when the issue was last found (Newest to oldest) |
severity_asc (vulnerability only) | Sort by severity (Lowest to highest) |
severity_desc (vulnerability only) | Sort by severity (Highest to lowest) Default for vulnerability |
Issue Filter
Because each issue category has different metadata associated with it, the filters that can be applied to issues, differ across categories. When querying for issues, by default, all issues are returned. The fields of filter types are therefore all optional.
For all issue categories, the
search
field applies to the problematic dependency's name. For Vulnerability issues, thesearch
field also applies to the CVE of the vulnerability.
When querying for issues of a specific category, endpoints that accept a filter
query parameter expect one of the following appropriate shapes:
Licensing
{
search?: string,
type?: LicensingIssueType[],
depths?: Depth[],
ticketed?: Ticketed[],
}
Quality
{
search?: string,
type?: QualityIssueType[],
depths?: Depth[],
ticketed?: Ticketed[],
}
Vulnerability
{
search?: string,
depths?: Depth[],
ticketed?: Ticketed[],
severity?: Severity[],
}
Endpoints
Request Parameter Encoding
Request parameter shapes are shown in JSON for readability, they are actually used as URL query parameters.
For example, a possible request to GET /api/v2/issues/categories
could have the parameters
{
scope: { type: 'project', id: 'git+github.com/some/project', revision: 'v1.2.3' }
}
This would be encoded to the following request, using curl
:
curl -G /api/v2/issues/categories \
-d 'scope[type]=project'
-d 'scope[id]=git%2Bgithub.com%2Fsome%2Fproject'
-d 'scope[revision]=v1.2.3'
Note that while the keys (eg.
scope[id]
) don't have to be URL encoded, the values (eg.git+github.com/some/project
) must be URL encoded.
GET /api/v2/issues/categories
Returns the number of active issue counts for a Scope, grouped by issue Category.
Request Parameters
{
scope?: Scope
}
Response
{
licensing: number,
quality: number,
vulnerability: number,
}
GET /api/v2/issues/statuses
Returns issue counts for a Scope, Category and Issue Filter, grouped by issue Status.
Request Parameters
{
category: Category,
scope?: Scope,
filter?: IssueFilter,
}
Response
{
active: number,
ignored: number,
}
GET /api/v2/issues
Returns the list of issues for given Scope, Category, and Issue Filter. Additionally, this endpoint is paginated, and sorting options can be applied.
Request Parameters
{
category: Category,
scope?: Scope,
filter?: IssueFilter,
sort?: Sort,
page?: number,
count?: number,
}
Response
{
issues: Issue[],
}
Examples
Here are some example Issues API requests using curl
.
Note that these make use of the
-G
flag, which forces all data specified with-d
to be encoded into the URL as part of a GET request. See Request Parameter Encoding for more information.
Listing All Direct Licensing Issues Globally
curl -G https://app.fossa.com/api/v2/issues \
-d 'category=licensing' \
-d 'filter[depths][0]=direct' \
-H 'Authorization: Bearer <FOSSA API Token>'
Listing Critical and High Vulnerability Issues For A Project
curl -G https://app.fossa.com/api/v2/issues \
-d 'category=vulnerability' \
-d 'scope[type]=project' \
-d 'scope[id]=git%2Bgithub.com%2Fsome%2Fproject' \
-d 'scope[revision]=v1.2.3' \
-d 'filter[severity][0]=critical' \
-d 'filter[severity][1]=high' \
-H 'Authorization: Bearer <FOSSA API Token>'
Listing Log4j Vulnerability Issues Globally
curl -G https://app.fossa.com/api/v2/issues \
-d 'category=vulnerability' \
-d 'filter[search]=log4j' \
-H 'Authorization: Bearer <FOSSA API Token>'
How do I download CSV of all active licensing issues?
curl -G https://app.fossa.com/api/v2/issues \
-d 'category=licensing' \
-d 'csv=true' \
-H 'Authorization: Bearer <FOSSA API Token>'
How do I download CSV of all ignored licensing issues?
curl -G https://app.fossa.com/api/v2/issues \
-d 'category=licensing' \
-d 'csv=true' \
-d 'status=ignored' \
-H 'Authorization: Bearer <FOSSA API Token>'
How do I download CSV of all active vulnerability issues?
curl -G https://app.fossa.com/api/v2/issues \
-d 'category=vulnerability' \
-d 'csv=true' \
-H 'Authorization: Bearer <FOSSA API Token>'
Updated 3 months ago