Responses
Responses are an essential part of the system. Responses hold the general details of a class which binds together the students' grades and the assignments they are given.
The response model
The response model contains all the general information about responses. Responses have additional type-exclusive properties.
Properties
- Name
id- Type
- string
- Description
Unique identifier for the resposne.
- Name
assessment_id- Type
- string
- Description
Unique identifier for the assessment the response is connected to.
- Name
question_id- Type
- string
- Description
Unique identifier for the question the response is connected to.
- Name
student_id- Type
- string
- Description
Unique identifier for the student the response is connected to.
- Name
earned_points- Type
- int
- Description
Number of points the response has earned. Affects the assignment's earned grade.
- Name
type- Type
- string
- Description
Type of question the response is responding to, can be free_response, fill_in, matching, or multiple_choice.
- Name
feedback- Type
- string
- Description
Helpful tips or comments a grader can leave for the student.
Free response additional properties
- Name
reponse- Type
- string
- Description
Student's written response to a free response question.
Fill-in additional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a fill in question. The order matters and must match the order for the correct answer to the question. This is not case-sensitive.
Matching additional properties
- Name
response- Type
- object
- Description
Object that matches strings to strings and is the response of the student to a matching question.
Multiple choice additional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a multiple choice or multi-select question.
Create a response
This endpoint allows you to create a new response.
Required parameters
- Name
assessment_id- Type
- string
- Description
Unique identifier for the assessment the response is connected to.
- Name
question_id- Type
- string
- Description
Unique identifier for the question the response is connected to.
- Name
student_id- Type
- string
- Description
Unique identifier for the student the response is connected to.
- Name
type- Type
- string
- Description
Type of question the response is responding to, can be free_response, fill_in, matching, or multiple_choice.
Optional parameters
- Name
id- Type
- string
- Description
Unique identifier for the response. Randomly generated by default
- Name
earned_points- Type
- int
- Description
Number of points the response has earned. Affects the assignment's earned grade.
- Name
feedback- Type
- string
- Description
Helpful tips or comments a grader can leave for the student.
Free response additional optional properties
- Name
reponse- Type
- string
- Description
Student's written response to a free response question.
Fill-in additional optional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a fill in question. The order matters and must match the order for the correct answer to the question. This is not case-sensitive.
Matching additional optional properties
- Name
response- Type
- object
- Description
Object that matches strings to strings and is the response of the student to a matching question.
Multiple choice additional optional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a multiple choice or multi-select question.
Request for free response
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.question.createResponse({
assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
question_id: "b882aa78-9c65-4446-9174-9bbd8ec26cb6",
student_id: "627a64c9-645a-491f-a851-b59331248af7",
earned_points: 7,
response: "Response to question",
type: "free_response"
})
Response for free response
{
"id": "3ae3641b-9de1-4a07-be5f-b54f788593d6",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "b882aa78-9c65-4446-9174-9bbd8ec26cb6",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 7,
"response": "Response to question",
"type": "free_response",
"feedback": null,
"created_at": "2024-06-26T10:23:11.908718+00:00"
}
Request for fill-in
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.question.createResponse({
assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
question_id: "fe7d5092-c017-4d5e-827e-8a14603bf05e",
student_id: "627a64c9-645a-491f-a851-b59331248af7",
earned_points: 2,
response: ["slope", "intercept"],
type: "fill_in",
})
Response for fill-in
{
"id": "bee32340-328f-410a-8737-174555df1b92",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "fe7d5092-c017-4d5e-827e-8a14603bf05e",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 2,
"response": ["slope", "intercept"],
"type": "fill_in",
"feedback": null,
"created_at": "2024-06-26T12:06:14.908718+00:00"
}
Request for matching
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.question.createResponse({
assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
question_id: "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
student_id: "627a64c9-645a-491f-a851-b59331248af7",
response: {
"Variable": "Number used to multiply a variable",
"Coefficient": "A symbol for an unknown value",
"Constants": "A number on its own"
},
type: "matching",
})
Response for matching
{
"id": "0c150b56-b85c-4daf-8966-464a5f27395c",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"response": {
"Variable": "Number used to multiply a variable",
"Coefficient": "A symbol for an unknown value",
"Constants": "A number on its own"
},
"type": "matching",
"feedback": null,
"created_at": "2024-06-26T15:43:32.827358+00:00"
}
Request for multiple choice
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.question.createResponse({
assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
question_id: "858370d5-14f4-4ac6-bdad-149a252912b1",
student_id: "627a64c9-645a-491f-a851-b59331248af7",
earned_points: 0,
response: ["b"],
feedback: "the variable b is a constant that represents the y-intercept of the equation",
type: "multiple_choice",
})
Response for multiple choice
{
"id": "8a413cf7-347d-4ede-949a-9394e7307a26",
"question_id": "858370d5-14f4-4ac6-bdad-149a252912b1",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 0,
"response": ["b"],
"feedback": "the variable b is a constant that represents the y-intercept of the equation",
"type": "multiple_choice",
"created_at": "2024-06-26T09:57:23.291358+00:00"
}
Retrieve all responses for an assessment
This endpoint allows you to retrieve all responses for a specified assignment and student. Refer to the list at the top of this page to see which properties are included with course objects.
Request
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.courses.getAssessmentQuestions('118a2584-44d8-4039-a082-bca87bdd5ffd')
Response
[
{
"id": "3ae3641b-9de1-4a07-be5f-b54f788593d6",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "b882aa78-9c65-4446-9174-9bbd8ec26cb6",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 7,
"response": "Response to question",
"type": "free_response",
"feedback": null,
"created_at": "2024-06-26T10:23:11.908718+00:00"
},
{
"id": "bee32340-328f-410a-8737-174555df1b92",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "fe7d5092-c017-4d5e-827e-8a14603bf05e",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 2,
"response": ["slope", "intercept"],
"type": "fill_in",
"feedback": null,
"created_at": "2024-06-26T12:06:14.908718+00:00"
},
{
"id": "0c150b56-b85c-4daf-8966-464a5f27395c",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"response": {
"Variable": "Number used to multiply a variable",
"Coefficient": "A symbol for an unknown value",
"Constants": "A number on its own"
},
"type": "matching",
"feedback": null,
"created_at": "2024-06-26T15:43:32.827358+00:00"
},
{
"id": "8a413cf7-347d-4ede-949a-9394e7307a26",
"question_id": "858370d5-14f4-4ac6-bdad-149a252912b1",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 0,
"response": ["b"],
"feedback": "the variable b is a constant that represents the y-intercept of the equation",
"type": "multiple_choice",
"created_at": "2024-06-26T09:57:23.291358+00:00"
}
]
Update a response
This endpoint allows you to update a a specified response. The response's id, assessment id, question id, student id, and type can't be updated.
Optional parameters
- Name
earned_points- Type
- int
- Description
Number of points the response has earned. Affects the assignment's earned grade.
- Name
feedback- Type
- string
- Description
Helpful tips or comments a grader can leave for the student.
Free response additional optional properties
- Name
reponse- Type
- string
- Description
Student's written response to a free response question.
Fill-in additional optional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a fill in question. The order matters and must match the order for the correct answer to the question. This is not case-sensitive.
Matching additional optional properties
- Name
response- Type
- object
- Description
Object that matches strings to strings and is the response of the student to a matching question.
Multiple choice additional optional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a multiple choice or multi-select question.
Request
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.courses.update("0215c090-6c68-46ee-932e-47be4c8e4a76", {
earned_points: 2,
response: ["m"]
})
Response
{
"id": "8a413cf7-347d-4ede-949a-9394e7307a26",
"question_id": "858370d5-14f4-4ac6-bdad-149a252912b1",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 2,
"response": ["m"],
"feedback": "the variable b is a constant that represents the y-intercept of the equation",
"type": "multiple_choice",
"created_at": "2024-06-26T09:57:23.291358+00:00"
}
Grade a response
This endpoint can be used as an alternative to the POST and PATCH endpoints for responses. This endpoint will automatically grade a response based on a given response object. If you want to update an existing response, the response object must contain the response's id. Otherwise, the ID can be discluded and a new graded response object will be made. Although free response properties are included, automatic grading doesn't work on free response questions and you should use the create or update for free response questions instead.
Required parameters
- Name
assessment_id- Type
- string
- Description
Unique identifier for the assessment the response is connected to.
- Name
question_id- Type
- string
- Description
Unique identifier for the question the response is connected to.
- Name
student_id- Type
- string
- Description
Unique identifier for the student the response is connected to.
- Name
type- Type
- string
- Description
Type of question the response is responding to, can be free_response, fill_in, matching, or multiple_choice.
Free response additional optional properties
- Name
reponse- Type
- string
- Description
Student's written response to a free response question.
Fill-in additional optional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a fill in question. The order matters and must match the order for the correct answer to the question. This is not case-sensitive.
Matching additional optional properties
- Name
response- Type
- object
- Description
Object that matches strings to strings and is the response of the student to a matching question.
Multiple choice additional optional properties
- Name
response- Type
- string[]
- Description
Array of student's response to a multiple choice or multi-select question.
Request for new response
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.courses.gradeResponse({
assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
question_id: "273a0384-2408-4eb3-96e4-8c893c22c000",
student_id: "627a64c9-645a-491f-a851-b59331248af7",
response: ["point", "equation", "horizontal axis", "vertical axis"],
type: "matching",
feedback: null,
})
Response for new response
{
"id": "8356581c-a0ba-448c-a7f5-0163930ee9b5",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 4,
"response": ["point", "equation", "horizontal axis", "vertical axis"],
"type": "matching",
"feedback": null,
"created_at": "2024-06-26T16:57:02.809358+00:00"
}
Request for existing response
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.courses.gradeResponse({
id: "0c150b56-b85c-4daf-8966-464a5f27395c",
assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
question_id: "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
student_id: "627a64c9-645a-491f-a851-b59331248af7",
response: {
"Variable": "Number used to multiply a variable",
"Coefficient": "A symbol for an unknown value",
"Constants": "A number on its own"
},
type: "matching",
feedback: null,
})
Response for existing response
{
"id": "0c150b56-b85c-4daf-8966-464a5f27395c",
"assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
"question_id": "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
"student_id": "627a64c9-645a-491f-a851-b59331248af7",
"earned_points": 2,
"response": {
"Variable": "Number used to multiply a variable",
"Coefficient": "A symbol for an unknown value",
"Constants": "A number on its own"
},
"type": "matching",
"feedback": null,
"created_at": "2024-06-26T15:43:32.827358+00:00"
}
Delete a response
This endpoint allows you to delete a response provided its id and type. The type can be free_response, fill_in, matching, or multiple_choice. THe type must be the correct type for this endpoint to work properly.
Request
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.courses.delete('0c150b56-b85c-4daf-8966-464a5f27395c', 'matching')