Skip to main content

​
Introduction

The SCANOSS API provides software composition analysis capabilities, enabling developers and organisations to:
  • Identify open-source components in their codebase
  • Detect vulnerabilities in dependencies
  • Analyse cryptographic algorithms and implementations
  • Retrieve component metadata and licensing information
  • Enrich dependencies with security and compliance data

​
API Endpoints

The SCANOSS API is organised into several functional areas:

​
Cryptography API

Analyse cryptographic algorithms, protocols, and libraries used in software components. Base URL: https://api.scanoss.com/v2/cryptography/ Key Endpoints:
  • GET /algorithms/component — Get algorithms for a single component
  • POST /algorithms/components — Get algorithms for multiple components
  • GET /algorithms/range/component — Get algorithms across version ranges
  • GET /hints/component — Get cryptographic hints for a component
  • GET /algorithms/versions/range/component — Get versions with or without algorithms

​
Vulnerability API

Access vulnerability intelligence including CVEs, CPEs, and security advisories. Base URL: https://api.scanoss.com/v2/vulnerabilities/ Key Endpoints:
  • GET /component — Get vulnerabilities for a single component
  • POST /components — Get vulnerabilities for multiple components
  • GET /cpes/component — Get CPE identifiers for a component
  • POST /cpes/components — Get CPE identifiers for multiple components

​
Component Search API

Search and retrieve information about open-source components. Base URL: https://api.scanoss.com/v2/components/ Key Endpoints:
  • GET /search — Search components by name, PURL, or attributes
  • GET /versions/component — Retrieve version information for a component
  • GET /metadata/component — Retrieve component metadata and licensing

​
Dependency Decoration API

Enrich dependency information with security, licensing, and compliance data. Decoration refers to augmenting a dependency record with additional intelligence (vulnerabilities, licences, cryptographic data) without modifying the original dependency definition. Base URL: https://api.scanoss.com/v2/dependencies/ Key Endpoints:
  • POST /decorations — Decorate dependencies with vulnerability data
  • POST /decorations/licenses — Add licence and compliance information
  • POST /decorations/cryptography — Enrich with cryptographic intelligence

​
Raw Output API

Access raw scan results and low-level component matching data. Base URL: https://api.scanoss.com/scan/ Key Endpoints:
  • POST /direct — Submit code directly for scanning
  • POST /fingerprint — Submit file fingerprints for matching
  • GET /results — Retrieve raw match results

​
Authentication

All API requests require authentication using an API key.

​
Obtaining an API Key

  1. Visit SCANOSS Platform
  2. Sign up or log in to your account
  3. Navigate to the API Keys section
  4. Generate a new API key
  5. Copy the API key for use in your requests

​
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/vulnerabilities/component?purl=pkg:github/example/component' \
  -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/vulnerabilities/component?purl=pkg:github/example/component' \
  -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

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

​
Request Formats

The API supports both GET and POST requests: GET requests are used for single-component queries: 
curl -X GET \
  'https://api.scanoss.com/v2/vulnerabilities/component?purl=pkg:github/example/component&requirement=>=1.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY"
POST requests are used for batch queries (multiple components): 
curl -X POST 'https://api.scanoss.com/v2/vulnerabilities/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SCANOSS_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/example/component1", "requirement": ">=1.0.0"},
      {"purl": "pkg:github/example/component2", "requirement": "~2.0.0"}
    ]
  }'

​
Response Format

All API responses follow a consistent JSON structure. The component object contains fields specific to the endpoint called, alongside a top-level status object: 
{
  "component": {
    "purl": "pkg:github/example/component",
    "version": "1.0.0",
    "requirement": ">=1.0.0"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed successfully"
  }
}
Note: Additional fields are returned within the component object depending on the endpoint. Refer to each endpoint’s reference page for the full response schema.

​
Error Handling

Request-level errors are indicated by standard HTTP status codes:
CodeMeaning
400 Bad RequestInvalid request format or parameters
401 UnauthorizedInvalid or missing API key
404 Not FoundEndpoint or resource not found
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorUnexpected server-side error