Initiating a binary scan

Upload a binary or archive and start a decomposition scan through the FOSSA API, then poll for completion.

5 min readUpdated Jul 17, 2026

Enterprise feature

Available on: Business, Enterprise.

Overview

Binary scanning (binary decomposition) uploads a compiled binary or archive to FOSSA and breaks it down into the open source components it was built from. This recipe walks through the full API flow: request an upload URL, push the file, trigger the scan, and poll until it finishes. It is the same flow the FOSSA CLI uses under the hood, exposed here so you can drive it from CI or custom tooling without the CLI.

Note

Prerequisites:

A FOSSA API token. A Push-Only token is sufficient to upload and trigger a scan; retrieving component results (below) needs a Full token. See Authentication.
Project create permission in your organization.
Binary scanning enabled for your organization. It requires a Business or Enterprise plan and is metered by a binary decomposition quota. If the quota is exhausted, the upload URL request returns 403. Contact your FOSSA account team to enable it or raise the limit.

How the flow works

A binary scan is three API calls plus one direct upload to storage. You never send the file bytes to the FOSSA API itself.

Ask FOSSA for a short-lived, signed upload URL for your binary.
PUT the raw file to that URL (it points at FOSSA's object storage, not the API).
Tell FOSSA to build (scan) the uploaded file.
Poll the build status until it reports finished.

FOSSA identifies the upload by a locator built from the values you supply: binary+<orgId>/<packageSpec>$<revision>. You provide packageSpec and revision on each call; the poll step (step 4) uses the full locator.

Running a binary scan

1
Request a signed upload URL
Call GET /api/components/signed_url with fileType=binary. packageSpec is the name to give the binary project and revision is its version.
Shell
curl -G 'https://app.fossa.com/api/components/signed_url' \ -H 'Authorization: Bearer YOUR_API_KEY' \ --data-urlencode 'packageSpec=my-binary' \ --data-urlencode 'revision=1.0.0' \ --data-urlencode 'fileType=binary'
The response contains the upload URL:
JSON
{ "signedUrl": "https://blob.fossa.io/binary_components/...&X-Amz-Signature=..." }
Copy the signedUrl value for the next step. The signed URL is write-only and expires one hour after it is issued.
2
Upload the binary
PUT the raw file to the signed URL, pasted inside single quotes. This request goes to object storage, so it does not take a FOSSA Authorization header.
Shell
curl -X PUT \ -H 'Content-Type: binary/octet-stream' \ --upload-file ./my-binary.bin \ 'PASTE_SIGNED_URL'
A successful upload prints no response body. If it fails, the response shows the error (for example an AccessDenied block).
Warning
Paste the URL exactly as returned, with no added backslashes or line breaks. Keeping it inside single quotes stops your shell from altering the ?, &, and = characters. An altered URL returns AccessDenied.
Warning
Do not trigger the scan until the upload succeeds.
3
Trigger the scan
Call POST /api/components/build?fileType=binary. The JSON body must reference the same packageSpec and revision you uploaded under in step 1. The endpoint queues the scan and returns immediately.
Shell
curl -X POST 'https://app.fossa.com/api/components/build?fileType=binary' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "archives": [ { "packageSpec": "my-binary", "revision": "1.0.0" } ] }'
A 201 Created (empty body) confirms the scan is queued.
4
Poll for completion
Poll GET /api/cli/<locator>/latest_build, where <locator> is binary+<orgId>/<packageSpec>$<revision>, URL-encoded, using the same packageSpec and revision as the upload.
Shell
curl -G 'https://app.fossa.com/api/cli/binary%2B<orgId>%2Fmy-binary%241.0.0/latest_build' \ -H 'Authorization: Bearer YOUR_API_KEY'
JSON
{ "id": 12345, "task": { "status": "RUNNING" } }
Poll until task.status is SUCCEEDED. A FAILED status is surfaced only after retries are exhausted; on failure, check error in the response.

Warning

Use the same packageSpec and revision across all three calls. To scan a new version of the same binary, keep packageSpec and change revision.

Note

Locators contain characters that must be URL-encoded in a path: + becomes %2B, / becomes %2F, and $ becomes %24. Your orgId is your organization's numeric ID, which you can get from GET /api/organizations. For packageSpec=my-binary and revision=1.0.0 in org 123, the locator binary+123/my-binary$1.0.0 encodes to binary%2B123%2Fmy-binary%241.0.0.

Optional build parameters

Pass these as query parameters on the POST /api/components/build call to control how the resulting project is set up. The exception is forceRebuild, which is a boolean field in the JSON body.

Parameter	Description
`title`	Display title for the project (defaults to `packageSpec`).
`branch`	Branch to record the revision under (defaults to `master`).
`team`	Name of a team to assign the project to.
`description`	Project description.
`projectURL`	External URL to attach to the project.
`policyId`	ID of a policy to apply to the project.
`releaseGroup` / `releaseGroupRelease`	Title of a release group and release to add the project to.
`forceRebuild`	Body field (boolean). Re-scan a locator that was already built.

Note

If your organization requires a team on every upload, include team (or a selectedTeams array in the body). Without it the build call returns an error naming the missing team requirement.

Retrieving results

When the build succeeds, the binary appears as a project in the FOSSA dashboard with its decomposed components and any license or vulnerability issues. To read the components programmatically, use the /api/binary/... endpoints with a Full token, for example:

Shell

curl -G 'https://app.fossa.com/api/binary/revision/<encoded-locator>/components/count' \  -H 'Authorization: Bearer YOUR_API_KEY'

For querying the resulting issues, see Managing issues.

Next steps

Authentication: token types and security best practices.
Retrieving the latest revision: find the newest revision of a project.
Endpoint Reference: every endpoint, parameter, and response.