Initiating a binary scan — FOSSA Docs Docs Search docs... ⌘K Docs API CLI Glossary Launch App User Guides Product Guides Get Started Project Setup Release Groups Issues Licenses Vulnerabilities Quality SBOM Policies Reports FOSSA CLI API Reference Introduction to the FOSSA API Authentication Errors Webhook Notifications CPE Lookup API Usage examples Managing issues Managing users and teams Initiating a binary scan Generating reports Creating Jira tickets Downloading attribution reports Modifying release groups Retrieving the latest revision Rotating access tokens Endpoint Reference Integrations fossabot Organization Management On-Premises Deployment Help & Support Legal Get Support fossa.com On this page * Overview * How the flow works * Running a binary scan * Optional build parameters * Retrieving results * Next steps On this page Docs API Reference Usage examples Initiating a binary scan Initiating a binary scan Upload a binary or archive and start a decomposition scan through the FOSSA API, then poll for completion. 5 min read Updated Aug 26, 2026 Copy link 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 Copy 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 Copy { "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 Copy 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 Copy 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 Copy 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 Copy { "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 Copy 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. Previous Generating reports Next Managing issues © 2026 FOSSA, Inc. [email protected]