Unpaywall API
Free Unpaywall API with no key: find legal open-access versions of paywalled papers by DOI, with direct PDF links and licence information. Tested example.
Endpoint tested and returned HTTP 200 on 2026-08-20
What is the Unpaywall API?
Unpaywall is a free, key-free API that finds legal open-access versions of scholarly articles by DOI, returning direct links to free full text along with the hosting repository, licence and version.
Unpaywall indexes open-access copies deposited in institutional repositories, preprint servers and publisher sites, then maps them to DOIs. Given a paywalled paper's DOI, it tells you whether a legal free version exists and where.
Crucially, everything it surfaces is legitimately deposited — this is not a shadow library. The `host_type` field distinguishes publisher-hosted open access from repository copies, and `version` tells you whether it is the published version or an author manuscript.
Quick facts
- Base URL
https://api.unpaywall.org/v2- Authentication
- No API key, but the `email` query parameter is mandatory on every request.
- Rate limit
- 100,000 requests per day.
- Pricing
- Free. Bulk users should use the data dump rather than the API.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the Unpaywall API
Every request below was executed against the live API on 2026-08-20, and the response shown is the real body it returned — not an illustration.
1. Find an open-access version by DOI
GET https://api.unpaywall.org/v2/10.1038/nature12373?email=contact@bytevancer.com
curl 'https://api.unpaywall.org/v2/10.1038/nature12373?email=contact@bytevancer.com'const res = await fetch("https://api.unpaywall.org/v2/10.1038/nature12373?email=contact@bytevancer.com");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://api.unpaywall.org/v2/10.1038/nature12373?email=contact@bytevancer.com", timeout=20)
res.raise_for_status()
print(res.json()){
"best_oa_location": {
"endpoint_id": null,
"evidence": "deprecated",
"host_type": "publisher",
"is_best": true,
"license": null,
"oa_date": "2013-07-30",
"pmh_id": null,
"repository_institution": null,
"updated": "deprecated",
"url": "https://www.nature.com/articles/nature12373.pdf",
"url_for_landing_page": "https://doi.org/10.1038/nature12373",
"url_for_pdf": "https://www.nature.com/articles/nature12373.pdf",
"version": "publishedVersion"
},
"data_standard": 2,
"doi": "10.1038/nature12373",
"doi_url": "https://doi.org/10.1038/nature12373",
"first_oa_location": {
"endpoint_id": null,
"evidence": "deprecated",
"host_type": "publisher",
"is_best": true,
"license": null,
"oa_date": "2013-07-30",
"pmh_id": null,
"repository_institution": null,
"updated": "deprecated",
"url": "https://www.nature.com/articles/nature12373.pdf",
"url_for_landing_page": "https://doi.org/10.1038/nature12373",
"url_for_pdf": "https://www.nature.com/articles/nature12373.pdf",
"version": "publishedVersion"
},
"genre": "journal-article",
"has_repository_copy": true,
"is_oa": true,
"is_paratext": false,
"journal_is_in_doaj": false,
"journal_is_oa": false,
"journal_issn_l": "0028-0836",
"journal_issns": "0028-0836,1476-4687",
"journal_name": "Nature",
"oa_locations": [
{
"endpoint_id": null,
"evidence": "deprecated",
"host_type": "publisher",
"is_best": true,
"license": null,
"oa_date": "2013-07-30",
"pmh_id": null,
"Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
<doi> | path | Required | The DOI to look up. 10.1038/nature12373 |
email | string | Required | Your email address. Mandatory — requests without it are rejected. you@example.com |
Response fields
is_oaboolean- Whether a free legal version exists.
best_oa_locationobject- The recommended free copy, or null.
best_oa_location.url_for_pdfstring- Direct PDF link where available.
best_oa_location.host_typestring- `publisher` or `repository`.
best_oa_location.versionstring- publishedVersion, acceptedVersion or submittedVersion.
oa_statusstring- gold, green, hybrid, bronze or closed.
journal_is_oaboolean- Whether the whole journal is open access.
What you can build with the Unpaywall API
- Add 'read free version' links to a literature database
- Check open-access compliance for institutional reporting
- Build a browser extension that surfaces free copies
- Analyse open-access rates across a research corpus
Common errors and how to fix them
422 without email
The email parameter is mandatory.
Fix: Always append &email=you@example.com — this is the most common failure.
404
The DOI is not in Unpaywall's index.
Fix: Coverage is broad but not universal, especially for very recent or non-journal works.
is_oa true but no PDF link
The free version is HTML-only or landing-page only.
Fix: Fall back to best_oa_location.url when url_for_pdf is null.
Unpaywall API — frequently asked questions
Is Unpaywall free and legal?
Yes on both counts. It is free with no API key, and it only indexes legitimately deposited open-access copies from publishers and institutional repositories — it is not a shadow library.
Why do my requests fail with a 422?
The `email` query parameter is mandatory on every request. Unpaywall uses it for contact and abuse prevention.
What do the oa_status colours mean?
gold means published in a fully open journal, green means a repository copy, hybrid means open within a subscription journal, bronze means free to read but without an open licence, and closed means no free version.
What is the difference between publishedVersion and acceptedVersion?
publishedVersion is the final typeset article; acceptedVersion is the peer-reviewed author manuscript before typesetting. Both are legitimate, but page numbers differ.
Tools that pair with this API
Unpaywall is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-20; always check the official documentation before relying on this API in production, as terms and limits can change.