Scholarly Logo Hello and welcome to the Scholarly API documentation. This site will provide an overview of how to interact with the Scholarly API. Using the Scholarly API is a great way to programmatically read or write data to your institution’s Scholarly instance. The Scholarly API is an HTTPS API, which adheres to the JSON:API specification. This is a RESTful specification that optimizes for consistency across accessing different resources.

​
Authentication

The Scholarly API is authenticated using an API Key attached to a User record within Scholarly. Using this API Key confers all permissions associated with that user. Most of the time, these API Keys will be attached to service accounts with the “institution admin” permission. If you have questions or concerns, please reach out to your Scholarly rep. This API Key will always begin with sch_. Include this API Key in the Authorization header with the Bearer prefix. Here’s an example in curl: 
curl https://api.scholarlysoftware.com/api/v1/institutions \
  -H "Authorization: Bearer sch_facebeef..." \
  -H "Accept: application/vnd.api+json"
This will list all institutions your users has access to.

​
Rate Limiting

The Scholarly API defaults to 1 request per second per institution, unless otherwise negotiated within your contract. When the rate limit is exceeded, Scholarly will respond with 429 Too Many Requests. We encourage you to handle these rate limits gracefully.

​
Versioning

The Scholarly API practices Semantic Versioning 2.0.0 by encoding the major version in the path component, i.e. /v1. This means that any breaking changes will necessitate a bump in the version number. As a client, you can expect to never see breaking changes within the same version of the API. Scholarly classifies changes or removal of existing attribute or relationship behavior as breaking changes. Adding attributes or relationships to existing objects is not considered a breaking change. You may see payloads grow over time.

​
IDs

All resources within the Scholarly API will be identified by a UUID represented as a string.

​
Read-on-write Consistency

To ensure a performant experience for all customers and users, Scholarly employs the use of database replicas for serving read traffic in many situations. All GET requests in the Scholarly API will be served from a read replica. As a result, GET requests may experience replica lag leading to slightly stale data. Requests that write, i.e PATCH, POST, and DELETE, ensure read-on-write consistency. All endpoints will return the most up-to-date copy of the data. Let’s take a look at a few examples: 
# A single request that writes will receive the latest
# data in its response
POST /institutions/{id}/departments # Receives a consistent copy

# Compared with a write and then a read

POST /institutions/{id}/departments # and then...
GET /departments/{new_id} # May or may not receive the latest copy of data
The on-call Scholarly engineer gets paged if replica lag exceeds a certain threshold, but will be not respond to replica lag of a few seconds. Please design you API interactions with this read-on-write consistency in mind!

​
AI-Native

Scholarly’s API docs are written to work well with large language models (LLMs) to make it easier to put together integration code. Click the “Copy page” button above to see the different options for working with Claude, ChatGPT, and more. In our experience, these LLMs do a great job of putting together the first draft of code to implement against Scholarly regardless of the programming language.

​
Not Seeing a Resource?

If you’re not seeing a resource that you need to successfully integrate with Scholarly, please reach out to your rep. We can get the necessary endpoints created.