Free REST JSON API for accessing papers (through Open Access, subscriptions, Interlibrary Loans, and emails to authors), finding metadata, and depositing papers.
Logging in isn’t required, but it gets you an API key, helps us tell funders how we’re doing, and lets us contact you with issues and updates.
Please limit your requests to one per second. We don’t enforce rate limits, but if we notice prolonged high usage, we may suspend your account and contact you about your needs.
If you’re looking to integrate us with your tools but aren’t able to code, our tools for librarians, especially integration guides, may be a better fit.
Support available at joe.mcarthur@oa.works.
Base URL of our API
curl -X GET "https://dev.api.cottagelabs.com/service/oab"
Returns a JSON status success message and 200 response code if the API is operational.
Gives URL to any Open Access paper.
Example: URL | DOI | Title | cURL
curl -X GET "https://dev.api.cottagelabs.com/service/oab/find?id=10.1126/science.196.4287.293"
Accepts a single parameter called "id", which should contain (in order of preference) a URL-encoded doi, pmc, pmid, url, title, or citation.
Tells you if an institution has access to a certain paper and provides a direct link
Requires both a paper ID and a specified institution to return a response. Accepts paper IDs as described in /find.
Institutions are specified by passing a code in "uid" obtained by logging in and setting up InstantILL with your details.
Finds as complete as possible metadata for any paper.
Accepts article information as described in /find.
curl -X POST "https://dev.api.cottagelabs.com/service/oab/metadata" -d '{"doi": "10.1126/science.196.4287.293"}' -H "Content-Type: application/json"
Accepts article information as described in /find as URL parameters or in a JSON body.
Create a request to the author to make a paper Open Access.
curl -X POST "https://dev.api.cottagelabs.com/service/oab/request" -d '{"doi": "10.1126/science.196.4287.293"}' -H "Content-Type: application/json"
Note: Many services opt to point users to our website using: https://openaccessbutton.org/request?doi=10.YOURDOI, allowing their users to sign up for our service, make requests, and receive notifications.
To start a request from your service, ensure you have signed up and completed your account information with what you’d like seen on a request.
Start by posting a JSON object containing at least a "doi" parameter. We will start a request for papers published in the past five years. If you’re unsure the item being requested is Open Access, use /find first to verify.
To be sent to an author, a request needs a justification. This can be provided in the "story" parameter. Our team manually moderates stories we haven’t seen before, but once we approve a story, we will automatically accept it so you can reuse stories.
When your request is successfully created, we will return an ID in a "_id" JSON parameter.
If you expect to generate more than ~100 requests per week regularly, that’s great; please contact us so we can ensure we plan adequate support such as moderation and quality checks.
Returns request metadata and status with the given ID.
Metadata fields returned are all optional, although DOI is always present in recent requests.
Find more about the permissions API here.
Accepts files to facilitate self-archiving papers in Zenodo.
curl -X POST "https://dev.api.cottagelabs.com/service/oab/deposit" -d '{"doi": "10.1126/science.196.4287.293", "url": "https://urltofileforupload.pdf"}' -H "Content-Type: application/json"
Include at least a DOI and a file, or a URL to a file. The file will be checked to ensure it’s the legal version (e.g postprint / submitted version) and deposited to Zenodo. We’ll pick up relevant metadata while checking, or you can pass your own.
You’ll get back a deposit object, you can view typical objects here.
Shows unique files deposited and their metadata for ingest into institutional repositories
Accepts "uid" as a parameter to filter results to your version of shareyourpaper.org.
Get a "uid" by logging in and setting up Shareyourpaper.org.
Add .csv to the end of the URL to get a CSV.
Show all deposits of any kind and their metadata
Accepts "uid" as a parameter to filter results to your version of shareyourpaper.org.
Get a "uid" by logging in and setting up Shareyourpaper.org.
Add .csv to the end of the URL to get a CSV.
Starts an ILL request by returning a link to a completed ILL form or sending an email.
curl -X POST "https://dev.api.cottagelabs.com/service/oab/ill" -d '{"doi": "10.1126/science.196.4287.293"}' -H "Content-Type: application/json"
Start a ILL by posting an paper ID as URL parameters or ideally in a JSON body. A list of accepted IDs can be found at /find. Include as much metadata as you can, under the list of parameters found in /metadata. We’ll enrich whatever you give us, or you can do it before by using /metadata directly.
We will then attempt to start an ILL according to your InstantILL configuration. By default, we will send an email to your account email, and you’ll need to pass the requestor’s email in the "email" parameter. If InstantILL is configured to do so, we can pass you a link to your completed ILL form.
Search ILLs made at your institution.
Most useful for custom integrations with InstantILL. This endpoint can be used to retrieve all activity from your embed(s) and then processed as you wish.
Queries are powered by Elasticsearch version 1.4.4. Knowledge of Elasticsearch will of course be helpful. In short, simple searches can be created by adding a URL parameter "q" and providing values you’d like to match.
A well-formed query for an InstantILL instance and the response format is demonstrated in the example. Any values you see can be queried. Don’t always expect all fields to be present.
