Pearson
Always Learning

This API allows you to retrieve the gradebook structure (the full list of gradable items) and make some updates to the details for gradable items.

A gradable item is the combination of a category and a unit (e.g., "grade for participation during Unit 3"). There are two types of categories: default and custom. Default category names are taken from the names of the content items in the course and custom category names are arbitrary strings created either through the User Interface or the API. Gradable Items for default categories can only be created through the User Interface; custom gradable items can be created either in the UI or the API.

Best Practice: This API provides a general structure of the gradebook's gradable items. There may be student-specific differences, however, so when retrieving a student's gradebook for display you should use the user-specific counterpart.

Custom Items and Gradable Items

The Custom Items API and this API are essentially two perspectives of the same object. Custom Items are returned as objects by this API, and you can use the Custom Item GUID as the Gradable Item GUID in this API to retrieve the gradable item details for a custom item.



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 1.0a, OAuth 2.0
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Student, Administrator
Note: Student roles can only use GET requests.

API Request

API Endpoints

HTTP Verbs and URIs

GET /courses/{courseId}/gradebook/gradebookItems{.format}
GET /courses/{courseId}/gradebookItems{.format}
  • Retrieve all gradable items in a course's gradebook.
  • These endpoints are synonymous.
GET /courses/{courseId}/gradebook/gradebookItems/{gradableItemGuid}{.format}
GET /courses/{courseId}/gradebookItems/{gradableItemGuid}{.format}
  • Retrieve a single gradable item.
  • These endpoints are synonymous.
PUT /courses/{courseId}/gradebook/gradebookItems/{gradableItemGuid}{.format}
PUT /courses/{courseId}/gradebookItems/{gradableItemGuid}{.format}
  • Update a gradable item with new configuration details.
  • These endpoints are synonymous.

Parameters

Parameter Description Valid Values
{courseId} LearningStudio Course ID or relevant course overload.
  • Numeric ID issued by LearningStudio
  • ccn={callNumber}
{gradableItemGuid} LearningStudio Gradable Item GUID (or a custom item GUID, which is the same value). Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio. String GUID issued by LearningStudio
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Query String Parameters

No query string parameters are supported.

Request Body

When updating gradable items, there is a different payload format depending on whether the gradable item is for a default category or a custom category.

For GET and DELETE Requests

None

For PUT Requests to Default Category Gradable Items

{
  "gradebookItem":{
    "isIncludedInGrade":{isIncludedInGradeFlag},
    "isExtraCredit":{isExtraCreditFlag},
    "pointsPossible":{pointsPossible}
  }
}

For PUT Requests to Custom Gradable Items

{
    "customItem": {
        "isIncludedInGrade": {isIncludedInGradeFlag},
        "isExtraCredit": {isExtraCreditFlag},
        "pointsPossible": {pointsPossible}
    }
}

Property Descriptions

Name Description Valid Values
{isIncludedInGradeFlag} Designates whether the grades entered in this item affect the course total grade.
  • true
  • false
{isExtraCreditFlag} Designates whether the grades entered in this item are counted as extra credit. If it's extra credit, the points awarded here increase the student's achieved points but the points possible value is not added to the course's total points possible. Note that an item must be included in the grade (see previous property) to be assignable as extra credit.
  • true
  • false
{pointsPossible} The total possible points that can be awarded for this item. Any float (decimal) number or integer.

API Response

Response HTTP Status Codes and Headers

This API returns the standard HTTP Status Codes used by the LearningStudio APIs. There are no special headers returned by the API.

When updating an item, the API will return a status code of 204 - No Content with no response body.

Response Body

Format

{
  "gradebookItems":[
  {
    "type":"{type}",
    "id":"{guid}",
    "title":"{title}",
    "isIncludedInGrade":{isIncludedInGradeFlag},
    "isExtraCredit":{isExtraCreditFlag},
    "pointsPossible":{pointsPossible},
    "weightsPossible":{weightsPossible},
    "links":[{
      "href":"{contentItemHref}",
      "rel":"related"
      },{
      "href":"{contentItemHref}",
      "rel":"https://api.learningstudio.com/courses/items/item"
      },{
      "href":"{unitHref}",
      "rel":"https://api.learningstudio.com/courses/items/unit"
      },{
      "href":"{dropboxBasketHref}",
      "rel":"https://api.learningstudio.com/course/dropboxbaskets"
      }
      ]
    }
  ]
}

Property Descriptions

Name Description
{type} Signifies whether the gradable item is for a default category or a custom category. Possible values are:

  • courseItem - default category
  • customItem - custom category
{guid} LearningStudio Gradable Item GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio.
{title} Title of the gradebook item.
{isIncludedInGradeFlag} Boolean that defines whether the item is included in course grade calculations.
{isExtraCreditFlag} Boolean that defines whether the item is marked as extra credit.
{pointsPossible} Number of points the user will get for a correct answer on this item.
{weightsPossible} The "weight" of the course items relative to other course content, listed in percentage points. Weighting allows users to "count" some course content items more than others without having to rely on point totals.

Note: This property is only included in the payload if weighting is turned on for this gradebook (this is configured via the User Interface).

{contentItemHref} A link to the detail for content item with which this gradable item is associated. (Due to the backwards-compatible evolution of this API over time, this URL may be duplicated in two separate links.) This may not appear for custom Items. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the content item. Learn more.
{unitHref} A link to the detail for unit content item with which this gradable item is associated. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the unit detail. Learn more.
{dropboxBasketHref} A link to the detail for dropbox basket content item with which this gradable item is associated. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the unit detail. Learn more.

Example: Get All Gradebook Items

Request

Endpoint

GET /courses/123456/gradebookItems

Response

Body

{
  "gradebookItems":[
  {
    "type":"courseItem",
    "id":"a24e4de6-ABCD-1234-WXYZ-123456789000",
    "title":"text item due yesterday",
    "pointsPossible":10.00,
    "isIncludedInGrade":true,
    "isExtraCredit":false,
    "links":[{
        "href":"https://api.learningstudio.com/courses/123456/items/1001234567",
        "rel":"related"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/1001234567",
        "rel":"https://api.learningstudio.com/courses/items/item"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/2007654321",
        "rel":"https://api.learningstudio.com/courses/items/unit"
      }]
  },{
    "type":"courseItem",
    "id":"bd681b1c-FFFF-1234-PPPP-000987654321",
    "title":"text item due today",
    "pointsPossible":10.00,
    "isIncludedInGrade":true,
    "isExtraCredit":false,
    "links":[{
        "href":"https://api.learningstudio.com/courses/2022295/items/1003333666",
        "rel":"related"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/1003333666",
        "rel":"https://api.learningstudio.com/courses/items/item"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/2004444555",
        "rel":"https://api.learningstudio.com/courses/items/unit"
      },{
        "href":"https:/api.learningstudio.com/courses/123456/dropboxBaskets/7201",
        "rel":"https://api.learningstudio.com/course/dropboxbaskets"
      }]
  }]
}

Example: Update Gradebook Item

Request

Endpoint

PUT /courses/123456/gradebook/gradebookItems/bd681b1c-FFFF-1234-PPPP-000987654321

Body

{
  "gradebookItem":{
    "isIncludedInGrade":true,
    "isExtraCredit":false,
    "pointsPossible":10.00
  }
}

Response

HTTP Status Code

204 No Content
3210 reads
Always Learning
Pearson