Integrating with PREreview's API

PREreview provides a RESTful API documented using the OpenAPI v3.0 standard. Using this API and simple web requests, users have access to all of the same data and functionality as is exposed by the PREreview.org website. A basic overview of the API's functionality is provided below (with examples using the common open-source command-line utility cURL), while the OpenAPI specification is available in JSON format is available here and detailed, automatically generated documentation of all available endpoints and methods is available here.

General

The current version of the PREreview API is accessible at https://prereview.org/api/v2. The API both accepts and returns JSON by default, so any interactions with the API should specify the Accept: application/json and Content-Type: application/json headers. All objects in the API are uniquely identified via a Universally Unique Identifier (UUID) string, specified by that object's uuid property. Additionally, users can optionally also be discovered via their orcid property, containing that user's associated ORCiD, and preprints can optionally be discovered via their handle property, containing a URI string describing them uniquely via an external unique identifier such as a DOI (for example, a preprint with the DOI '10.0000/1111.22' would have a handle of doi:10.0000-1111.22).

API Keys

Much of the API is available publicly in a read-only fashion. However, in order to access the restricted parts of the API or add and edit data on the site, you'll need to authenticate your requests using an API key. After you've logged in to the site using your ORCiD, you can click on your user icon on the upper right to access the user menu and click 'API Settings' to manage your API keys. API keys have an arbitrary name (specified by the user to help them remember which key they're using for which purpose) and a random secret generated by the site. You can specify the API key name and secret with a request using the headers X-API-App and X-API-Key respectively. For example, to POST to a particular endpoint that requires authentication using the API key named 'TEST' with the secret '5555-5555-5555':

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "X-API-App: TEST" -H "X-API-Key: 5555-5555-5555" https://prereview.org/api/v2/examples

API keys have the same access permissions as the user account they're associated with. If you need an API key with special or elevated privileges, contact engineering@prereview.org.

Overview of Data Types

The PREreview API is organized into a number of different types representing different kinds of data provided by the platform and the relationships between those pieces of data. In true RESTful style, those datatypes can be manipulated via standard HTTP verbs POST, GET, PUT, and DELETE to perform the standard create, read, update, delete (CRUD) operations on that data. The data itself is available at URLs under the /api path on prereview.org. PREreview has many additional data types other than the ones below, but these are the most important ones for the purposes of interacting with the platform.

Preprint

A 'preprint' object represents a particular preprint that has been added to the system for review. Because PREreview is not itself a preprint server, it does not maintain all of the information from a particular preprint nor serve as the canonical source for a particular preprint. PREreview relies on external metadata sources such as doi.org (for preprints that have a DOI), arXiv.org (for preprints with an arXivId), CrossRef, and Google Scholar to gather information about a given preprint. This data (where available) includes the title, abstract, authors, host publication, publication date, license, URL, and a link to a PDF of the full preprint. It's not possible for an API user to submit this data manually; a preprint is requested by DOI or arXivId and then resolved from the above sources. The preprint object also contains the relationships to the requests, reviews, and other PREreview objects associated with the given preprint.

To fetch the first 10 preprints from the platform:

curl -X GET -H "Accept: application/json" -H "Content-Type: application/json" https://prereview.org/api/v2/preprints?limit=10

To add a preprint with the DOI '10.1111/2222.33' to the platform (it won't show up on the front page until it's been reviewed or someone has requested a review):

curl -X GET -H "Accept: application/json" -H "Content-Type: application/json" https://prereview.org/api/v2/resolve?identifier=10.1111/2222.33

To fetch a single preprint with the DOI '10.1111/2222.33':

curl -X GET -H "Accept: application/json" -H "Content-Type: application/json" https://prereview.org/api/v2/preprints/doi-10.1111-2222.33

For the full range of methods available for preprints, and all of the supported query parameters, see the detailed API documentation.

Request

A 'request' object represents a particular user requesting that other users review this preprint.

To request a review for a particular preprint with a DOI of '10.1111/2222.33' (note that this requires authentication, see API Keys above):

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "X-API-App: TEST" -H "X-API-Key: 5555-5555-5555" https://prereview.org/api/v2/preprints/doi-10.1111-2222.33/requests

For the full range of methods available for requests, and all of the supported query parameters, see the detailed API documentation.

Rapid Review

A 'rapid review' is a short, structured survey-style review of a particular preprint. It is meant to provide a brief assessment of a particular preprint by a reviewer, optionally followed by a more in-depth long-form review.

To fetch the rapid reviews for a particular preprint with a DOI of '10.1111/2222.33':

curl -X GET -H "Accept: application/json" -H "Content-Type: application/json" https://prereview.org/api/v2/preprints/doi-10.1111-2222.33/rapid-reviews

To post a rapid review of the same preprint (note that this requires authentication, see API Keys above):

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "X-API-App: TEST" -H "X-API-Key: 5555-5555-5555" -d '{ "ynNovel": "yes", "ynFuture": "yes", "ynReproducibility": "no", "ynMethod": "N/A", "ynCoherent": "unsure", "ynLimitations": "yes", "ynEthics": "no", "ynNewData": "yes", "ynRecommend": "yes", "ynPeerReview": "no", "ynAvailableCode": "N/A", "ynAvailableData": "no" }' https://prereview.org/api/v2/preprints/doi-10.1111-2222.33/rapid-reviews

For the full range of methods available for rapid reviews, and all of the supported query parameters, see the detailed API documentation.

Full Review

A 'full review' or long-form review is a longer, free-form review of a preprint. It is meant to be a more in-depth assessment of a particular preprint. The platform maintains multiple drafts of a given full review up until publication, and then displays the most recent draft.

To fetch the full reviews for a particular preprint with a DOI of '10.1111/2222.33':

curl -X GET -H "Accept: application/json" -H "Content-Type: application/json" https://prereview.org/api/v2/preprints/doi-10.1111-2222.33/full-reviews

To post a full review of the same preprint (note that this requires authentication, see API Keys above):

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "X-API-App: TEST" -H "X-API-Key: 5555-5555-5555" -d '{ "preprint": "doi:10.1111/2222.33", "contents": "This is the contents of this full review" }' https://prereview.org/api/v2/full-reviews

For the full range of methods available for full reviews, and all of the supported query parameters, see the detailed API documentation.

Contributing to PREreview's Development

PREreview is an open-source web application available under the MIT License. In order to contribute to the development of the software, visit our Github repository.