# Package Registries API — npm (Node.js) and PyPI (Python) metadata, version history, dependencies, download counts and keyword search (no API key required)

> full package metadata (latest version normalized)
> ReefAPI engine `packages` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/packages/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 /packages/v1/package — 1 credit
full package metadata (latest version normalized)

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `name` (string, required) — Exact package name (e.g. npm 'react', PyPI 'requests'). Scoped npm names like '@scope/pkg' are supported.

**Returns:** package{} — name, latest version, description, license, homepage, repository, keywords, maintainers, dependencies, dist_tags/version_count, links

**Example request body:**
```json
{
  "registry": "npm",
  "name": "react"
}
```

### POST /packages/v1/versions — 1 credit
paginated version list for a package

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `name` (string, required) — Exact package name (e.g. npm 'react', PyPI 'requests'). Scoped npm names like '@scope/pkg' are supported.
- `page` (integer, optional, default 1) — 1-based page number for paginated lists (versions / search).
- `page_size` (integer, optional, default 50) — Results per page (1-250, default 50). Larger values are clamped.

**Returns:** versions[] (newest-first: version, latest flag, npm published_at / pypi file count); meta has page, page_size, total, has_more, next_page

**Example request body:**
```json
{
  "registry": "npm",
  "name": "react",
  "page_size": 10
}
```

### POST /packages/v1/version — 1 credit
single version metadata

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `name` (string, required) — Exact package name (e.g. npm 'react', PyPI 'requests'). Scoped npm names like '@scope/pkg' are supported.
- `version` (string, required) — Exact version string to fetch (e.g. '18.2.0', '2.31.0').

**Returns:** version{} — that version's description, license, homepage, repository, dependencies, dist/engines (npm) or requires_dist/classifiers (pypi)

**Example request body:**
```json
{
  "registry": "pypi",
  "name": "requests",
  "version": "2.34.2"
}
```

### POST /packages/v1/dependencies — 1 credit
runtime + dev dependencies for a version (latest if omitted)

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `name` (string, required) — Exact package name (e.g. npm 'react', PyPI 'requests'). Scoped npm names like '@scope/pkg' are supported.
- `version` (string, optional) — Optional exact version; omit to use the latest published version.

**Returns:** registry, name, version + dependencies (npm: dependencies/dev/peer/optional; pypi: requires_dist[] + parsed dependencies map)

**Example request body:**
```json
{
  "registry": "npm",
  "name": "react"
}
```

### POST /packages/v1/downloads — 1 credit
download statistics (npm: period=last-day|week|month|year; pypi: recent day/week/month)

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `name` (string, required) — Exact package name (e.g. npm 'react', PyPI 'requests'). Scoped npm names like '@scope/pkg' are supported.
- `period` (enum, optional, default "last-month") — npm download window (rejects unknown values). Ignored for PyPI, which always returns recent last-day/last-week/last-month totals. [one of: last-day, last-week, last-month, last-year]

**Returns:** npm: downloads count for the period (+ start/end); pypi: last_day/last_week/last_month totals (source pypistats.org)

**Example request body:**
```json
{
  "registry": "npm",
  "name": "react",
  "period": "last-month"
}
```

### POST /packages/v1/search — 2 credits
search packages (npm: registry API; pypi: libraries.io→HTML→ranked simple-index+enrich)

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `query` (string, required) — Free-text search keywords matched against package name/description.
- `page` (integer, optional, default 1) — 1-based page number for paginated lists (versions / search).
- `page_size` (integer, optional, default 20) — Results per page (1-250, default 20). Larger values are clamped.
- `from` (integer, optional) — npm search only: raw result offset (alternative to page). Page forward with meta.next_from.

**Returns:** results[] (name, version, description, license, score, links/maintainers); meta has page, page_size, total/has_more, next_page/next_from, method

**Example request body:**
```json
{
  "registry": "npm",
  "query": "fastapi"
}
```

### POST /packages/v1/maintainer — 1 credit
maintainer/author records for a package

**Parameters:**
- `registry` (enum, required) — Which package registry to query. npm = Node.js packages; pypi = Python packages. (Synonyms node/nodejs -> npm, python/pip -> pypi.) [one of: npm, pypi, node, nodejs, python, pip]
- `name` (string, required) — Exact package name (e.g. npm 'react', PyPI 'requests'). Scoped npm names like '@scope/pkg' are supported.

**Returns:** maintainers[] (name/email) + author/publisher; pypi also author_email/maintainer_email

**Example request body:**
```json
{
  "registry": "pypi",
  "name": "requests"
}
```

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