Learning Tools Interoperability Assignment and Grade Services

https://www.imsglobal.org/spec/lti-ags/v2p0/
Admin
This specification defines the Learning Tools Interoperability (LTI) Assignment and Grade Services,...
Tokens:20,906
Snippets:107
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### POST Example: Progress Started Score Update (LTI-AGS v2.0)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Example of a POST request to publish a progress started score update. This is used to indicate that an activity has begun or is in progress, without necessarily providing a final score. It includes userId, activityProgress, gradingProgress, and submission details like startedAt and submittedAt.

```http
POST lineitem URL/scores
Content-Type: application/vnd.ims.lis.v1.score+json
Authentication: Bearer 89042.hfkh84390xaw3m
{
  "timestamp": "2017-03-16T18:54:36.736+00:00",
  "activityProgress" : "InProgress",
  "gradingProgress": "NotReady",
  "userId" : "5323497",
  "submission": {
    "startedAt": "2017-03-13T16:12:27.000+00:00",
    "submittedAt": "2017-03-14T18:42:15.000+00:00"
  }
}


HTTP/1.1 204 No Content
```

--------------------------------

### Example GET Request for Line Item Results

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Demonstrates how a tool can request the results for a specific line item from the platform's Result Service. It includes the necessary HTTP method, headers for authentication and content type negotiation.

```http
GET lineitem URL/results
Authentication: Bearer 8789.ghiurn2.polgw1
Accept: application/vnd.ims.lis.v2.resultcontainer+json
```

--------------------------------

### LTI-AGS v2.0: HTTP Request to GET a Single Line Item

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This example shows the HTTP request to retrieve a single line item. It includes the GET method, the URL for the line item, and the Accept header specifying the desired media type.

```http
HTTP/1.1 GET lineitem URL
Accept: application/vnd.ims.lis.v2.lineitem+json

200 OK
content-type: application/vnd.ims.lis.v2.lineitem+json
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "a-9334df-33",
  "tag" : "grade",
  "resourceLinkId" : "1g3k4dlk49fk",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z",
  "gradesReleased": false
}
```

--------------------------------

### Pagination Link Header Example (HTTP)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

An example of an HTTP 'Link' header used for pagination, as described in RFC8288. This header indicates the URL for the next page of results.

```HTTP
Link: <https://lms.example.com/sections/2923/lineitems/69?p=2>; rel="next"
```

--------------------------------

### LTI-AGS v2.0: HTTP Request to GET All Line Items in a Container

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This example illustrates the HTTP request to retrieve all line items within a given container. It uses the GET method on the 'lineitems' URL and specifies the media type for a line item container.

```http
HTTP/1.1 GET lineitems URL
Accept: application/vnd.ims.lis.v2.lineitemcontainer+json

200 OK
content-type: application/vnd.ims.lis.v2.lineitemcontainer+json
[
  {
        "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"
        "gradesReleased": true
    },
    {
        "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"
    }
]
```

--------------------------------

### POST Example: Final Score Update (LTI-AGS v2.0)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Example of a POST request to publish a final score update for a user on a specific line item. Includes essential fields like timestamp, scoreGiven, scoreMaximum, comment, activityProgress, gradingProgress, userId, and scoringUserId. The response is typically '204 No Content' upon successful processing.

```http
POST lineitem URL/scores
Content-Type: application/vnd.ims.lis.v1.score+json
Authentication: Bearer 89042.hfkh84390xaw3m
{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "scoreGiven" : 83,
  "scoreMaximum" : 100,
  "comment" : "This is exceptional work.",
  "activityProgress" : "Completed",
  "gradingProgress": "FullyGraded",
  "userId" : "5323497",
  "scoringUserId": "4567890"
}


HTTP/1.1 204 No Content
```

--------------------------------

### Filter Line Items by Resource ID and Link ID (HTTP)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Demonstrates filtering line items using 'resource_id' and 'resource_link_id' query parameters in an HTTP GET request. Shows an example of an empty response when no matching line items are found.

