Name: SCA API — Software Composition Analysis for npm & PyPI
Brand: quotalink
SKU: api-quotalink-sca-api
Availability: InStock
Author: API Market

李乐

## Overview

SCA API brings software composition analysis to any npm or PyPI package through a single HTTP call. Pass a package name and get back its metadata, a vulnerability list drawn from the NIST National Vulnerability Database, a severity breakdown, a heuristic risk score and a license assessment.

It is built for the checks you want inside CI, a procurement workflow or a dependency dashboard, without standing up a scanner of your own.

## Features

- **npm and PyPI coverage**: scan packages from either ecosystem with the same request shape.
- **NIST NVD vulnerability data**: CVE identifiers, CVSS scores, severities, descriptions and publication dates.
- **Severity breakdown**: counts bucketed into CRITICAL, HIGH, MEDIUM, LOW and UNKNOWN.
- **Heuristic risk score**: a single 0 to 100 number plus a `risk_level` label for quick triage.
- **License risk assessment**: the declared license with a plain-English risk note.
- **Keyword CVE search**: query the NVD directly by keyword, independent of any one package.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **CI/CD security gates**: fail a build when a dependency crosses a severity threshold.
- **Dependency review**: check a package before adding it to your project.
- **License compliance**: flag copyleft or unusual licenses before shipping.
- **Vendor and procurement due diligence**: assess third-party libraries in a security questionnaire.
- **Security dashboards**: track the risk profile of your dependency tree over time.
- **Vulnerability research**: search the NVD by keyword for a technology or vendor.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/sca-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Ecosystems

`/scan` and `/license-check` take an `ecosystem` parameter.

| Value | Registry |
| --- | --- |
| `npm` | npm Registry |
| `pypi` | Python Package Index |

### Endpoints

#### GET /scan

Full composition analysis for one package: metadata, vulnerabilities, severity breakdown and risk score.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `package` | query | string | Yes | Package name, for example `lodash` |
| `ecosystem` | query | string | No | `npm` or `pypi`, defaults to `npm` |

```bash
curl "https://prod.api.market/api/v1/quotalink/sca-api/scan?ecosystem=npm&package=lodash" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "package": {
    "name": "lodash",
    "version": "4.18.1",
    "ecosystem": "npm",
    "license": "MIT",
    "description": "Lodash modular utilities.",
    "homepage": "https://lodash.com/"
  },
  "security": {
    "score": 0,
    "risk_level": "CRITICAL",
    "total_vulnerabilities": 17,
    "severity_breakdown": {
      "CRITICAL": 2, "HIGH": 6, "MEDIUM": 9, "LOW": 0, "UNKNOWN": 0
    }
  },
  "vulnerabilities": [
    {
      "cve_id": "CVE-2024-38986",
      "severity": "CRITICAL",
      "score": 9.8,
      "published": "2024-07-30",
      "description": "Prototype Pollution ..."
    }
  ],
  "meta": {
    "data_sources": ["NIST NVD v2.0", "npm Registry", "PyPI"],
    "scan_time": "2026-08-22T21:41:37.704804Z",
    "disclaimer": "Vulnerability data from NIST NVD. Score is heuristic and should not be the sole basis for security decisions."
  }
}
```

`vulnerabilities` is capped at the 10 highest-scoring entries; `security.total_vulnerabilities` reports the true count. `security.score` runs 0 to 100 where higher is safer, so a `CRITICAL` risk level pairs with a score near 0.

Matching is by package name, so results can include CVEs for similarly named or related projects. Treat the list as a starting point for review rather than a definitive per-version verdict.

#### GET /vulnerabilities

Free-text CVE search against the NVD. Note that this endpoint takes `keyword`, not `package`.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `keyword` | query | string | Yes | Search term, for example `openssl` |

```bash
curl "https://prod.api.market/api/v1/quotalink/sca-api/vulnerabilities?keyword=openssl" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "query": "openssl",
  "total_results": 599,
  "returned": 10,
  "vulnerabilities": [
    {
      "cve_id": "CVE-1999-0428",
      "severity": "HIGH",
      "score": 7.5,
      "published": "1999-01-01",
      "description": "OpenSSL and SSLeay allow remote attackers to reuse SSL sessions ..."
    }
  ],
  "meta": {
    "source": "NIST NVD v2.0",
    "search_time": "2026-08-22T21:34:58.397264Z"
  }
}
```

