Skip to main content
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!

​
Pagination

The Scholarly API uses pagination to efficiently handle large datasets. All collection endpoints support pagination following the JSON:API pagination specification. To ensure consistent performance regardless of how deep in a list the query might be reaching, the Scholarly API implements cursor-based pagination. Rather than using a “limit + offset”, you will set the page size and then be returned a cursor in the links.next attribute of the response.

​
Request Parameters

Pagination is controlled using the following query parameters:
  • page[size] - The number of items per page (default: 25, minimum: 1, maximum: 100)

​
Example Requests

# Get the first page with default page size (25 items)
GET /api/v1/departments

# Inspect the response from above, pull out the `links.next` attribute. Get the next page
GET /api/v1/departments?page[after]=...&page[size]=30

​
Page Size Limits

To ensure optimal performance:
  • Default page size: 25 items
  • Minimum page size: 1 item
  • Maximum page size: 100 items
If you request a page size greater than 100, it will be automatically clamped to 100.

​
Response Metadata

Paginated responses include metadata about the collection in the meta field: 
{
  "data": [...],
  "meta": {
    "total": 250  // Total number of items in the collection
    // Additional pagination metadata
  },
  "links": {
    // JSON:API pagination links when applicable
  }
}

​
Best Practices

  1. Start with reasonable page sizes: Use the default of 25 items unless you have specific requirements
  2. Handle empty results: When iterating through pages, stop when you receive an empty data array
  3. Respect rate limits: Pagination doesn’t exempt you from rate limiting - space out your requests appropriately
  4. Use filters when possible: Combine pagination with filtering to reduce the total number of pages needed

​
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.
⌘I