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

# API Overview

> Introduction to the SCANOSS API for software composition analysis, dependency information, vulnerability detection, and cryptography intelligence.

## Prerequisites

Before using the SCANOSS API, ensure you have:

* **SCANOSS API key**
* [curl](https://curl.se/): Command-line tool (pre-installed on Linux/macOS)
* **jq** (optional): JSON processor for readable output

## API Endpoints

The SCANOSS API is organised into several functional areas:

### Cryptography API

Analyse cryptographic algorithms, usage hints and version coverage for software components.

**Base URL**: `https://api.scanoss.com/v2/cryptography/`

**Key Endpoints**:

* `GET /algorithms/component` — Get algorithms for a component

* `POST /algorithms/components` — Get algorithms for multiple components

* `GET /algorithms/range/component` — Get algorithms across a version range

* `GET /algorithms/range/components` — Get algorithms across version ranges for multiple components

* `GET /algorithms/versions/range/component` — Get versions that include or exclude cryptographic algorithms

* `POST /algorithms/version/range/components` — Get versions that include or exclude cryptographic algorithms for multiple components

* `GET /hints/component` — Get cryptographic hints for a component

* `POST /hints/components` — Get cryptographic hints for multiple components

* `GET /rulesets/dca/latest/download` — Download DCA cryptography detection rules

* `GET /rulesets/keywords/v1.2.3/download` — Download keyword-based cryptography detection rules

### Vulnerability API

Provides vulnerability data for software components, including CPE identifiers and known vulnerabilities (CVEs).

**Base URL**: `https://api.scanoss.com/v2/vulnerabilities/`

**Key Endpoints**:

* `GET /cpes/component` — Get CPE identifiers for a component

* `POST /cpes/components` — Get CPE identifiers for multiple components

* `GET /component` — Get known vulnerabilities for a component, including CVEs and severity data

* `POST /components` — Get known vulnerabilities for multiple components, including CVEs and severity data

### Component Search API

Search components and retrieve versions, metadata, code statistics, and lifecycle status.

**Base URL**: `https://api.scanoss.com/v2/components/`

**Key Endpoints**:

* `GET /search` — Search components by name, PURL, or attributes

* `GET /versions` — Get available versions and metadata for a component

* `GET /statistics` — Get code statistics (files, lines, languages) for a component

* `GET /status/component` — Get lifecycle status for a component

* `POST /status/components` — Get lifecycle status for multiple components

### License API

Retrieve license information for software components, including SPDX details and approval status.

**Base URL**: `https://api.scanoss.com/v2/licenses/`

**Key Endpoints**:

* `GET /component` — Get license information for a component
* `POST /components` — Get license information for multiple components

### Geoprovenance API

Retrieve geographical provenance of software components using contributor locations, commit timing patterns, and development activity.

**Base URL**: `https://api.scanoss.com/v2/geoprovenance/`

**Key Endpoints**:

* `GET /countries/component` — Geographical provenance from declared contributor locations

* `POST /countries/components` — Geographical provenance from declared contributor locations for multiple components

* `GET /origin/component` — Geographical origin inferred from commit timing patterns

* `POST /origin/components` — Geographical origin inferred from commit timing patterns for multiple components

### Dependencies API

Provides dependency analysis for software components, including direct and transitive dependency resolution.

**Base URL**: `https://api.scanoss.com/v2/dependencies/`

**Key Endpoint**:

* `POST /transitive/components` — Get the full transitive dependency tree for software components, including all indirect dependencies

### Scanning API

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

**Base URL**: `https://api.scanoss.com/v2/`

**Key Endpoint**:

* `POST /scanning/hfh/scan` — Scan folder structures to identify software components using hierarchical hashing

### Semgrep API

Detect security, quality, and compliance issues in software components using Semgrep static analysis.

**Base URL**: `https://api.scanoss.com/v2/`

**Key Endpoint**:

* `POST /semgrep/issues/components` — Get security issues for multiple components using Semgrep static analysis
* `GET /semgrep/issues/component` — Get security issues for a component using Semgrep static analysis

## Authentication

All API requests require authentication using an API key.

### Using Your API Key

Include your API key in the request header:

```bash theme={null}
X-Api-Key: your-api-key-here
```

### Example with curl

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/components/search?search=scanoss&limit=10' \
  -H "X-Api-Key: your-api-key-here"
```

### Environment Variable Setup

For convenience, store your API key as an environment variable:

```bash theme={null}
# Set API key
export SCANOSS_API_KEY="your-api-key-here"

# Use in requests
curl -X GET 'https://api.scanoss.com/v2/components/search?search=scanoss&limit=10' \
  -H "X-Api-Key: $SCANOSS_API_KEY"
```

### Persistent Configuration

Add to your shell profile for persistence:

```bash theme={null}
# Add to ~/.bashrc or ~/.zshrc
echo 'export SCANOSS_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

## Common Concepts

### Echo

Standard service health check endpoint for testing connectivity and API key validation.

#### HTTP Request

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/dependencies/echo' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{"message": "test"}'
```

### Package URLs (PURLs)

SCANOSS uses **Package URLs (PURLs)** as the standard identifier for
software components. A PURL follows this format:

```
pkg:<type>/<namespace>/<name>@<version>
```

**Examples**:

* `pkg:github/scanoss/engine@5.0.0`
* `pkg:npm/express@4.18.2`
* `pkg:maven/org.springframework/spring-core@5.3.23`
* `pkg:pypi/django@4.2.0`

Learn more: [Package URL Specification](https://github.com/package-url/purl-spec)

### Version Requirements

The `requirement` field accepts **semantic version (semver) constraints**
to filter results by version range:

* `>=5.0.0` — Greater than or equal to version 5.0.0
* `~1.30.0` — Patch-level changes only (approximately equivalent to 1.30.x)
* `^2.0.0` — Minor- and patch-level changes only (compatible with 2.x.x)
* `1.0.0` — Exact version match

See the [semver specification](https://semver.org) for full details on
constraint syntax.

### Error Handling

**Request-level errors** are indicated by standard HTTP status codes:

| Code                        | Meaning                                |
| --------------------------- | -------------------------------------- |
| `400 Bad Request`           | Invalid request format or parameters   |
| `401 Unauthorized`          | Missing or invalid API key             |
| `403 Forbidden`             | Authenticated but not authorized       |
| `404 Not Found`             | Endpoint or resource not found         |
| `429 Too Many Requests`     | Rate limit exceeded                    |
| `500 Internal Server Error` | Unexpected server-side error           |
| `503 Service Unavailable`   | Temporary service or dependency outage |