Skip to main content

​
Prerequisites

Before using the SCANOSS API, ensure you have:
  • SCANOSS API key
  • curl: 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: 
X-Api-Key: your-api-key-here

​
Example with curl

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

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

​
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 for full details on constraint syntax.

​
Error Handling

Request-level errors are indicated by standard HTTP status codes:
CodeMeaning
400 Bad RequestInvalid request format or parameters
401 UnauthorizedMissing or invalid API key
403 ForbiddenAuthenticated but not authorized
404 Not FoundEndpoint or resource not found
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorUnexpected server-side error
503 Service UnavailableTemporary service or dependency outage