# NCBI — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and retrieve biomedical literature from NCBI databases including PubMed, PubMed Central, and MeSH. Supports full-text extraction, metadata lookup, and research filtering.

**Category:** Healthcare | **Website:** [ncbi.nlm.nih.gov/](https://ncbi.nlm.nih.gov/) | **Docs:** [parse.bot/marketplace/b9df61a7-f583-4b25-b30e-9e4b1dbc543a/ncbi-nlm-nih-gov-api](https://parse.bot/marketplace/b9df61a7-f583-4b25-b30e-9e4b1dbc543a/ncbi-nlm-nih-gov-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/ncbi/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Mesh get term

Retrieve full details for a specific MeSH descriptor by its numeric ID (as returned by mesh_search). Returns the preferred term name, scope note, MeSH tree classification numbers, and entry terms.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `term_id` | string | Yes | Numeric MeSH term ID from mesh_search results (e.g. 68003920). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/ncbi/mesh-get-term \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"term_id":"<string>"}'
```

### Mesh search

Search the MeSH (Medical Subject Headings) vocabulary for terms matching a query. Returns matching descriptors with unique identifiers, definitions, and entry terms (synonyms). Each result carries a numeric ID usable with mesh_get_term for tree classification.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search term to find in MeSH database. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/ncbi/mesh-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Pmc get article

Retrieve full text and structured sections for a PMC article by its PMCID. Extracts labeled sections (methods, results, conclusions, limitations) when present. For publisher-restricted articles, returns the abstract as full_text. Truncates full_text at 20000 characters.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pmcid` | string | Yes | PubMed Central ID (e.g. PMC9516129). Accepts with or without the PMC prefix. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/ncbi/pmc-get-article \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"pmcid":"<string>"}'
```

### Pubmed get article

Retrieve full bibliographic metadata for a single PubMed article by its PMID. Returns authors with affiliations, structured journal info, full abstract, MeSH headings, and keywords. One network round-trip per article.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pmid` | string | Yes | PubMed ID (e.g. 35771962). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/ncbi/pubmed-get-article \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"pmid":"<string>"}'
```

### Pubmed search

Full-text search across all PubMed articles. Supports filters for date range, article type, and text availability. Returns paginated article summaries (title, authors, journal, identifiers). Pagination is offset-based via retstart/retmax. Each result carries a PMID usable with pubmed_get_article for full metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_type` | string | No | Article type filter (e.g. Review, Clinical Trial, Meta-Analysis, Randomized Controlled Trial). |
| `date_range` | string | No | Filter by publication date range. |
| `query` | string | Yes | Search query string for PubMed. |
| `retmax` | integer | No | Maximum number of results to return per request. |
| `retstart` | integer | No | Result offset for pagination (0-based). |
| `sort` | string | No | Sort order for results. |
| `text_availability` | string | No | Filter by text availability. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/ncbi/pubmed-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"article_type":"<string>","date_range":"<string>","query":"<string>","retmax":"<integer>","retstart":"<integer>","sort":"<string>","text_availability":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.