---
name: unpaywall-api-d8a7dffc83c7
description: "Find free legal full-text versions of scholarly articles via Unpaywall"
metadata:
  openclaw:
    emoji: "🔍"
    category: "literature"
    subcategory: "fulltext"
    keywords: ["full-text retrieval", "open access", "journal copyright policy", "self-archiving"]
    source: "https://unpaywall.org/products/api"
    requires:
      env: ["UNPAYWALL_EMAIL"]
---

# Unpaywall API Guide

## Overview

Unpaywall is a free, open database of over 40 million free scholarly articles. Built by the nonprofit OurResearch, Unpaywall indexes legal open access (OA) copies of papers from thousands of institutional repositories, preprint servers, publisher websites, and government archives. It is the most comprehensive source for finding freely available versions of paywalled academic literature.

Researchers, librarians, and tool developers use Unpaywall to locate open access copies of papers they need, assess the OA status of publications, and integrate OA discovery into their workflows. The database is updated daily, scanning repositories and publisher sites for new open access content. Unpaywall categorizes OA into types: gold (published OA), green (repository copy), hybrid (OA in subscription journal), and bronze (free to read on publisher site).

The API requires only an email address for authentication and is free for non-commercial use with a generous rate limit of 100,000 requests per day.

## Authentication

Authentication is via email address passed as a query parameter. No API key or registration is needed -- just provide a valid email:

```
?email=your@email.com
```

This email is used for contact purposes only and to identify your application. The API will reject requests without a valid email address. For commercial use or higher rate limits, contact OurResearch for an API key.

## Core Endpoints

### DOI Lookup: Find Open Access for a Paper

- **URL**: `GET https://api.unpaywall.org/v2/{doi}`
- **Parameters**:
  | Param | Type | Required | Description |
  |-------|------|----------|-------------|
  | doi | string | Yes | The DOI of the paper (URL-encoded in path) |
  | email | string | Yes | Your email address |
- **Example**:
  ```bash
  curl "https://api.unpaywall.org/v2/10.1038/nature12373?email=user@example.com"
  ```
- **Response**: JSON with comprehensive OA information:
  - `is_oa`: boolean indicating if any OA version exists
  - `best_oa_location`: the best available OA copy with `url`, `url_for_pdf`, `evidence`, `host_type`, `license`, and `version`
  - `oa_locations`: array of all known OA copies
  - `oa_status`: gold, green, hybrid, bronze, or closed
  - `title`, `doi`, `year`, `genre`, `journal_name`, `publisher`

### Batch DOI Lookup: Multiple Papers

- **URL**: `GET https://api.unpaywall.org/v2/{doi}` (repeated per DOI)
- **Parameters**:
  | Param | Type | Required | Description |
  |-------|------|----------|-------------|
  | doi | string | Yes | One DOI per request (batch via multiple requests) |
  | email | string | Yes | Your email address |
- **Example**:
  ```bash
  # Process multiple DOIs sequentially
  for doi in "10.1038/nature12373" "10.1126/science.aaa8685" "10.1016/j.cell.2015.05.002"; do
    curl -s "https://api.unpaywall.org/v2/$doi?email=user@example.com" | jq '{doi: .doi, is_oa: .is_oa, oa_status: .oa_status, best_url: .best_oa_location.url}'
    sleep 0.01
  done
  ```
- **Response**: Same JSON structure as single lookup, for each DOI.

### Data Feed: Bulk Access

For large-scale analyses, Unpaywall provides a complete database snapshot and a weekly data feed, rather than requiring millions of individual API calls. Access is available at https://unpaywall.org/products/data-feed for registered users.

## Rate Limits

The API allows 100,000 requests per day (approximately 1.15 requests per second sustained). There is no strict per-second rate limit, so burst traffic is acceptable as long as the daily cap is respected. Exceeding the limit returns HTTP 429. For analyses requiring more than 100K lookups, use the Unpaywall Data Feed (database snapshot) instead.

## Common Patterns

### Check OA Status for a Reading List

Determine which papers in your reading list have freely available versions:

```bash
curl -s "https://api.unpaywall.org/v2/10.1038/s41586-021-03819-2?email=user@example.com" | jq '{title: .title, is_oa: .is_oa, oa_status: .oa_status, pdf: .best_oa_location.url_for_pdf}'
```

### Find the Best Available PDF

Get a direct link to the best open access PDF for a paper:

```bash
curl -s "https://api.unpaywall.org/v2/10.1145/3292500.3330672?email=user@example.com" | jq '.best_oa_location | {url: .url, pdf: .url_for_pdf, version: .version, license: .license}'
```

### Audit Open Access Compliance for a Grant

Check whether publications from a funded project comply with OA mandates:

```bash
# For each publication DOI from the grant
curl -s "https://api.unpaywall.org/v2/10.1038/nature12373?email=user@example.com" | jq '{doi: .doi, title: .title, is_oa: .is_oa, oa_status: .oa_status, locations: [.oa_locations[] | {host: .host_type, license: .license, version: .version}]}'
```

## References

- Official documentation: https://unpaywall.org/products/api
- Unpaywall data format: https://unpaywall.org/data-format
- OurResearch: https://ourresearch.org/


---
Source attribution: wentorai
Original project: https://github.com/wentorai/research-plugins/blob/bf44b3cd617fa94c8a1b254c5d1987142ca3d631/skills/literature/fulltext/unpaywall-api/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 Wentor AI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: wentorai
Original project: https://github.com/wentorai/research-plugins/blob/bf44b3cd617fa94c8a1b254c5d1987142ca3d631/skills/literature/fulltext/unpaywall-api/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Education & Research
Roles: Data Scientist, Researcher
Specialties: API
Tools: Unpaywall
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 79dd1c14d70b732629abd1556738b1445e166199472733d1b56bcd9461b04c00