Skip to main content
The SCANOSS v3 API is the public HTTP API behind scanoss-cli. Use it directly when you build your own client, or when you need SCANOSS component data inside another service. If you only need results in a pipeline, scanoss-cli already implements everything on this page. The API Reference group in the sidebar lists every endpoint with its request and response schema.

​
Base URL

All endpoints are under the /v3/ prefix. An on-premise deployment exposes the same paths under its own base URL.

​
Authentication

Send your API key in the x-api-key header on every request:
HTTP header names are not case-sensitive, so X-Api-Key works too. The API rejects a missing or invalid key with HTTP 401. To get a key, see API keys and authentication.

​
What the API covers

​
Identify components by PURL

Component data is keyed by Package URL (PURL), for example pkg:github/scanoss/engine or pkg:npm/lodash. An optional requirement narrows the request to a version or, on range endpoints, a version range: Most lookup endpoints accept both forms:
  • GET for one component. Pass purl and requirement as query parameters.
  • POST for many components. Send a JSON body with a components array. This is the batch form.
A batch request must contain at least one component. To send a list larger than you want in one request, split it into chunks and send the chunks in parallel. scanoss-cli does this with a default chunk size of 10 PURLs.

​
Search options

A batch body can also carry a search object, and the same options are available as query parameters on GET requests: Endpoints that support these options say so in the API Reference. Today, /v3/license/evidence is the main endpoint that uses them.

​
Response conventions

​
Batch status and per-item info codes

A batch request returns HTTP 200 even when some components could not be resolved. Each response has two levels of outcome:
  • status.status for the request as a whole: SUCCESS, PARTIAL_SUCCESS, or ERROR, with a human-readable status.message.
  • info_code and info_message on each item in components, when that item did not resolve cleanly.
This is an illustrative response for the request above, where the second PURL is not known:
A single-component GET reports the same status.status, derived from that one item’s info_code.
In a client, treat SUCCESS and PARTIAL_SUCCESS as usable responses, and read info_code on each item to decide what to retry or report. Do not retry a whole batch because one item returned COMPONENT_NOT_FOUND.

​
Errors

Requests that fail as a whole, such as a malformed body or a server error, return an HTTP error status with this body:
error.code is a stable identifier, so parse it instead of message. Common codes include INVALID_BODY, INVALID_QUERY, EMPTY_BATCH, INVALID_PURL, COMPONENT_NOT_FOUND, VERSION_NOT_FOUND, TIMEOUT, and INTERNAL_ERROR.

​
Scanning source code: the fingerprint flow

The API never receives your source code. You send WFP fingerprints, which are compact hashes of each file and of its snippets. Generate them with scanoss-cli wfp, the Go SDK, or another SCANOSS client, rather than writing your own fingerprinter:
POST /v3/wfp/scan accepts a WFP in one of two modes. The X-Scan-Id request header selects the mode. Both return the same ScanEnvelope, and the final result is identical in both.

​
Small inputs: one synchronous request

Without an X-Scan-Id header, send the whole WFP as the body. The request blocks until the scan finishes and returns 200 with status: completed and the result:
The request timeout and the maximum upload size limit this mode. Use it only for small inputs.

​
Large inputs: upload in blocks, then poll

For anything larger, upload the WFP in blocks and poll for the result. This is what scanoss-cli scan does.
1

Create a scan ID

Generate a new UUID version 7 in canonical lowercase form, for example 018f7b2c-9a3e-7d41-8b6a-2c1d4e5f6a7b. Your client creates this ID, not the server. The server rejects any other ID format with 400 INVALID_SCAN_ID.
2

Upload each block

Split the WFP into byte ranges (scanoss-cli uses 1 MiB blocks by default). Send each one as POST /v3/wfp/scan with:
  • X-Scan-Id: the same scan ID on every block
  • Content-Range: bytes <start>-<end>/<total>: the block’s position, zero-based, end inclusive
  • Content-Type: application/octet-stream
Each accepted block returns 202 with status: uploading and received_bytes. Blocks can arrive in any order and in parallel. If you resend a block the server already has, with the same bytes, it returns 202 again, so you can retry a block safely. When the blocks cover the whole range with no gaps, the server starts the scan.
3

Poll for the result

status moves through uploading, queued, scanning, and finally completed, failed, or expired. While scanning, phase, phase_done, and phase_total report progress. Once completed, the envelope carries result. The API reports a failed scan in the body with an error string, not as an HTTP error. scanoss-cli polls every 2 seconds by default.
A block upload can return these errors: The server keeps a scan session for a limited time. Polling an unknown ID returns 404 SCAN_NOT_FOUND, and polling an expired one returns 410 SCAN_EXPIRED.

​
The scan result

result contains:
  • files: one entry per scanned file, with its path, its match_type (file, snippet, or none), and a matches list. Each match names a component release by url_hash and carries a confidence grade (LOW, MEDIUM, or HIGH). Snippet matches also carry match_percentage and the matched line ranges in your file and in the open source file.
  • components: the matched component releases, keyed by url_hash, with component, vendor, version, url, release_date, and purls.
scanoss-cli turns this result into its raw inventory, SPDX, or CycloneDX output and can add licence, vulnerability, cryptography, and geoprovenance data with --include. If you call the API yourself, you add that data by sending the matched PURLs to the lookup endpoints above.