Definitions

What follows are definitions of the types used across the Issues v2 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 default
• ignored

Ticketed

Whether the issue has an associated Jira ticket.

Depth

The depth of the dependency with the issue.

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 v2 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.

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, the search 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 v2 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>'