> ## 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.

# Scanning API

> Provides high-precision scanning of folder structures to identify software components based on project hierarchy, file names, and content patterns.

## FolderHashScan

Scan folder structures to identify software components using hierarchical proximity hashing.

The scan evaluates filenames, directory structure, and file content to generate similarity scores against the SCANOSS knowledge base.

### Request Format

The request defines a hierarchical folder tree:

* `root`: The root folder node containing the structure to scan
  * `path_id`: Folder identifier (can be obfuscated)
  * `sim_hash_names`: Hash derived from filenames
  * `sim_hash_content`: Hash derived from file contents
  * `sim_hash_dir_names`: Hash derived from directory structure
  * `lang_extensions`: File type distribution (e.g., \{"py": 15, "js": 8})
  * `children`: Nested folder nodes following the same structure

Optional filtering parameters:

* `rank_threshold`: Filter by ecosystem (e.g. github, npm, maven)
* `category`: Filter by ecosystem (e.g. github, npm, maven)
* `query_limit`: Max results per folder
* `recursive_threshold`: Minimum score for recursive matches
* `min_accepted_score`: Minimum similarity score (0–1)

### HTTP Request Example

````bash theme={null}
```bash
curl -X POST 'https://api.scanoss.com/v2/scanning/hfh/scan' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "root": {
      "path_id": "src",
      "sim_hash_names": "abc123def456",
      "sim_hash_content": "789ghi012jkl",
      "sim_hash_dir_names": "345mno678pqr",
      "lang_extensions": {
        "py": 25,
        "md": 3
      },
      "children": [
        {
          "path_id": "src/utils",
          "sim_hash_names": "def456ghi789",
          "sim_hash_content": "012jkl345mno",
          "sim_hash_dir_names": "678pqr901stu",
          "lang_extensions": {
            "py": 8
          },
          "children": []
        }
      ]
    },
    "rank_threshold": 5,
    "category": "github",
    "query_limit": 10,
    "min_accepted_score": 0.7
  }' | jq
````

### Response Format

Returns scan results grouped by folder path.

* `results`: List of folder paths with their matching components
* `status`: Response status indicating success or failure

Each result includes:

* `path_id`: The folder path identifier from the request
* `components`: List of matching components found in this folder

Each component includes:

* `purl`: Component Package URL
* `name`: Component name
* `vendor`: Component maintainer or organisation
* `versions`: Matched versions with similarity scores
* `rank`: Component quality rank (1–9)
* `order`: Match priority (1 = best match)

### Response Example

#### Successful Scan with Matches

```json theme={null}
{
  "results": [
    {
      "path_id": "src",
      "components": [
        {
          "purl": "pkg:github/scanoss/scanoss.py",
          "name": "scanoss-py",
          "vendor": "scanoss",
          "versions": [
            {
              "version": "1.30.0",
              "score": 0.95,
              "licenses": [
                {
                  "name": "MIT License",
                  "spdx_id": "MIT",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/MIT.html"
                }
              ]
            },
            {
              "version": "1.29.0",
              "score": 0.87,
              "licenses": [
                {
                  "name": "MIT License",
                  "spdx_id": "MIT",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/MIT.html"
                }
              ]
            }
          ],
          "rank": 1,
          "order": 1
        },
        {
          "purl": "pkg:github/example/similar-project",
          "name": "similar-project",
          "vendor": "example",
          "versions": [
            {
              "version": "2.1.0",
              "score": 0.78,
              "licenses": [
                {
                  "name": "Apache License 2.0",
                  "spdx_id": "Apache-2.0",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/Apache-2.0.html"
                },
                {
                  "name": "MIT License",
                  "spdx_id": "MIT",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/MIT.html"
                }
              ]
            }
          ],
          "rank": 3,
          "order": 2
        }
      ]
    },
    {
      "path_id": "src/utils",
      "components": [
        {
          "purl": "pkg:pypi/requests",
          "name": "requests",
          "vendor": "psf",
          "versions": [
            {
              "version": "2.31.0",
              "score": 0.92,
              "licenses": [
                {
                  "name": "Apache License 2.0",
                  "spdx_id": "Apache-2.0",
                  "is_spdx_approved": true,
                  "url": "https://spdx.org/licenses/Apache-2.0.html"
                }
              ]
            }
          ],
          "rank": 1,
          "order": 1
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Scan completed successfully"
  }
}
```

#### Scan with No Matches

```json theme={null}
{
  "results": [],
  "status": {
    "status": "SUCCESS",
    "message": "Scan completed successfully"
  }
}
```

### Match Quality

**Rank (1-9)**

Indicates confidence in component origin:

* **1-2**: Official or highly trusted repositories
* **3-4**: Verified community projects
* **5-6**: Standard open-source projects
* **7-9**: Lower confidence or derivative matches

**Score (0-1)**

Similarity confidence per version:

* **0.9-1.0**: Very high confidence
* **0.8-0.89**: High confidence
* **0.7-0.79**: Moderate confidence
* **Below 0.7**: Low confidence (filterable via `min_accepted_score`)