```HTTP
GET lineitems URL?resource_id=d0d6212ecc4e4696a76f7359ef76e3f4
Accept: application/vnd.ims.lis.v2.lineitemcontainer+json

HTTP/1.1 200 OK
content-type: application/vnd.ims.lis.v2.lineitemcontainer+json
[]
```

--------------------------------

### Score Object Example (application/vnd.ims.lis.v1.score+json)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

An example of a Score object, representing a completed activity that is pending manual grading. It includes essential properties like timestamp, activityProgress, gradingProgress, and userId.

```json
{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "activityProgress" : "Completed",
  "gradingProgress" : "PendingManual",
  "userId" : "5323497"
}
```

--------------------------------

### Example Response for Line Item Results

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Illustrates the JSON structure returned by the Result Service when a GET request for line item results is successful. It details the fields for result identification, score, and associated metadata.

```json
HTTP/1.1 200 OK
content-type: application/vnd.ims.lis.v2.resultcontainer+json
[
  {
    "id": "https://lms.example.com/context/2923/lineitems/1/results/5323497",
    "scoreOf": "https://lms.example.com/context/2923/lineitems/1",
    "userId": "5323497",
    "resultScore": 0.83,
    "resultMaximum": 1,
    "scoringUserId": "4567890",
    "comment": "This is exceptional work."
  }
]
```

--------------------------------

### GET /lineitems

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Retrieves a list of line items for a given context. The response format is a line item container.

```APIDOC
## GET /lineitems

### Description
Retrieves a collection of line items associated with a specific context. This endpoint is used to query multiple line items.

### Method
GET

### Endpoint
`/lineitems`

### Query Parameters
None

### Request Body
None

### Request Example
```http
HTTP/1.1 GET /lineitems
Accept: application/vnd.ims.lis.v2.lineitemcontainer+json
```

### Response
#### Success Response (200)
- **Content-Type**: `application/vnd.ims.lis.v2.lineitemcontainer+json`
- **Body**: A JSON array of line item objects.

#### Response Example
```json
[
    {
        "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",
        "gradesReleased": true
    },
    {
        "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"
    }
]
```
```

--------------------------------

### Update Line Item Definition (HTTP PUT)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This example demonstrates how a tool can update a line item definition by sending a PUT request to the line item's URL. It includes the necessary headers and a JSON payload with the updated fields. The response shows the platform's applied changes, including an instance where 'scoreMaximum' was not updated.

```HTTP
PUT lineitems URL
Authorization: Bearer 78aerc7829z.890.duepz
Content-Type: application/vnd.ims.lis.v2.lineitem+json
{
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "endDateTime": "2018-04-06T22:05:03Z"
}


HTTP/1.1 201 Created
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 50,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "startDateTime": "",
  "endDateTime": "2018-04-06T22:05:03Z"
  "gradesReleased": true
}
```

--------------------------------

### Create Line Item Response (No Start/End Times)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Shows an alternative 201 Created response for creating a line item when the platform does not support start and end times. The 'id', 'scoreMaximum', 'label', 'resourceId', and 'tag' are included.

```HTTP
HTTP/1.1 201 Created
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade"
}
```

--------------------------------

### LTI AGS Endpoint Claim Example (Line Item Management)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This JSON snippet shows the 'endpoint' claim where the tool has permissions to query and add line items but no specific line item URL is provided. This configuration is used when the link is not associated with a single line item.

```json
{
  "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score"
    ],
    "lineitems": "https://www.myuniv.edu/2344/lineitems/"
  }
}
```

--------------------------------

### LTI-AGS v2.0: Tool POSTs Single Score

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This snippet shows an example of how a tool can POST a single score to a line item. It specifies the scope required for this operation and the URL of the line item.

```json
{
  "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-ags/scope/score"
    ],
    "lineitem": "https://www.myuniv.edu/2344/lineitems/1234/lineitem"
  }
}
```

--------------------------------

### LTI-AGS v2.0: Score Extension with Custom Data

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This example demonstrates how to extend the score object with additional custom data using a fully qualified URL as the key. This allows tools to pass extra information relevant to the score.

