Read a research paper API

Endpoint facts

Method

POST

API path

/research/papers/read

Auth

apiKey

Credits

1 credit metadata-only · 5 full text

Charged on

Successful 2xx responses only

Platform

Research

Request body schema

#/definitions/researchpapers.PaperReadRequest

How this endpoint behaves

Read licensed Europe PMC body prose and question-ranked passages, with an x-api-key. PMID, PMCID and DOI resolution covers Europe PMC's supported MED records and their PMC full text; this is not universal scholarly coverage. Explicit arXiv identifiers retain metadata-only behavior.

Request body:

• paper_id: required, up to 4096 characters; a namespaced identifier (pmid:17299597, pmcid:PMC1790863, doi:10.1371/journal.pone.0000217, arxiv:1706.03762), supported source URL, or registered canonical paper: ID.
• question: required, 1–2000 characters. Deterministic lexical ranking selects body passages; no model-generated answer is returned. With no informative overlap, earliest body passages are returned with zero relevance score.
• limit: optional passage cap, 1–10, default 4.

Response behavior:

full_text_available=true includes full_text.text (at most 1 MiB of normalized body prose), item-level license_url, original license/copyright notices, attribution, source_url, retrieved_at, and a SHA-256 digest of the exact normalized UTF-8 text. Paragraph whitespace is normalized. Figures, tables, bibliography and sub-articles are excluded, as stated in the extraction note. Up to ten passages have byte offsets into this exact text and stable content-derived identifiers. Oversized or malformed source payloads fail rather than silently claiming a complete clipped text.

The initial license policy accepts only CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) and CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/). Other, absent or conflicting licenses return metadata-only restricted; inaccessible/non-indexed bodies are explicit availability outcomes. Upstream failures return 503, not fabricated empty passages.

Billing: successful full-text extraction costs 5 credits; metadata-only reads cost 1; failed requests cost zero. Precheck requires at most 5 credits and preserves a 1-credit gate for explicit arXiv identifiers. usage.credits_charged contains the actual finalized receipt; pending settlement is explicit. No cache discount is claimed for an uncached source read.

Response enum values:

• paper.identifiers[].namespace: arxiv, doi, pmid, pmcid.
• paper.content_level: metadata, abstract, full_text.
• unavailable_reason: not_indexed, restricted, unsupported_format, not_found.
• coverage[].status: ok, failed, not_indexed, unsupported.
• coverage[].failure.reason: invalid_url, unsupported_content_type, blocked, not_found, rate_limited, timeout, upstream_error, internal_error, out_of_scope, robots_disallowed, duplicate, limit_reached, unsupported_filter, unknown_source, idempotency_conflict, invalid_cursor, result_expired, full_text_unavailable, budget_exhausted.
• warnings[].code: source_failed, source_not_indexed, discovery_truncated, ranking_window_limit, imprecise_date_excluded, content_unavailable, cached_source_stale.

Example request:

{"paper_id":"pmcid:PMC1790863","question":"phenotypic complexity","limit":1}

Example response (text and metadata abbreviated):

{
  "code": 200,
  "msg": "OK",
  "data": {
    "paper": {"paper_id":"paper:8e50eecc-636b-40f9-a6a1-df0e66862dd1","primary_id":"europepmc:MED:17299597","content_level":"full_text"},
    "full_text_available": true,
    "full_text": {
      "text": "Body prose…",
      "license_url": "https://creativecommons.org/licenses/by/4.0/",
      "source_url": "https://www.ebi.ac.uk/europepmc/webservices/rest/PMC1790863/fullTextXML",
      "copyright": "Retained article copyright statement",
      "attribution": "Retained author and article attribution"
    },
    "passages": [{"passage_id":"content-derived-id","text":"Body prose…","locator":{"start_byte":0,"end_byte":13}}],
    "coverage": [{"source_id":"europepmc","status":"ok"}],
    "warnings": [],
    "usage": {"credits_charged":5,"settlement_pending":false}
  }
}

Returned europepmc:MED:<id> / europepmc:PMC:<pmcid> primary IDs and public https://europepmc.org/article/MED/<id> / article/PMC/<id> URLs can be reused as paper identifiers. Other Europe PMC source codes are outside this resolver.

Sampled response

Request, 14 Oct 2026

POST /research/papers/read

Items in paper.authors

4

Fields filled in every checked item

1

Shared guides

Related