> ## Documentation Index > Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt > Use this file to discover all available pages before exploring further. # Scan a WFP — synchronous single-shot, or one block of a chunked async upload > Dual-mode upload, selected by the presence of the `X-Scan-Id` request header. Both modes return the same `ScanEnvelope` envelope, and the `result` payload is byte-identical to the polled async result (both run the same batchScanner pipeline → same `Report`). **Mode B — synchronous single-shot (no `X-Scan-Id`).** The request body is one complete WFP (`application/octet-stream`, capped at `scan.max_upload_size`), scanned inline. Responds `200` with a `ScanEnvelope` already at `status: completed`, carrying `result`, `files_total` and a fresh `scan_id` (for traceability only — no session is created, nothing to poll). `Content-Range` is ignored. An empty/whitespace body → `400 INVALID_BODY`. The request blocks for the whole scan, so this mode is bounded by the request timeout and intended for small inputs. **Mode A — chunked async (`X-Scan-Id` present).** One block of a multi-block upload too large for a single request. The client generates the session id — a **canonical lowercase UUIDv7** — and sends it on **every** block (it is what a load balancer hashes on to keep all blocks on one instance). `Content-Range: bytes -/` is **required**. Blocks are reassembled by their declared byte offset, so they **may be uploaded in any order or concurrently**; the first received block need not start at offset 0. Each block responds `202` with a `ScanEnvelope` (`status: uploading`). When the received ranges fully cover `[0, total)` with no gaps, the upload is sealed and the batchScanner pipeline is queued (its stages call the scan API over HTTP); poll `GET /v3/wfp/scan/{id}` for progress/result. `received_bytes` reports the total distinct bytes covered so far. Re-POSTing an already-received range with identical bytes is an idempotent `202` no-op. Mode A errors: a non-canonical / non-UUIDv7 id → `400 INVALID_SCAN_ID`; missing `Content-Range` → `400 MISSING_RANGE`; malformed `Content-Range` (or a body length that disagrees with the range) → `400 INVALID_RANGE`; an overlapping block carrying **conflicting** bytes, or reuse of a sealed id → `409 RANGE_CONFLICT` (note: out-of-order arrival alone is **not** a conflict); a block or declared total over the configured limits → `413 PAYLOAD_TOO_LARGE`. ## OpenAPI ````yaml /api-reference/developer-tools/v3-openapi.yaml post /v3/wfp/scan openapi: 3.0.3 info: title: SCANOSS Services API version: 0.28.1 description: | Consolidated HTTP API for the SCANOSS knowledge base. Exposes the following domains under a single `/v3/*` prefix: * **licenses** — attribution files + per-file license evidence * **copyright** — copyright evidence + holders (stubbed pending data) * **components** — free-form search, versions and lifecycle status * **crypto** — algorithms, hints and version ranges per purl, plus ruleset tarball downloads * **crypto reachability** — stitched cryptographic findings, call chains, entry points, supporting and forward calls per component or frozen dependency tree * **dependencies** — declared dependencies (with composite-license resolution) and bounded transitive walks * **geo** — contributor declared/curated locations and timezone-based origin distribution * **vulnerabilities** (path `/vuln/*`) — CVE detection by merging the local NVD KB with osv.dev, enriched with EPSS * **scan** — direct SCANOSS engine scans (WFP upload, MD5 / urlhash / snippet lookups) * **contents** — raw notice / source-code content from the mz store Every batch endpoint encodes per-item failures as `info_code` / `info_message` so the call as a whole returns 200 with a `status.status` ∈ {SUCCESS, PARTIAL_SUCCESS, ERROR}. Single-purl GETs derive the same status from the item's `info_code`. servers: - url: https://api.scanoss.com description: Production security: [] tags: - name: licenses description: License attribution files and per-file license evidence - name: copyright description: Copyright evidence and holders (stubbed pending KB data) - name: components description: Component search, versions and lifecycle status - name: cryptography description: Cryptographic algorithms, hints, version ranges and ruleset downloads - name: cryptography-reachability description: > Crypto reachability over mining results: stitched findings, call chains, crypto entry points, supporting calls and bounded forward calls, for one component (with its mined dependency closure) or a caller-supplied frozen dependency tree. Registered only when reachability_db.dsn is configured. - name: dependencies description: Declared dependencies (per component) and transitive walks - name: geoprovenance description: Contributor locations (declared + curated) and origin distribution - name: vulnerabilities description: CVE detection (local KB + OSV) and CPE lookup - name: scan description: > Direct SCANOSS engine scans (passthrough), plus MD5 / urlhash / snippet lookups, and the dual-mode batch endpoint (synchronous single-shot WFP and chunked-async upload over the batchScanner pipeline). Registered only when scan.engine_path is configured. - name: contents description: Raw notice / source-code content from the mz store paths: /v3/wfp/scan: post: tags: - scan summary: >- Scan a WFP — synchronous single-shot, or one block of a chunked async upload description: | Dual-mode upload, selected by the presence of the `X-Scan-Id` request header. Both modes return the same `ScanEnvelope` envelope, and the `result` payload is byte-identical to the polled async result (both run the same batchScanner pipeline → same `Report`). **Mode B — synchronous single-shot (no `X-Scan-Id`).** The request body is one complete WFP (`application/octet-stream`, capped at `scan.max_upload_size`), scanned inline. Responds `200` with a `ScanEnvelope` already at `status: completed`, carrying `result`, `files_total` and a fresh `scan_id` (for traceability only — no session is created, nothing to poll). `Content-Range` is ignored. An empty/whitespace body → `400 INVALID_BODY`. The request blocks for the whole scan, so this mode is bounded by the request timeout and intended for small inputs. **Mode A — chunked async (`X-Scan-Id` present).** One block of a multi-block upload too large for a single request. The client generates the session id — a **canonical lowercase UUIDv7** — and sends it on **every** block (it is what a load balancer hashes on to keep all blocks on one instance). `Content-Range: bytes -/` is **required**. Blocks are reassembled by their declared byte offset, so they **may be uploaded in any order or concurrently**; the first received block need not start at offset 0. Each block responds `202` with a `ScanEnvelope` (`status: uploading`). When the received ranges fully cover `[0, total)` with no gaps, the upload is sealed and the batchScanner pipeline is queued (its stages call the scan API over HTTP); poll `GET /v3/wfp/scan/{id}` for progress/result. `received_bytes` reports the total distinct bytes covered so far. Re-POSTing an already-received range with identical bytes is an idempotent `202` no-op. Mode A errors: a non-canonical / non-UUIDv7 id → `400 INVALID_SCAN_ID`; missing `Content-Range` → `400 MISSING_RANGE`; malformed `Content-Range` (or a body length that disagrees with the range) → `400 INVALID_RANGE`; an overlapping block carrying **conflicting** bytes, or reuse of a sealed id → `409 RANGE_CONFLICT` (note: out-of-order arrival alone is **not** a conflict); a block or declared total over the configured limits → `413 PAYLOAD_TOO_LARGE`. operationId: postScanBatch parameters: - in: header name: X-Scan-Id required: false schema: type: string format: uuid description: > Absent → Mode B (synchronous single-shot). Present → Mode A (chunked async): a client-generated canonical lowercase UUIDv7, sent on every block of the session. example: 018f7b2c-9a3e-7d41-8b6a-2c1d4e5f6a7b - in: header name: Content-Range required: false schema: type: string description: > Required in Mode A (`X-Scan-Id` present): byte range of this block, e.g. `bytes 0-8388607/26214400` (end inclusive, 0-based). Ignored in Mode B. example: bytes 0-8388607/26214400 requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: '200': description: > Mode B only. The WFP was scanned inline; `ScanEnvelope` is at `status: completed` with `result` and `files_total` populated. content: application/json: schema: $ref: '#/components/schemas/ScanEnvelope' '202': description: > Mode A only. Block accepted; `ScanEnvelope` at `status: uploading` (the final block transitions the session to queued → scanning). headers: X-Scan-Id: schema: type: string format: uuid description: The session id (also present in the body). content: application/json: schema: $ref: '#/components/schemas/ScanEnvelope' '400': description: > `INVALID_BODY` (Mode B empty WFP), `INVALID_SCAN_ID` (Mode A: id is not a canonical lowercase UUIDv7), `MISSING_RANGE` (Mode A: no `Content-Range`) or `INVALID_RANGE` (Mode A: malformed range / body length mismatch). content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: status: error error: code: INVALID_SCAN_ID message: 'invalid scan id: not a UUIDv7' timestamp: '2026-05-19T11:39:56Z' '409': $ref: '#/components/responses/RangeConflict' '413': $ref: '#/components/responses/PayloadTooLarge' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/EngineUnavailable' '504': $ref: '#/components/responses/Timeout' components: schemas: ScanEnvelope: type: object description: > Unified status envelope returned by `POST /v3/wfp/scan` (both modes) and `GET /v3/wfp/scan/{id}`. Mode B returns it synchronously already at `status: completed`; Mode A returns it per block (`uploading`) and on each poll. Zero-valued fields are omitted, so an uploading session carries no scan counters and a running scan carries no result. required: - scan_id - status properties: scan_id: type: string format: uuid x-go-type: string description: > Canonical lowercase UUIDv7 session id. In Mode A this is the client-supplied id; in Mode B it is a server-generated id for traceability only (no session is created). example: 018f7b2c-9a3e-7d41-8b6a-2c1d4e5f6a7b status: type: string enum: - uploading - queued - scanning - completed - failed - expired received_bytes: type: integer x-go-type-skip-optional-pointer: true description: Bytes received so far (Mode A upload; omitted when 0). total_bytes: type: integer x-go-type-skip-optional-pointer: true description: Declared total upload size (Mode A; omitted when 0). upload_percent: type: integer x-go-type-skip-optional-pointer: true description: Exact upload progress percent (Mode A; omitted when 0). phase: type: string x-go-type-skip-optional-pointer: true description: 'Current pipeline pass while scanning, e.g. ''Pass 1: scan files''.' phase_done: type: integer x-go-type-skip-optional-pointer: true description: Items processed in the current phase. phase_total: type: integer x-go-type-skip-optional-pointer: true description: Total items in the current phase. files_total: type: integer x-go-type-skip-optional-pointer: true description: File count of the report, filled in on completion. result: allOf: - $ref: '#/components/schemas/ScanResult' description: > Populated only when status is `completed`. The batchScanner report — byte-identical whether obtained synchronously (Mode B) or by polling an async session to completion (Mode A). error: type: string x-go-type-skip-optional-pointer: true description: Populated only when status is `failed`. ErrorBody: type: object required: - status - error - timestamp properties: status: type: string enum: - error error: type: object required: - code - message properties: code: type: string description: | Stable machine-readable error identifier. Possible values: - INVALID_BODY, INVALID_QUERY, INVALID_FILE_HASH, INVALID_RANGE - EMPTY_BATCH - INVALID_PURL, COMPONENT_NOT_FOUND, VERSION_NOT_FOUND - NOTICE_NOT_FOUND, FILE_NOT_FOUND, MZ_READ_FAILED - TIMEOUT, INTERNAL_ERROR message: type: string timestamp: type: string format: date-time ScanResult: type: object description: > batchScanner multi-pass report: a `files` array of per-file match entries and a `components` map keyed by url_hash. Produced by /wfp/scan (not raw engine output). properties: server: allOf: - $ref: '#/components/schemas/ScanServer' description: > Optional run/server metadata passed through from the batchScanner pipeline when present; omitted otherwise. files: type: array x-go-type-skip-optional-pointer: true description: One entry per scanned file (order is unspecified). items: $ref: '#/components/schemas/FileResult' components: type: object x-go-type-skip-optional-pointer: true description: Resolved components keyed by url_hash. Extra fields may be present. additionalProperties: $ref: '#/components/schemas/ComponentResult' ScanServer: type: object description: > Run/server metadata for the scan, produced by the batchScanner pipeline and passed through unchanged. Fields may be empty; open to extra passthrough fields. properties: api_version: type: string x-go-type-skip-optional-pointer: true description: batchScanner API version. knowledge_base: allOf: - $ref: '#/components/schemas/KnowledgeBase' hostname: type: string x-go-type-skip-optional-pointer: true description: Host that ran the scan. elapsed_ms: type: integer x-go-type-skip-optional-pointer: true description: Scan wall-clock time, in milliseconds. FileResult: type: object description: One scanned-file entry in a batchScanner report. required: - path - source_hash - file_hash - match_type - matches properties: path: type: string description: The scanned file path. source_hash: type: string description: MD5 of the input file (from the WFP). file_hash: type: string description: >- MD5 of the matched file: equals `source_hash` for a `file` match, the matched OSS file's MD5 for a `snippet` match (differs from `source_hash`), and empty for a `none` match. match_type: type: string enum: - file - snippet - none description: Full-file match, partial (snippet) match, or no match. matches: type: array description: Matched KB entries for this file. items: $ref: '#/components/schemas/MatchResult' ComponentResult: type: object description: > A resolved component in a batchScanner report, keyed by url_hash in `ScanResult.components`. Open to extra upstream fields. properties: component: type: string x-go-type-skip-optional-pointer: true vendor: type: string x-go-type-skip-optional-pointer: true version: type: string x-go-type-skip-optional-pointer: true file: type: string x-go-type-skip-optional-pointer: true url: type: string x-go-type-skip-optional-pointer: true release_date: type: string x-go-type-skip-optional-pointer: true rank: type: integer x-go-type-skip-optional-pointer: true purls: type: array items: type: string x-go-type-skip-optional-pointer: true KnowledgeBase: type: object description: SCANOSS knowledge-base versions the scan ran against. properties: monthly_version: type: string x-go-type-skip-optional-pointer: true description: Monthly KB snapshot version. daily_version: type: string x-go-type-skip-optional-pointer: true description: Daily KB delta version. MatchResult: type: object description: One matched KB entry for a scanned file. required: - url_hash - confidence properties: url_hash: type: string description: url_hash of the matched component release. confidence: type: string enum: - LOW - MEDIUM - HIGH description: 'Attribution reliability grade for this match: LOW, MEDIUM or HIGH.' oss_file_path: type: string x-go-type-skip-optional-pointer: true description: Path of the matched file inside the OSS component. match_percentage: type: integer x-go-type-skip-optional-pointer: true description: Snippet matches only; omitted for full-file matches. input_line_ranges: type: array x-go-type-skip-optional-pointer: true description: Snippet matches only — matched line ranges in the input file. items: $ref: '#/components/schemas/LineRange' oss_line_ranges: type: array x-go-type-skip-optional-pointer: true description: Snippet matches only — matched line ranges in the OSS file. items: $ref: '#/components/schemas/LineRange' LineRange: type: object description: A matched line range (inclusive) within a file. required: - start_line - end_line properties: start_line: type: integer description: First line of the matched range. end_line: type: integer description: Last line of the matched range. responses: RangeConflict: description: Block range gaps or overlaps the bytes already received content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: status: error error: code: RANGE_CONFLICT message: block does not continue from received_bytes timestamp: '2026-05-19T11:39:56Z' PayloadTooLarge: description: Upload exceeds the configured size limit content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: status: error error: code: PAYLOAD_TOO_LARGE message: upload exceeds max size timestamp: '2026-05-19T11:39:56Z' InternalError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: status: error error: code: INTERNAL_ERROR message: ... timestamp: '2026-05-19T11:39:56Z' EngineUnavailable: description: The scan engine is not configured or not executable content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: status: error error: code: ENGINE_UNAVAILABLE message: scan engine not available timestamp: '2026-05-19T11:39:56Z' Timeout: description: Request exceeded the server-side deadline content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: status: error error: code: TIMEOUT message: request timed out timestamp: '2026-05-19T11:39:56Z' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.