# Package & Dependency Trust API — score an open-source package or repository (npm, PyPI, Go, Cargo, RubyGems): downloads, maintainers, license, repo health and vulnerabilities, plus lockfile scanning

> ecosystem+package → registry metadata + downloads + maintainers + license + resolved repository health + vulnerabilities + partial trust score (with per-sub-score inputs)
> ReefAPI engine `enrich-package` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/enrich-package/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /enrich-package/v1/package_trust — 3 credits
ecosystem+package → registry metadata + downloads + maintainers + license + resolved repository health + vulnerabilities + partial trust score (with per-sub-score inputs)

**Parameters:**
- `ecosystem` (enum, required) — Package ecosystem. npm/pypi get full registry metadata + downloads; maven/rubygems/crates/go get vulnerabilities + declared-repository health (the wider OSV ecosystem set). [one of: npm, pypi, maven, rubygems, crates, go]
- `package` (string, required) — Package name as published in its registry (npm 'lodash', PyPI 'requests', Maven 'group:artifact', Go import path). Scoped npm names like '@scope/pkg' are supported.
- `version` (string, optional) — Exact installed version to assess for vulnerabilities. Omit to assess the latest published version + ALL known vulns of the package.
- `mode` (enum, optional, default "rich") — basic = registry metadata + license + repo health + score; rich (default) adds the full vulnerability scan, release cadence, contributor bus-factor and a stackoverflow community signal. [one of: basic, rich]

**Returns:** package{name,ecosystem,version,description,homepage}, metadata{license{value,spdx,tier,risk_note}, maintainers[], keywords, version_count, latest}, downloads{monthly|recent}, repo{found,host,owner,repo,repo_url,match{confidence,class,source_field,name_similarity,evidence[],reason}, health{stars,forks,open_issues,archived,pushed_at,last_release,releases_12mo,contributors,bus_factor}}, vulnerabilities{count,highest_severity,by_severity,items[]}, dependencies{direct_count,sample}, community{stackoverflow}, score{popularity,maintenance,security,license,dependency_risk — each {score|'unknown',inputs,method,flags?}, overall{trust_score,grade,scored_components,unknown_components}}; provenance{per-group status+engine+missing_reason}; meta.extra.subcalls[]

**Example request body:**
```json
{
  "ecosystem": "npm",
  "package": "lodash",
  "version": "4.17.15",
  "mode": "rich"
}
```

### POST /enrich-package/v1/repo_trust — 3 credits
owner/repo → repository health + release cadence + bus-factor signal + repo-anchored trust sub-scores (popularity/maintenance), independent of any registry

**Parameters:**
- `owner` (string, required) — GitHub repository owner / org (e.g. 'facebook').
- `repo` (string, required) — GitHub repository name (e.g. 'react').

**Returns:** repo{owner,repo,repo_url,health{stars,forks,watchers,open_issues,archived,license,pushed_at,created_at,last_release,releases_12mo,contributors,bus_factor,top_languages}}, score{popularity,maintenance,license,overall}; provenance; meta.extra.subcalls[]

**Example request body:**
```json
{
  "owner": "facebook",
  "repo": "react"
}
```

### POST /enrich-package/v1/lockfile_scan — 5 credits
manifest/lockfile text → dependency list + each dep's vuln/risk summary via one batched vuln scan (BOUNDED: direct + lockfile-pinned deps, max 100; truncated:true when capped). package.json/lock, requirements.txt, go.sum/mod, Cargo.lock, Gemfile.lock

**Parameters:**
- `content` (string, required) — Raw manifest/lockfile text: package.json, package-lock.json, requirements.txt, go.sum/go.mod, Cargo.lock, or Gemfile.lock. Direct (+ lockfile-pinned) deps are scanned; bounded to 100 deps.
- `filename` (string, optional) — Optional filename hint to disambiguate the manifest format (e.g. 'package-lock.json', 'go.sum'). Auto-detected if omitted.
- `ecosystem` (enum, optional) — Optional ecosystem hint when the manifest format is ambiguous. [one of: npm, pypi, maven, rubygems, crates, go]

**Returns:** manifest{ecosystem,format,dependency_count,truncated,parsed_count}, summary{vulnerable_deps,total_vulns,highest_severity,by_severity,clean_deps}, dependencies[] (ecosystem,name,version,vuln_count,highest_severity,vulns[]); meta.extra.subcalls[]

**Example request body:**
```json
{
  "content": "lodash\nflask==2.0.0\nrequests==2.20.0",
  "filename": "requirements.txt"
}
```

### POST /enrich-package/v1/batch — 2 credits
trust-score up to 10 packages in one call (basic depth, per-item ok/error)

**Parameters:**
- `items` (array, required) — Up to 10 {ecosystem, package, version?} objects. Each is trust-scored like package_trust (basic depth); per-item ok/error.

**Returns:** results[] (one package_trust basic payload or {ok:false,error} per item), count, ok_count

**Example request body:**
```json
{
  "items": [
    {
      "ecosystem": "npm",
      "package": "p0"
    },
    {
      "ecosystem": "npm",
      "package": "p1"
    },
    {
      "ecosystem": "npm",
      "package": "p2"
    },
    {
      "ecosystem": "npm",
      "package": "p3"
    },
    {
      "ecosystem": "npm",
      "package": "p4"
    },
    {
      "ecosystem": "npm",
      "package": "p5"
    },
    {
      "ecosystem": "npm",
      "package": "p6"
    },
    {
      "ecosystem": "npm",
      "package": "p7"
    },
    {
      "ecosystem": "npm",
      "package": "p8"
    },
    {
      "ecosystem": "npm",
      "package": "p9"
    },
    {
      "ecosystem": "npm",
      "package": "p10"
    }
  ]
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=enrich-package
- Human docs page: https://reefapi.com/docs/enrich-package
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt