Skip to content

Line Items and Grades

The /api/lineitems endpoints implement the Assignment and Grade Service and are used to access and manipulate line items and scores.

Retrieve line items

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems GET LTIK_AUTH_V1

Request

Parameters

PARAMETER TYPE LOCATION REQUIRED
id String query
resourceId String query
tag String query
label String query
resourceLinkId Boolean query
limit Number query
url String query
  • id: Retrieves a specific line item by ID. Line item IDs are URLs so the parameter should be URL encoded.
  • resourceId: Filters line items by resourceId.
  • tag: Filters line items by tag.
  • label: Filters line items by label.
  • resourceLinkId: Filters line items by the resource link ID attached to the current launch context.
  • limit: Limits the number of line items returned.
  • url: Retrieves line items from a specific URL.
    • When present, the url parameter causes every other parameter to be ignored.
    • The url parameter should be URL encoded.
    • In cases where not all line items are retrieved when the line item limit is reached, the returned object will contain a next field holding an URL that can be used to retrieve the remaining line items through the url parameter.

Example usage

app.get('/get-lineitems', async (req, res, next) => {
  const ltik = req.query.ltik
  const query = {
    tag: 'grade_line',
    label: 'Grade line'
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.get('https://your.ltiaas.com/api/lineitems', { searchParams: query, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response.lineItems)
})

Response

Returns an object with a lineItems field containing an array of line items.

More information about line items can be found in the IMS Line Item Service specification.

  • lineItems = Array of line items.
  • next - URL of the next line item page. This field is only present if the line item limit was reached before the full list was retrieved.
  • prev - URL of the previous line item page. This field is only present if the line item limit was reached before the full list was retrieved.
  • first - URL of the first line item page. This field is only present if the line item limit was reached before the full list was retrieved.
  • last - URL of the last line item page. This field is only present if the line item limit was reached before the full list was retrieved.

Example response

{
  next: 'https://lms.example.com/sections/2923/lineitems/pages/2',
  first: 'https://lms.example.com/sections/2923/lineitems/pages/1',
  last: 'https://lms.example.com/sections/2923/lineitems/pages/3',
  lineItems: [  
    {
      id: 'https://lms.example.com/context/2923/lineitems/1',
      scoreMaximum: 60,
      label: 'Chapter 5 Test',
      resourceId: 'a-9334df-33',
      tag: 'grade',
      resourceLinkId: '1g3k4dlk49fk',
      endDateTime: '2018-04-06T22:05:03Z'
    },
    {
      id: 'https://lms.example.com/context/2923/lineitems/47',
      scoreMaximum: 100,
      label: 'Chapter 5 Progress',
      resourceId: 'a-9334df-33',
      tag: 'originality',
      resourceLinkId: '1g3k4dlk49fk'
    },
    {
      id: 'https://lms.example.com/context/2923/lineitems/69',
      scoreMaximum: 60,
      label: 'Chapter 2 Essay',
      tag: 'grade'
    }
  ]
}

Create line item

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems POST LTIK_AUTH_V1

Request

Parameters

Requests MUST have a body representing a Line Item Object as specified in the IMS Line Item Object Specification.

The only required parameters are label and scoreMaximum.

PARAMETER TYPE LOCATION REQUIRED
label String body ✔️
scoreMaximum Number body ✔️
  • label: Line item label.
  • scoreMaximum: Maximum score allowed for the line item.

Example usage

app.post('/create-lineitem', async (req, res, next) => {
  const ltik = req.query.ltik
  const lineitem = {
    scoreMaximum: 60,
    label: 'Grade line',
    resourceId: 'quiz-231',
    tag: 'grade',
    resourceLinkId: '42', // Can be retrieved from ID Token's resource link ID (idtoken.launch.resource.id). Used to bind line item to LMS resource (activity).
    startDateTime: '2022-03-06T20:05:02Z',
    endDateTime: '2022-04-06T22:05:03Z'
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.post('https://your.ltiaas.com/api/lineitems', { json: lineitem, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

Setting a resourceLinkId will bind the created line item to a specific resource (activity) in the LMS.

Response

Returns the newly created line item.

Example response

{
  id: 'https://lms.example.com/context/2923/lineitems/1',
  scoreMaximum: 60,
  label: 'Chapter 5 Test',
  resourceId: 'quiz-231',
  tag: 'grade',
  resourceLinkId: '1234',
  startDateTime: '2018-03-06T20:05:02Z',
  endDateTime: '2018-04-06T22:05:03Z'
}

Retrieve line item by ID

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems/:lineitemid GET LTIK_AUTH_V1

The line item ID is an URL so it MUST be URL encoded.

Request

Parameters

The /lineitems/:lineitemid GET endpoint receives no parameters.

Example usage

app.get('/get-lineitem', async (req, res, next) => {
  const ltik = req.query.ltik
  const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.get(`https://your.ltiaas.com/api/lineitems/${lineitemId}`, { headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

Response

Returns the requested line item.

Example response

{
  id: 'https://lms.example.com/context/2923/lineitems/1',
  scoreMaximum: 60,
  label: 'Chapter 5 Test',
  resourceId: 'quiz-231',
  tag: 'grade',
  startDateTime: '2018-03-06T20:05:02Z',
  endDateTime: '2018-04-06T22:05:03Z'
}

Update line item by ID

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems/:lineitemid PUT LTIK_AUTH_V1

The line item ID is an URL so it MUST be URL encoded.

Request

Parameters

Requests MUST have a body representing a Line Item Object as specified in the IMS Line Item Object Specification.

The only required parameters are label and scoreMaximum.

PARAMETER TYPE LOCATION REQUIRED
label String body ✔️
scoreMaximum Number body ✔️
  • label: Line item label.
  • scoreMaximum: Maximum score allowed for the line item.

Example usage

app.put('/update-lineitem', async (req, res, next) => {
  const ltik = req.query.ltik
  const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
  const lineitem = {
    scoreMaximum: 60,
    label: 'Chapter 5 Updated'
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.put(`https://your.ltiaas.com/api/lineitems/${lineitemId}`, { json: lineitem, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

Response

Returns the updated line item.

Example response

{
  id: 'https://lms.example.com/context/2923/lineitems/1',
  scoreMaximum: 60,
  label: 'Chapter 5 Updated',
  resourceId: 'quiz-231',
  tag: 'grade',
  startDateTime: '2018-03-06T20:05:02Z',
  endDateTime: '2018-04-06T22:05:03Z'
}

Delete line item by ID

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems/:lineitemid DELETE LTIK_AUTH_V1

The line item ID is an URL so it MUST be URL encoded.

Request

Parameters

The /lineitems/:lineitemid DELETE endpoint receives no parameters.

Example usage

app.delete('/launch', async (req, res, next) => {
  const ltik = req.query.ltik
  const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  await request.delete(`https://your.ltiaas.com/api/lineitems/${lineitemId}`, { headers: { Authorization: authorizationHeader } })
  return res.sendStatus(204)
})

Response

Returns 204 status if the line item is successfully deleted.

Submit scores

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems/:lineitemid/scores POST LTIK_AUTH_V1

The line item ID is an URL so it MUST be URL encoded.

Request

Parameters

Requests MUST have a body representing a Score Object as specified in the IMS Score Specification.

The required parameters are userId, activityProgress and gradingProgress. The parameters timestamp and scoreMaximum are also required but are set automatically by LTIaaS.

PARAMETER TYPE LOCATION REQUIRED
userId String body ✔️
activityProgress String body ✔️
gradingProgress String body ✔️
  • userId: Target user ID.
  • activityProgress: Status of the user towards the activity's completion.
  • gradingProgress: Status of the grading process.

Example usage

app.get('/submit-score', async (req, res, next) => {
  const ltik = req.query.ltik
  const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
  const score = {
    userId: '5323497',
    activityProgress: 'Completed',
    gradingProgress: 'FullyGraded',
    scoreGiven: 83,
    comment: 'This is exceptional work.',
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.post(`https://your.ltiaas.com/api/lineitems/${lineitemId}/scores`, { json: score, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

Response

Returns the submitted score.

Example response

{
  userId: '5323497',
  activityProgress: 'Completed',
  gradingProgress: 'FullyGraded',
  scoreGiven: 83,
  scoreMaximum: 100,
  comment: 'This is exceptional work.',
  timestamp: '2021-04-16T18:54:36.736+00:00',
}

Retrieve scores

ROUTE METHOD AUTHENTICATION METHOD
/api/lineitems/:lineitemid/scores GET LTIK_AUTH_V1

The line item ID is an URL so it MUST be URL encoded.

Request

Parameters

PARAMETER TYPE LOCATION REQUIRED
userId String query
limit Number query
url String query
  • userId: Filters scores based on the user ID.
  • limit: Limits the number of scores returned.
  • url: Retrieves scores from a specific URL.
    • When present, the url parameter causes every other parameter to be ignored.
    • The url parameter should be URL encoded.
    • In cases where not all scores are retrieved when the score limit is reached, the returned object will contain a next field holding an URL that can be used to retrieve the remaining scores through the url parameter.

Example usage

app.get('/launch', async (req, res, next) => {
  const ltik = req.query.ltik
  const lineitemId = encodeURIComponent('https://lms.example.com/context/2923/lineitems/1')
  const query = {
    userId: 2,
    limit: 10
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.get(`https://your.ltiaas.com/api/lineitems/${lineitemId}/scores`, { searchParams: query, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response.scores)
})

Response

Returns an object with a scores field containing an array of scores.

More information about scores can be found in the IMS Result Service specification.

  • scores - Array of scores.
  • next - URL of the next score page. This field is only present if the score limit was reached before the full list was retrieved.
  • prev - URL of the previous score page. This field is only present if the score limit was reached before the full list was retrieved.
  • first - URL of the first score page. This field is only present if the score limit was reached before the full list was retrieved.
  • last - URL of the last score page. This field is only present if the score limit was reached before the full list was retrieved.

Example response

{
  next: 'https://lms.example.com/sections/2923/scores/pages/2',
  first: 'https://lms.example.com/sections/2923/scores/pages/1',
  last: 'https://lms.example.com/sections/2923/scores/pages/3',
  scores: [
    {
      id: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem/results?type_id=1&user_id=2',
      userId: '2',
      resultScore: 100,
      resultMaximum: 100,
      scoreOf: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem?type_id=1',
      timestamp: '2020-06-02T10:51:08-03:00'
    },
    {
      id: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem/results?type_id=1&user_id=2',
      userId: '3',
      resultScore: 90,
      resultMaximum: 100,
      scoreOf: 'https://lms.example.com/lti/services.php/2/lineitems/16/lineitem?type_id=1',
      timestamp: '2020-06-02T10:51:08-03:00'
    }
  ]
}