Managing issues

Overview

The FOSSA Issues API (v2) lets you query, filter, and act on issues across your organization or a single project. This page covers the core concepts, key endpoints, and practical recipes for common issue management tasks.

Core concepts

Scope

The scope determines which issues are returned:

• Global: issues across all projects in your organization. Set scope[type]=global.
• Project: issues for a single project. Set scope[type]=project, scope[id]=<project-locator>, and scope[revision]=<revision>.

Category

Issues fall into three categories, passed as the category query parameter:

Status

Ticket status

Filter by ticket status using the bracketed array parameter filter[ticketed][]. Pass one or more of the following values (URL-encode the brackets when your HTTP client doesn't do it automatically):

Depth

Severity (vulnerability only)

Filter by severity: critical, high, medium, low, or unknown.

Issue types

Pass one or more values to types to narrow by issue type:

Sort

Issues are sorted by created_at descending by default. Control this with the sort parameter.

Listing issues

# All active licensing issues globallycurl -G 'https://app.fossa.com/api/v2/issues' \  -d 'category=licensing' \  -d 'scope[type]=global' \  -d 'status=active' \  -H 'Authorization: Bearer YOUR_API_KEY' # Active security issues for a specific projectcurl -G 'https://app.fossa.com/api/v2/issues' \  -d 'category=vulnerability' \  -d 'scope[type]=project' \  -d 'scope[id]=git%2Bgithub.com%2Fyour-org%2Fyour-repo' \  -d 'scope[revision]=abc123' \  -d 'status=active' \  -H 'Authorization: Bearer YOUR_API_KEY'

The response includes an issues array and pagination metadata. Use page and count to paginate. Each issue has an id used in follow-up requests.

Getting issue counts

GET /api/v2/issues/categories returns counts grouped by category, useful for dashboards or alerting:

curl -G 'https://app.fossa.com/api/v2/issues/categories' \  -d 'scope[type]=global' \  -H 'Authorization: Bearer YOUR_API_KEY'

GET /api/v2/issues/statuses returns counts grouped by status:

curl -G 'https://app.fossa.com/api/v2/issues/statuses' \  -d 'category=vulnerability' \  -d 'scope[type]=global' \  -H 'Authorization: Bearer YOUR_API_KEY'

Getting a single issue

curl -G 'https://app.fossa.com/api/v2/issues/12345' \  -d 'category=vulnerability' \  -d 'scope[type]=global' \  -H 'Authorization: Bearer YOUR_API_KEY'

Bulk-ignoring issues

Use PUT /api/v2/issues to ignore multiple issues at once. Pass issue IDs as query parameters and the action in the request body.

1. 1

   Fetch the issue IDs you want to ignore

   ShellCopy

   curl -G 'https://app.fossa.com/api/v2/issues' \  -d 'category=licensing' \  -d 'scope[type]=global' \  -d 'status=active' \  -H 'Authorization: Bearer YOUR_API_KEY' | jq '[.issues[].id]'

2. 2

   Submit the ignore action

   ShellCopy

   curl --request PUT \  --url 'https://app.fossa.com/api/v2/issues?category=licensing&scope[type]=global&ids[0]=12345&ids[1]=67890' \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --data '{    "type": "ignore",    "reason": "other",    "notes": "Test-only dependency, not shipped to production"  }'

   Valid reason values: Fixed, Under_investigation, incorrect_data_found, Component_not_present, Inline_mitigations_already_exist, Vulnerable_code_cannot_be_controlled_by_adversary, Vulnerable_code_not_in_execute_path, Vulnerable_code_not_present, other. Use the notes field (not comment) for free-text justification.

Bulk-unignoring issues

curl --request PUT \  --url 'https://app.fossa.com/api/v2/issues?category=licensing&scope[type]=global&ids[0]=12345' \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --data '{ "type": "unignore" }'

Working with auto-ignore rules

Auto-ignore rules persist ignore decisions across versions or projects. Manage them via the exceptions API.

List auto-ignore rules for a project

curl -G 'https://app.fossa.com/api/v2/issues/exceptions' \  -d 'scope[type]=project' \  -d 'scope[id]=git%2Bgithub.com%2Fyour-org%2Fyour-repo' \  -H 'Authorization: Bearer YOUR_API_KEY'

Get a single auto-ignore rule

curl 'https://app.fossa.com/api/v2/issues/exceptions/456' \  -H 'Authorization: Bearer YOUR_API_KEY'

Delete an auto-ignore rule

curl --request DELETE \  'https://app.fossa.com/api/v2/issues/exceptions/456' \  -H 'Authorization: Bearer YOUR_API_KEY'

Bulk-delete auto-ignore rules

curl --request DELETE \  --url 'https://app.fossa.com/api/v2/issues/exceptions' \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --data '{ "kind": "idList", "value": [456, 789] }'

The request body is a discriminated union on kind. Use { "kind": "idList", "value": [456, 789] } to delete specific rules by ID, or { "kind": "all", "filters": { ... } } to delete every rule matching a filter.

Exporting issues as CSV

# Download immediatelycurl -G 'https://app.fossa.com/api/v2/issues/csv/global' \  -H 'Authorization: Bearer YOUR_API_KEY' \  --output issues.zip # Email insteadcurl -G 'https://app.fossa.com/api/v2/issues/csv/global' \  -d 'email=true' \  -H 'Authorization: Bearer YOUR_API_KEY'

The download contains separate CSV files for licensing, security, and quality issues. See Generating reports for more on org-wide report options.