API

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.

https://dev.api.cottagelabs.com/service/oab

Base URL of our API


GET

Examples: URL | cURL

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.

/find

Gives URL to any Open Access paper.


GET

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.

/subscription

Tells you if an institution has access to a certain paper and provides a direct link


GET

Example

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.

/metadata

Finds as complete as possible metadata for any paper.


GET

Example

Accepts article information as described in /find.

POST

Example

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.

/request

Create a request to the author to make a paper Open Access.


POST

Example

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.

/request/:id

Returns request metadata and status with the given ID.


GET

Example

Metadata fields returned are all optional, although DOI is always present in recent requests.

/permissions/:doi [coming soon]

Find more about the permissions API here.

/deposit

Accepts files to facilitate self-archiving papers in Zenodo.


POST

Example

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.

/deposited

Shows unique files deposited and their metadata for ingest into institutional repositories


GET.

Example: [JSON] [CSV]

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.

/deposits

Show all deposits of any kind and their metadata


GET.

Example: [JSON] [CSV]

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.

/ill

Starts an ILL request by returning a link to a completed ILL form or sending an email.


POST

Example

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.

/ills

Search ILLs made at your institution.


GET. Authorization required.

Example

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.


Haven’t found what you want? Get in touch. Only the most commonly required endpoints are included for brevity.