Find legally available free versions of paywalled papers using a DOI, the paper's identifier. Unpaywall provides access links and manuscript versions, helping retrieve PDFs and record where each accessible copy came from.
Use Unpaywall API to find free full-text versions of paywalled papers
Run score Not tested
See how to installReview the instructions the agent will receive before you install.
Use Unpaywall to find legally available open access versions of papers that appear to be behind paywalls.
Core principle: Many paywalled papers have free versions (preprints, author manuscripts, institutional repositories). Unpaywall finds them.
Use this skill when:
Use BEFORE giving up on full text access
Simple REST API - no authentication required for reasonable usage
curl "https://api.unpaywall.org/v2/DOI?email=YOUR_EMAIL"
Parameters:
DOI - The paper's DOI (URL-encoded if needed)email - User's email (required, for courtesy/contact)IMPORTANT: Ask user for their email at the start of research session. Do NOT use placeholder emails like claude@anthropic.com or researcher@example.com.
Example:
curl "https://api.unpaywall.org/v2/10.1038/nature12373?email=user@example.com"
{
"doi": "10.1038/nature12373",
"title": "Paper Title",
"is_oa": true,
"best_oa_location": {
"url": "https://europepmc.org/articles/pmc3858213",
"url_for_pdf": "https://europepmc.org/articles/pmc3858213?pdf=render",
"version": "publishedVersion",
"license": "cc-by",
"host_type": "repository"
},
"oa_locations": [
{
"url": "https://europepmc.org/articles/pmc3858213",
"version": "publishedVersion"
},
{
"url": "https://arxiv.org/abs/1234.5678",
"version": "submittedVersion"
}
]
}
is_oa (boolean)
true - Open access version availablefalse - No free version foundbest_oa_location (object or null)
oa_locations (array)
version types:
publishedVersion - Final published version (best)acceptedVersion - Author's accepted manuscript (good)submittedVersion - Preprint before peer review (useful)# Try DOI first
curl -L "https://doi.org/10.1234/example.2023"
# If paywall detected (403, subscription required, etc):
curl "https://api.unpaywall.org/v2/10.1234/example.2023?email=your@email.com"
# Parse JSON response
response=$(curl -s "https://api.unpaywall.org/v2/DOI?email=EMAIL")
# Check if OA available
is_oa=$(echo $response | jq -r '.is_oa')
if [ "$is_oa" = "true" ]; then
# Get best PDF URL
pdf_url=$(echo $response | jq -r '.best_oa_location.url_for_pdf // .best_oa_location.url')
# Download
curl -L -o "papers/paper.pdf" "$pdf_url"
fi
When OA found:
⚠️ Paper behind paywall at publisher
✓ Found open access version via Unpaywall!
Source: Europe PMC (published version)
PDF: https://europepmc.org/articles/pmc3858213?pdf=render
→ Downloading...
When no OA found:
⚠️ Paper behind paywall at publisher
✗ No open access version found via Unpaywall
Options:
- Request via institutional access
- Contact authors for preprint
- Continue with abstract only
If multiple locations available:
Priority order:
publishedVersion from publisher or PMCacceptedVersion from institutional repositorysubmittedVersion from preprint server (arXiv, bioRxiv)Add to full text fetching workflow:
Stage 2: Fetch Full Text
Try in order:
A. PubMed Central (free full text)
B. DOI resolution → If paywall, try Unpaywall
C. Unpaywall direct lookup
D. Preprints (bioRxiv, arXiv)
Updated workflow:
# 1. Try PMC
pmc_result=$(curl "https://eutils.ncbi.nlm.nih.gov/...")
if has_pmc_fulltext; then
fetch_pmc
exit 0
fi
# 2. Try DOI
doi_result=$(curl -L "https://doi.org/$doi")
if is_paywall; then
# 3. Try Unpaywall
unpaywall_result=$(curl "https://api.unpaywall.org/v2/$doi?email=$EMAIL")
if has_oa; then
fetch_unpaywall_pdf
exit 0
fi
fi
# 4. No full text available
report_no_fulltext
Free tier (with email):
Best practices:
import requests
import time
def find_open_access(doi, email):
"""
Find open access version via Unpaywall
Returns: (pdf_url, version, source) or (None, None, None)
"""
url = f"https://api.unpaywall.org/v2/{doi}"
params = {"email": email}
try:
response = requests.get(url, params=params, timeout=10)
response.raise_for_status()
data = response.json()
if not data.get('is_oa'):
return None, None, None
best_loc = data.get('best_oa_location')
if not best_loc:
return None, None, None
pdf_url = best_loc.get('url_for_pdf') or best_loc.get('url')
version = best_loc.get('version', 'unknown')
source = best_loc.get('host_type', 'unknown')
return pdf_url, version, source
except Exception as e:
print(f"Error checking Unpaywall for {doi}: {e}")
return None, None, None
# Usage
doi = "10.1038/nature12373"
pdf_url, version, source = find_open_access(doi, "researcher@example.com")
if pdf_url:
print(f"Found {version} at {source}")
print(f"PDF: {pdf_url}")
# Download PDF
response = requests.get(pdf_url)
with open(f'papers/{doi.replace("/", "_")}.pdf', 'wb') as f:
f.write(response.content)
else:
print("No open access version found")
time.sleep(0.1) # Rate limiting
Repositories:
Preprint servers:
Publisher sites:
DOI not found:
{
"error": "true",
"message": "DOI not found"
}
→ Check DOI format, try alternative identifiers
Network errors:
Malformed response:
is_oa fieldoa_locations array if best_oa_location missing| Task | Command |
|---|---|
| Check if OA available | curl "https://api.unpaywall.org/v2/DOI?email=EMAIL" |
| Get best PDF URL | Parse .best_oa_location.url_for_pdf |
| List all OA sources | Parse .oa_locations[] |
| Check version type | Look at .version field |
| Download PDF | curl -L -o paper.pdf "$pdf_url" |
Called by:
evaluating-paper-relevance - When full text not in PMCanswering-research-questions - For highly relevant papersUpdates:
papers-reviewed.json - Note if OA foundSUMMARY.md - Include OA source infoUsing placeholder email: Using claude@anthropic.com or researcher@example.com → Ask user for their real email
Not including email: Required parameter, requests will fail
Checking every paper: Only check when needed (score ≥7, no PMC)
Ignoring version type: Published version better than preprint
Single source only: Check oa_locations array for alternatives
No rate limiting: Add delays even though no hard limit
Successful when:
After finding OA version:
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Turn a broad research idea into clear, testable questions. Compare familiar and less conventional approaches, structure the selected question around its population and methods, and assess variables, feasibility, and potential theoretical contributions.
Helps build a research framework by comparing theories, mapping relationships between variables, and deriving testable hypotheses. Explores less conventional options, examines weaknesses and competing explanations, and produces diagrams with anticipated reviewer objections.
Clarify the philosophical assumptions behind a research project and check whether they fit the proposed methods. Get a reasoned research stance, draft proposal wording, and guidance for explaining how the researcher's background and values shape the study.
Plan and draft academic papers through specialized agent roles covering literature, arguments, citations, and review. Get chapter guidance, revision roadmaps, Traditional Chinese and English abstracts, and documents formatted as LaTeX, DOCX, PDF, or Markdown.
Turn a detailed outline into a philosophy or interdisciplinary manuscript. Draft chapters with repeated quality reviews, check terminology and arguments across sections, and prepare the manuscript, evaluation reports, abstract, and metadata for submission.
Simulate academic peer review through five reviewer roles tailored to the paper's field. Receive separate critiques, an editorial decision, and a prioritized revision roadmap, or check whether a revised manuscript addresses earlier comments.