Skip to main content
Scholarly’s API is an implementation of the JSON:API specification. One of the optional parts of this specification is Inclusion of Related Resources via the ?include query parameter. Scholarly implements this parameter on all GET endpoints. Bringing in these related resources is a great way to make fewer requests against the Scholarly API while still accomplishing your goal. Rather than needing to issue 1 request to fetch a list of users, and then N requests for their attached profiles, API clients are able to pull all of that down in one request. These extra records are written to the top-level included JSON key. Here’s an example response to the GET /api/v1/users?include=profile endpoint: 
{
  "data": [
    /* Users data found here */
  ],
  "included": [
    /* Profile data found here */
  ]
}

​
Limitations

To prevent runaway queries, Scholarly limits all ?include parameters to a depth of 2. Any request specifying more than that will receive a 400 Bad Request. Note, a depth of 2 means the ?include parameter will have at most 1 period (.). Here are a few examples: 
# 200 OK
GET /api/v1/users?include=profile
GET /api/v1/users?include=profile.current_primary_appointment

# 400 Bad Request
GET /api/v1/users?include=profile.current_primary_appointment.rank
There is no limit to the number of 1- and 2-level relationships you can request: 
# 200 OK
GET /api/v1/users?include=profile,addresses,phone_numbers