```json
{
  "timestamp": "2017-04-16T18:54:36.736+00:00",
  "activityProgress" : "Completed",
  "gradingProgress" : "PendingManual",
  "userId" : "5323497",
  "https://www.toolexample.com/lti/score": {
    "originality": 94,
    "submissionUrl": "https://www.toolexample.com/lti/score/54/5893/essay.pdf"
  }
}
```

--------------------------------

### GET /lineitems

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Retrieves a list of line items, optionally filtered by resource link ID, resource ID, tag, or a limit for pagination. Supports RFC8288 Link headers for navigation.

```APIDOC
## GET /lineitems

### Description
Retrieves a list of line items. This endpoint supports filtering the results using query parameters such as `resource_link_id`, `resource_id`, and `tag`. Pagination is supported via the `limit` query parameter, which may also trigger the inclusion of RFC8288 `Link` headers for 'next', 'prev', 'first', and 'last' page navigation.

### Method
GET

### Endpoint
`/lineitems`

### Parameters
#### Query Parameters
- **resource_link_id** (string) - Optional - Limits line items to those associated with the specified tool platform's LTI link ID.
- **resource_id** (string) - Optional - Limits line items to those associated with the specified tool resource identifier.
- **tag** (string) - Optional - Limits line items to those associated with the specified tag.
- **limit** (integer) - Optional - Restricts the number of line items returned. If more items exist, a 'Link' http header with a URL pointing to the next page and a 'rel' value of 'next' MUST be included.

### Request Example
```
GET /lineitems?resource_id=d0d6212ecc4e4696a76f7359ef76e3f4 HTTP/1.1
Accept: application/vnd.ims.lis.v2.lineitemcontainer+json
```

### Response
#### Success Response (200)
- **Array** (Array of LineItem objects) - A list of line items matching the specified filters, or an empty array if no matches are found.

#### Response Example
```json
[
  {
    "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"
  }
]
```

#### Response Example (Empty)
```json
[]
```

#### Headers Example (for pagination)
```
Link: <https://lms.example.com/sections/2923/lineitems/69?p=2>; rel="next"
```
```

--------------------------------

### LTI AGS Endpoint Claim Example (Full Permissions)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This JSON snippet illustrates the 'endpoint' claim within an LTI message, indicating that the tool has permissions for line items, read-only results, and scores. It includes URLs for both the general line items endpoint and a specific line item.

```json
{
  "https://purl.imsglobal.org/spec/lti-ags/claim/endpoint": {
    "scope": [
      "https://purl.imsglobal.org/spec/lti-ags/scope/lineitem",
      "https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly",
      "https://purl.imsglobal.org/spec/lti-ags/scope/score"
    ],
    "lineitems": "https://www.myuniv.example.com/2344/lineitems/",
    "lineitem": "https://www.myuniv.example.com/2344/lineitems/1234/lineitem"
  }
}
```

--------------------------------

### PUT /lineitems/{lineItemId}

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Updates an existing line item definition. The entire line item definition is replaced with the provided payload. It's recommended to first GET the current definition to avoid conflicts.