Calling this endpoint without `keyword` returns `400` with `{"error":"Missing required parameter: keyword"}`.

#### GET /license-check

The declared license for a package, with a risk label and explanatory notes.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `package` | query | string | Yes | Package name |
| `ecosystem` | query | string | No | `npm` or `pypi`, defaults to `npm` |

```bash
curl "https://prod.api.market/api/v1/quotalink/sca-api/license-check?ecosystem=npm&package=lodash" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "package": "lodash",
  "version": "4.18.1",
  "ecosystem": "npm",
  "license": "MIT",
  "risk_level": "LOW",
  "notes": ["Permissive license — minimal restrictions on use"]
}
```

`risk_level` reflects how restrictive the license is, not the package's security posture.

#### GET /health

Service liveness. Takes no parameters and is useful for monitoring.

```bash
curl "https://prod.api.market/api/v1/quotalink/sca-api/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{ "service": "sca-api", "status": "ok", "version": "1.0.0" }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | A required parameter or the `x-api-market-key` header is missing | Check `package` / `keyword` and headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | Registry or NVD upstream error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **FREE**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **Basic**: 1,000 API units per month, soft limit, with overage billed per additional call.

Every endpoint costs one unit per request.

## Error Handling

Missing parameters return a `400` naming the field:

```json
{ "error": "Missing required parameter: package" }
```

```json
{ "error": "Missing required parameter: keyword" }
```

`/scan` and `/license-check` use `package`; `/vulnerabilities` uses `keyword`. Mixing them up is the most common integration error.

The NVD applies its own rate limits upstream. Under sustained load a keyword search can return `total_results: 0` where a moment earlier it returned matches. Treat an empty result set as inconclusive rather than as proof of no vulnerabilities, and retry after a short pause.

## Implementation Guide

### Example Code

```python
import requests

BASE = "https://prod.api.market/api/v1/quotalink/sca-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def gate(package, ecosystem="npm", max_critical=0):
    r = requests.get(f"{BASE}/scan", headers=HEADERS, timeout=30,
                     params={"package": package, "ecosystem": ecosystem})
    r.raise_for_status()
    sec = r.json()["security"]
    critical = sec["severity_breakdown"]["CRITICAL"]
    if critical > max_critical:
        raise SystemExit(
            f"{package}: {critical} critical CVEs, score {sec['score']}"
        )
    return sec

gate("lodash")
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/sca-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function licenseRisk(pkg, ecosystem = "npm") {
  const url = `${BASE}/license-check?package=${encodeURIComponent(pkg)}&ecosystem=${ecosystem}`;
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`License check failed: ${res.status}`);
  const { license, risk_level, notes } = await res.json();
  return { license, risk_level, notes };
}

console.log(await licenseRisk("lodash"));
```

### Performance Optimization

- Cache scan results per package and version. Published CVE data changes daily at most, so a 24 hour cache is usually safe and removes nearly all repeat calls.
- Scan only your direct dependencies on every build, and run the full tree on a nightly schedule.
- Use `/license-check` when license is all you need, because it is a lighter call than a full `/scan`.
- Stay within 10 requests per second when scanning a manifest; queue the packages rather than firing them all at once.

## FAQ

**Do I need an account with QuotaLink or NIST to use this API?**

No. Your API.market key is the only credential required.

**Which ecosystems are supported?**

npm and PyPI. Pass `ecosystem=npm` or `ecosystem=pypi`; `npm` is the default.

**Why does `/vulnerabilities` reject my `package` parameter?**

That endpoint searches by free text and expects `keyword`. Only `/scan` and `/license-check` take `package`.

**Why are only 10 vulnerabilities listed when the total is higher?**

The array is capped at the 10 highest-scoring entries. `security.total_vulnerabilities` gives the full count.

**Can I scan a specific version of a package?**

Not currently. Scans resolve against the package as published in the registry, and the version scanned is reported in the response.

**Why did a keyword search return zero results when it worked a minute ago?**

The upstream NVD rate limits requests. Retry after a short pause and treat an empty result as inconclusive.

**Is the security score authoritative?**

No. It is a heuristic, as the response disclaimer states, and should not be the sole basis for a security decision.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Scan npm and PyPI packages for known CVE vulnerabilities, license compliance, and security scoring. Powered by NIST NVD.