```APIDOC
## PUT /lineitems/{lineItemId}

### Description
Updates an existing line item definition. The entire line item definition is replaced with the provided payload. It's recommended to first GET the current definition to avoid conflicts.

### Method
PUT

### Endpoint
`/lineitems/{lineItemId}`

### Parameters
#### Path Parameters
- **lineItemId** (string) - Required - The unique identifier for the line item to be updated.

#### Query Parameters
None

#### Request Body
- **scoreMaximum** (number) - Required - The maximum score for this line item. Must be a numeric non-null value, strictly greater than 0.
- **label** (string) - Required - A short, human-readable text for the line item. Must not be blank.
- **resourceLinkId** (string) - Optional - Identifier for the resource link this line item is attached to.
- **resourceId** (string) - Optional - Tool's identifier for the resource the line item is attached to. Must be non-blank if provided.
- **tag** (string) - Optional - Further qualifies the line item. Can be used to differentiate multiple line items for the same resource.
- **startDateTime** (string) - Optional - ISO 8601 formatted date and time when the line item can start receiving submissions. Must include a time zone designator.
- **endDateTime** (string) - Optional - ISO 8601 formatted date and time when the line item can stop receiving submissions. Must include a time zone designator.

### Request Example
```json
{
  "scoreMaximum": 60,
  "label": "Chapter 5 Test",
  "resourceId": "quiz-231",
  "tag": "grade",
  "endDateTime": "2018-04-06T22:05:03Z"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the line item.
- **scoreMaximum** (number) - The maximum score for the line item as applied by the platform.
- **label** (string) - The label for the line item.
- **resourceId** (string) - The resource ID associated with the line item.
- **tag** (string) - The tag associated with the line item.
- **startDateTime** (string) - The start date and time for submissions.
- **endDateTime** (string) - The end date and time for submissions.
- **gradesReleased** (boolean) - Indicates if grades have been released for this line item.

#### Response Example
```json
{
  "id": "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum": 50,
  "label": "Chapter 5 Test",
  "resourceId": "quiz-231",
  "tag": "grade",
  "startDateTime": "",
  "endDateTime": "2018-04-06T22:05:03Z",
  "gradesReleased": true
}
```

#### Error Responses
- **400 Bad Request**: The request payload is invalid.
- **401 Unauthorized**: The client is not authorized to perform the action.
- **403 Forbidden**: The client does not have permission to access the resource.
- **404 Not Found**: The specified line item or resource link does not exist.
- **409 Conflict**: The line item was modified concurrently by another client.
```

--------------------------------

### Substitution Parameters for Line Items

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Explains how 'LineItem.url' is resolved and when substitution parameters are available. It also details fallback mechanisms when multiple line items exist or no direct relationship is found.

```APIDOC
## Substitution Parameters Available on Launch

### Description
'LineItem.url' can only be resolved if there is a single associated line item with the resource link. In this case, matching parameters MUST be present in the launch data. If multiple line items exist, or there's no direct relationship, the platform cannot pass these values. The tool must then use 'LineItems.url' and filter by 'resource_link_id', 'resource_id', and/or 'tag'.

### Method
N/A (Launch context)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Create a New Line Item (HTTP)

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Illustrates the process of creating a new line item by sending a POST request to the 'lineitems' endpoint. Includes the request body with line item details and the subsequent 201 Created response with the newly created item's URL.

```HTTP
POST lineitems URL
Authorization: Bearer 78aerc7829z.890.duepz
Content-Type: application/vnd.ims.lis.v2.lineitem+json
{
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "quiz-231",
  "tag" : "grade",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z"
}

HTTP/1.1 201 Created
{
  "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"
}
```

--------------------------------

### GET /lineitems/{id}/results

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Retrieves results for a specific line item. This endpoint allows fetching grades submitted for an assignment.

```APIDOC
## GET /lineitems/{id}/results

### Description
Retrieves the results (scores) associated with a specific line item. This endpoint is used to fetch grades that have been submitted for a particular assignment or activity.

### Method
GET

### Endpoint
`/lineitems/{id}/results`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique URL (ID) of the line item for which to retrieve results.

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
HTTP/1.1 GET /lineitems/https://lms.example.com/context/2923/lineitems/1/results
```

### Response
#### Success Response (200 OK)
- **Content-Type**: `application/vnd.ims.lis.v2.resultcontainer+json` (expected, though not explicitly stated in source)
- **Body** (array): A JSON array of result objects, each representing a score submission for the line item.

#### Response Example
```json
[
  {
    "id": "https://lms.example.com/context/2923/lineitems/1/results/student123",
    "scoreGiven": 85,
    "scoreMaximum": 100,
    "timestamp": "2023-10-27T10:00:00Z",
    "activityProgress": "Completed",
    "gradingProgress": "FullyGraded",
    "userId": "student123"
  },
  {
    "id": "https://lms.example.com/context/2923/lineitems/1/results/student456",
    "scoreGiven": 92,
    "scoreMaximum": 100,
    "timestamp": "2023-10-27T10:05:00Z",
    "activityProgress": "Completed",
    "gradingProgress": "FullyGraded",
    "userId": "student456"
  }
]
```
```

--------------------------------

### GET /lineitems/{id}

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Retrieves a specific line item by its ID. This endpoint allows fetching details of a single grading item.

```APIDOC
## GET /lineitems/{id}

### Description
Retrieves a single line item identified by its unique URL (ID). This is used to get the details of a specific grading assignment.

### Method
GET

### Endpoint
`/lineitems/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique URL (ID) of the line item to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
HTTP/1.1 GET /lineitems/https://lms.example.com/context/2923/lineitems/1
Accept: application/vnd.ims.lis.v2.lineitem+json
```

### Response
#### Success Response (200)
- **Content-Type**: `application/vnd.ims.lis.v2.lineitem+json`
- **Body** (object): A JSON object representing the line item.

#### Response Example
```json
{
  "id" : "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum" : 60,
  "label" : "Chapter 5 Test",
  "resourceId" : "a-9334df-33",
  "tag" : "grade",
  "resourceLinkId" : "1g3k4dlk49fk",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z",
  "gradesReleased": false
}
```
```

--------------------------------

### POST /lineitems

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Creates a new line item. The platform must return the newly created item, enriched with its URL. The `resourceId` and `tag` fields are immutable.

```APIDOC
## POST /lineitems

### Description
Creates a new line item. The request body should contain the details of the line item to be created. The platform MUST return the newly created line item, including its unique `id` (URL). The `resourceId` and `tag` properties of the created line item cannot be modified by the platform. The `resourceLinkId` is optional and has specific usage constraints.

### Method
POST

### Endpoint
`/lineitems`

### Parameters
#### Request Body
- **scoreMaximum** (number) - Required - The maximum score possible for this line item.
- **label** (string) - Required - The label or name of the line item.
- **resourceId** (string) - Required - The identifier for the resource associated with this line item.
- **tag** (string) - Optional - A tag or category for the line item.
- **startDateTime** (string) - Optional - The start date and time for the line item in ISO 8601 format.
- **endDateTime** (string) - Optional - The end date and time for the line item in ISO 8601 format.
- **resourceLinkId** (string) - Optional - The LTI resource link identifier associated with this line item. Its usage is restricted.

### Request Example
```json
{
  "scoreMaximum": 60,
  "label": "Chapter 5 Test",
  "resourceId": "quiz-231",
  "tag": "grade",
  "startDateTime": "2018-03-06T20:05:02Z",
  "endDateTime": "2018-04-06T22:05:03Z"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique URL of the created line item.
- **scoreMaximum** (number) - The maximum score for the line item.
- **label** (string) - The label of the line item.
- **resourceId** (string) - The resource ID associated with the line item.
- **tag** (string) - The tag associated with the line item.
- **startDateTime** (string) - The start date and time (if provided and supported).
- **endDateTime** (string) - The end date and time (if provided and supported).

#### Response Example (with start/end times)
```json
{
  "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"
}
```

#### Response Example (without start/end times)
```json
{
  "id": "https://lms.example.com/context/2923/lineitems/1",
  "scoreMaximum": 60,
  "label": "Chapter 5 Test",
  "resourceId": "quiz-231",
  "tag": "grade"
}
```
```

--------------------------------

### Result Service API

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

The Result Service allows tools to retrieve current results for their line items from the platform. It supports read-only GET operations and is accessed via a subpath of the line item resource URL.

```APIDOC
## GET /results

### Description
Retrieves the current results for a specific line item across all users or a single user.

### Method
GET

### Endpoint
`[line_item_url]/results`

### Parameters
#### Query Parameters
- **user_id** (string) - Optional - Filters results to a specific user.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **id** (string) - URL uniquely identifying the result record.
- **scoreOf** (string) - URL identifying the Line Item to which this result belongs.
- **userId** (string) - LTI user ID identifying the recipient of the Result.
- **resultScore** (number) - The current score for this user. May be omitted or null if no value exists.
- **resultMaximum** (number) - The maximum possible score for the line item. Must be a positive number; defaults to 1 if not specified.
- **scoringUserId** (string) - The LTI user ID of the agent who performed the scoring.
- **comment** (string) - A comment associated with the result.

#### Response Example
```json
[
  {
    "id": "https://lms.example.com/context/2923/lineitems/1/results/5323497",
    "scoreOf": "https://lms.example.com/context/2923/lineitems/1",
    "userId": "5323497",
    "resultScore": 0.83,
    "resultMaximum": 1,
    "scoringUserId": "4567890",
    "comment": "This is exceptional work."
  }
]
```
```

--------------------------------

### POST /lineitems

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Creates a new line item within a context. This endpoint allows tools to define new grading items.

```APIDOC
## POST /lineitems

### Description
Creates a new line item. This endpoint is used by a tool to register a new grading assignment or activity within a learning platform.

### Method
POST

### Endpoint
`/lineitems`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scoreMaximum** (number) - Required - The maximum score a student can achieve for this line item.
- **label** (string) - Required - A human-readable label for the line item (e.g., 'Homework 1', 'Quiz 3').
- **resourceLinkId** (string) - Optional - An identifier for the resource associated with this line item.
- **resourceId** (string) - Optional - A platform-specific identifier for the resource.
- **tag** (string) - Optional - A tag to categorize the line item (e.g., 'grade', 'completion').
- **startDateTime** (string) - Optional - ISO 8601 datetime string indicating when the item is available.
- **endDateTime** (string) - Optional - ISO 8601 datetime string indicating the due date for the item.

### Request Example
```json
{
  "scoreMaximum": 100,
  "label": "Final Exam",
  "resourceLinkId": "lti-resource-12345",
  "tag": "final-grade",
  "endDateTime": "2024-12-31T23:59:59Z"
}
```

### Response
#### Success Response (201 Created)
- **Location** (header) - URL of the newly created line item.
- **Body** (object) - The created line item object, including its assigned `id`.

#### Response Example
```json
{
  "id": "https://lms.example.com/context/abc/lineitems/xyz",
  "scoreMaximum": 100,
  "label": "Final Exam",
  "resourceLinkId": "lti-resource-12345",
  "tag": "final-grade",
  "endDateTime": "2024-12-31T23:59:59Z"
}
```
```

--------------------------------

### Valid Timestamp Formats for Score Updates

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Examples of valid timestamp formats as per the LTI AGS v2.0 specification. Timestamps must be in ISO 8601 format with sub-second precision and include a time zone designator (Z for UTC or an offset).

```json
"timestamp": "2017-04-16T18:54:36.736+00:00"

```

```json
"timestamp": "2017-04-16T18:54:36.736Z"

```

```json
"timestamp": "2017-04-16T18:54:36.736+00"

```

--------------------------------

### Score Submission API

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This section details the optional fields that can be included when submitting a score, such as startedAt, submittedAt, and comment. It also explains how these fields are handled by the platform.

```APIDOC
## POST /scores

### Description
Submits a score or status update for a line item. This endpoint allows for the inclusion of optional fields to provide more context about the submission.

### Method
POST

### Endpoint
`/scores`

### Parameters
#### Request Body
- **startedAt** (string) - Optional - Indicates when work on the line item submission was first started by the student. Must be ISO 8601 format with sub-second precision and a time zone designator.
- **submittedAt** (string) - Optional - Indicates when work on the line item submission was completed by the student. Must be ISO 8601 format with sub-second precision and a time zone designator. If both `startedAt` and `submittedAt` are present, `submittedAt` must be equal to or later than `startedAt`.
- **comment** (string) - Optional - A plain text comment intended for both student and instructor. The platform will update its comment with every score update. If not present, blank, or null, the platform comment will be cleared if it was sent from the tool.

### Request Example
```json
{
  "score": 0.85,
  "startedAt": "2023-10-27T10:00:00.123Z",
  "submittedAt": "2023-10-27T11:30:00.456Z",
  "comment": "Good effort on this assignment."
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the score submission.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Managing Multiple Line Items API

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

This section describes how to manage multiple line items, enabling a tool to return multiple results to a tool consumer for a single resource. It covers the workflow for creating and updating line items and submitting scores.

```APIDOC
## GET /lineitems

### Description
Retrieves a list of line items. Can be filtered by `resource_link_id`.

### Method
GET

### Endpoint
`/lineitems`

### Parameters
#### Query Parameters
- **resource_link_id** (string) - Optional - Filters line items associated with a specific resource link.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the line item.
- **tag** (string) - An identifier for the purpose of the line item (e.g., "grade", "progress").

### Response Example
```json
{
  "id": "/lineitems/12345",
  "tag": "grade"
}
```

## POST /lineitems

### Description
Creates a new line item. This is typically done when a line item does not exist for a given resource link or tag.

### Method
POST

### Endpoint
`/lineitems`

### Parameters
#### Request Body
- **resourceLinkId** (string) - Required - The ID of the resource link to associate the line item with.
- **tag** (string) - Required - An identifier for the purpose of the line item (e.g., "grade", "progress").

### Request Example
```json
{
  "resourceLinkId": "resource-link-abcde",
  "tag": "progress"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created line item.

### Response Example
```json
{
  "id": "/lineitems/67890"
}
```

## POST /scores

### Description
Submits a score for a learner for a specific line item. This endpoint is used to update the learner's progress and grade.

### Method
POST

### Endpoint
`/scores`

### Parameters
#### Request Body
- **lineItemId** (string) - Required - The ID of the line item to which the score belongs.
- **userId** (string) - Required - The LTI User ID of the learner.
- **score** (number) - Required - The score value, typically between 0 and 1.
- **activityProgress** (string) - Optional - Indicates the progress of the activity (e.g., 'Initialized', 'Started', 'Completed').
- **gradingProgress** (string) - Optional - Indicates the grading status (e.g., 'Pending', 'FullyGraded').

### Request Example
```json
{
  "lineItemId": "/lineitems/67890",
  "userId": "user-123",
  "score": 0.85,
  "activityProgress": "Completed",
  "gradingProgress": "FullyGraded"
}
```

### Response
#### Success Response (200)
Indicates that the score was successfully processed.

### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### LTI AGS Submission Review: Pending Manual Grade

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Illustrates the workflow for handling a manual grading process using LTI AGS. The tool posts a score with a 'pendingManual' grading progress, allowing the platform to indicate a pending review, and subsequently updates the score after grading.

```text
1. The tool posts a Score with a `gradingProgress: pendingManual`
2. The platform decorates the gradebook cell with a needs attention indicator
3. The instructor can then click on the indicator
4. An `LtiSubmissionReviewRequest` launches the user into the grading interface of the tool, directly in context of the activity and student to be graded
5. After grading, the tool sends a score update through a POST to the Score endpoint and redirects the user back the Learning Platform using the return URL included in the launch
6. The tool platform updates the grade and status of the activity for that student
```

--------------------------------

### Scores and gradingProgress Handling

Source: https://www.imsglobal.org/spec/lti-ags/v2p0/index

Specifies the requirements for setting the 'gradingProgress' field when submitting scores, emphasizing the need for 'FullyGraded' for final scores to be recorded by the platform.

```APIDOC
## Scores and gradingProgress

### Description
This section outlines the requirements for the 'gradingProgress' field when submitting scores. The platform may choose not to record scores that are not marked as 'FullyGraded'.

### Method
POST (to Score endpoint)

### Endpoint
`/scores` (within a LineItem context)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **gradingProgress** (string) - Required - Must be set to 'FullyGraded' when communicating the student's final score. Other possible values include 'PendingManual', 'Pending', 'PendingAssessment'.

### Request Example
```json
{
  "scoreGiven": 0.82,
  "scoreMaximum": 1.0,
  "gradingProgress": "FullyGraded",
  "timestamp": "2023-10-27T10:00:00Z"
}
```

### Response
#### Success Response (200)
Indicates the score was successfully received and processed.

#### Response Example
```json
{
  "status": "success"
}
```
```
Tokens:
Raw