Questions

This page will go into detail on the properties of the questions class as well as the different endpoints used to query, create, update, and delete questions.

The question model

This model details all of the properties of a question. Questions can vary in type and can have different additional properties based on their types

General Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the question.

  • Name
    assessment_id
    Type
    string
    Description

    Unique identifiier for the assessment the question is a part of.

  • Name
    number
    Type
    int
    Description

    The number of the question on the assessment.

  • Name
    content
    Type
    string
    Description

    What the question is asking.

  • Name
    point_value
    Type
    int
    Description

    How many points this question is worth. Affects the max_grade of the assignment.

  • Name
    type
    Type
    string
    Description

    The question type, which determines how answers are stored. type can have 4 values: free_response, fill_in, matching, or multiple_choice.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the question was created. Generated automatically at creation in ISO 8601 format.

Free response additional properties

Free response questions don't have any extra properties since the format is a big textbox for the test taker.

Fill-in additional properties

  • Name
    answer_key
    Type
    string[]
    Description

    array of the correct answers to fill in the blank questions. This array allows there to be questions with multiple blanks.

Matching additional properties

  • Name
    choices
    Type
    object
    Description

    A hashmap containing the correct pairings for a matching question.

Mutliple choice additional properties

  • Name
    choices
    Type
    string[]
    Description

    Available choices to select for a multiple choice question.

  • Name
    correct_choice
    Type
    string[]
    Description

    The correct choice/choices for the question.

  • Name
    multi_select_grading_method
    Type
    string
    Description

    The different ways a multi select multiple choice problem can be graded. Default is null for multiple choice questions that aren't multi-select
    ALL_OR_NOTHING: Points are only earned when all correct answers are selected and incorrect answers are left blank, otherwise no points are awarded.
    CORRECT_SELECTIONS: Partial credit is given for each correct answer chosen and each incorrect answer left blank.
    LIMIT_SELECTIONS: Students are limited to choosing only the right number of answers(ex. if there are only 2 correct choices, students can only choose 2 answers), partial credit is given for each answer chosen correctly. RIGHT_MINUS_WRONG: Students earn partial credit for each correct answer selected and each incorrect answer left blank, but will lose partial credit for incorrect answer choices and leaving correct answers blank.

POST/v1/assessments/questions/create

Create a question

This endpoint allows you to add a new question to the database. To add a question, you must provide a proper Question object as the request body. Questions must have the additional properties of their respective type to be valid. For example, a matching question must have a choices property which is an object.

Required parameters

  • Name
    assessment_id
    Type
    string
    Description

    Unique identifiier for the assessment the question is a part of.

  • Name
    number
    Type
    int
    Description

    The number of the question on the assessment.

  • Name
    content
    Type
    string
    Description

    What the question is asking.

  • Name
    point_value
    Type
    int
    Description

    How many points this question is worth. Affects the max_grade of the assignment..

  • Name
    type
    Type
    string
    Description

    The question type, which determines how answers are stored. type can have 4 values: free_response, fill_in, matching, or multiple_choice.

Optional parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier for the question.

Fill in additional required parameters

  • Name
    answer_key
    Type
    string[]
    Description

    array of the correct answers to fill in the blank questions. This array allows there to be questions with multiple blanks.

Matching additional required parameters

  • Name
    choices
    Type
    object
    Description

    A hashmap containing the correct pairings for a matching question.

Multiple choice additional required parameters

  • Name
    choices
    Type
    string[]
    Description

    Available choices to select for a multiple choice question.

  • Name
    correct_choice
    Type
    string[]
    Description

    The correct choice/choices for the question.

Multiple choice additional optional parameters

  • Name
    multi_select_grading_method
    Type
    string
    Description

    The different ways a multi select multiple choice problem can be graded: ALL_OR_NOTHING, CORRECT_SELECTIONS, LIMIT_SELECTIONS, or RIGHT_MINUS_WRONG. refer to multiple choice additional properties for more info on these grading methods.

Request for free response

POST
/v1/assessments/questions/create
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.question.createQuestion({
  id: "b882aa78-9c65-4446-9174-9bbd8ec26cb6",
  assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
  number: 1,
  content: "Solve for x. 2x-7=3x+4",
  point_value: 8,
  type: "free_response"
})

Response for free response

{
  "id": "b882aa78-9c65-4446-9174-9bbd8ec26cb6",
  "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
  "number": 1,
  "content": "Solve for x. 2x-7=3x+4",
  "point_value": 8,
  "type": "free_response",
  "created_at": "2024-06-25T15:22:14.908718+00:00"
}

Request for fill-in

POST
/v1/assessments/questions/create
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.question.createQuestion({
  id: "fe7d5092-c017-4d5e-827e-8a14603bf05e",
  assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
  number: 2,
  content: "the equation y=mx+b is in []-[] form.",
  point_value: 2,
  type: "fill_in",
  answer_key: ["slope", "intercept"]
})

Response for fill-in

{
  "id": "fe7d5092-c017-4d5e-827e-8a14603bf05e",
  "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
  "number": 2,
  "content": "the equation y=mx+b is in []-[] form.",
  "point_value": 2,
  "type": "fill_in",
  "answer_key": ["slope", "intercept"],
  "created_at": "2024-06-25T15:25:14.908718+00:00"
}

Request for matching

POST
/v1/assessments/questions/create
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.question.createQuestion({
  assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
  number: 3,
  content: "match these terms to their definitions.",
  point_value: 6,
  type: "matching",
  choices: {
    "Variable": "A symbol for an unknown value",
    "Coefficient": "Number used to multiply a variable",
    "Constants": "A number on its own"
  }
})

Response for matching

{
  "id": "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
  "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
  "number": 3,
  "content": "match these terms to their definitions.",
  "point_value": 6,
  "type": "matching",
  "choices": {
    "Variable": "A symbol for an unknown value",
    "Coefficient": "Number used to multiply a variable",
    "Constants": "A number on its own"
  },
  "created_at": "2024-06-25T15:30:32.827358+00:00"
}

Request for multiple choice

POST
/v1/assessments/questions/create
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.question.createQuestion({
  assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
  number: 4,
  content: "Which variable in y=mx+b represents the slope?",
  point_value: 2,
  type: "multiple_choice",
  choices: ["y", "m", "x", "b"],
  correct_choice: ["m"]
})

Response for multiple choice

{
  "id": "858370d5-14f4-4ac6-bdad-149a252912b1",
  "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
  "number": 4,
  "content": "Which variable in y=mx+b represents the slope?",
  "point_value": 2,
  "type": "multiple_choice",
  "choices": ["y", "m", "x", "b"],
  "correct_choice": ["m"],
  "multi_select_grading_method": null,
  "created_at": "2024-06-25T15:32:58.291358+00:00"
}

Request for multi-select

POST
/v1/assessments/questions/create
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.question.createQuestion({
  assessment_id: "118a2584-44d8-4039-a082-bca87bdd5ffd",
  number: 5,
  content: "What terms are parts on a coordinate grid? Select all that apply.",
  point_value: 6,
  type: "multiple_choice",
  choices: ["point", "equation", "horizontal axis", "variable", "vertical axis", "quadratic equation"],
  correct_choice: ["point", "horizontal axis", "vertical axis"],
  multi_select_grading_method: "RIGHT_MINUS_WRONG"
})

Response for multi-select

{
  "id": "273a0384-2408-4eb3-96e4-8c893c22c000",
  "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
  "number": 5,
  "content": "What terms are parts on a coordinate grid? Select all that apply.",
  "point_value": 6,
  "type": "multiple_choice",
  "choices": ["point", "equation", "horizontal axis", "variable", "vertical axis", "quadratic equation"],
  "correct_choice": ["point", "horizontal axis", "vertical axis"],
  "multi_select_grading_method": "RIGHT_MINUS_WRONG",
  "created_at": "2024-06-25T15:34:45.121389+00:00"
}

Retrieve all questions for an assessment

This endpoint allows you to retrieve all questions for a specified assignment sorted by their number. Refer to the list at the top of this page to see which properties are included with course objects.

Request

GET
/v1/assessments/questions/118a2584-44d8-4039-a082-bca87bdd5ffd
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.getAssessmentQuestions('118a2584-44d8-4039-a082-bca87bdd5ffd')

Response

[
  {
    "id": "b882aa78-9c65-4446-9174-9bbd8ec26cb6",
    "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
    "number": 1,
    "content": "Solve for x. 2x-7=3x+4",
    "point_value": 8,
    "type": "free_response",
    "created_at": "2024-06-25T15:22:14.908718+00:00"
  },
  {
    "id": "fe7d5092-c017-4d5e-827e-8a14603bf05e",
    "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
    "number": 2,
    "content": "the equation y=mx+b is in []-[] form.",
    "point_value": 2,
    "type": "fill_in",
    "answer_key": ["slope", "intercept"],
    "created_at": "2024-06-25T15:25:14.908718+00:00"
  },
  {
    "id": "60f1f1f6-3165-4deb-ab72-0b8c571bf819",
    "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
    "number": 3,
    "content": "match these terms to their definitions.",
    "point_value": 6,
    "type": "matching",
    "choices": {
      "Variable": "A symbol for an unknown value",
      "Coefficient": "Number used to multiply a variable",
      "Constants": "A number on its own"
    },
    "created_at": "2024-06-25T15:30:32.827358+00:00"
  },
  {
    "id": "858370d5-14f4-4ac6-bdad-149a252912b1",
    "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
    "number": 4,
    "content": "Which variable in y=mx+b represents the slope?",
    "point_value": 2,
    "type": "multiple_choice",
    "choices": ["y", "m", "x", "b"],
    "correct_choice": ["m"],
    "multi_select_grading_method": null,
    "created_at": "2024-06-25T15:32:58.291358+00:00"
  },
  {
    "id": "273a0384-2408-4eb3-96e4-8c893c22c000",
    "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
    "number": 5,
    "content": "What terms are parts on a coordinate grid? Select all that apply.",
    "point_value": 6,
    "type": "multiple_choice",
    "choices": ["point", "equation", "horizontal axis", "variable", "vertical axis", "quadratic equation"],
    "correct_choice": ["point", "horizontal axis", "vertical axis"],
    "multi_select_grading_method": "RIGHT_MINUS_WRONG",
    "created_at": "2024-06-25T15:34:45.121389+00:00"
  }
]
PATCH/v1/assessments/questions/update/:id

Update a question

This endpoint allows you to update a a specified question. The question's id, assessment id, and type can't be updated.

Optional parameters

  • Name
    number
    Type
    int
    Description

    The number of the question on the assessment.

  • Name
    content
    Type
    string
    Description

    What the question is asking.

  • Name
    point_value
    Type
    int
    Description

    How many points the question is worth. Affects the max_grade of the assignment.

Fill in additional optional parameters

  • Name
    answer_key
    Type
    string[]
    Description

    array of the correct answers to fill in the blank questions. This array allows there to be questions with multiple blanks.

Matching additional optional parameters

  • Name
    choices
    Type
    object
    Description

    A hashmap containing the correct pairings for a matching question.

Multiple choice additional optional parameters

  • Name
    choices
    Type
    string[]
    Description

    Available choices to select for a multiple choice question.

  • Name
    correct_choice
    Type
    string[]
    Description

    The correct choice/choices for the question.

  • Name
    multi_select_grading_method
    Type
    string
    Description

    The different ways a multi select multiple choice problem can be graded: ALL_OR_NOTHING, CORRECT_SELECTIONS, LIMIT_SELECTIONS, or RIGHT_MINUS_WRONG. refer to multiple choice additional properties for more info on these grading methods.

Request

PATCH
/v1/assessments/questions/update/fe7d5092-c017-4d5e-827e-8a14603bf05e
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.update("0215c090-6c68-46ee-932e-47be4c8e4a76", {
  point_value: 3
})

Response

{
  "id": "fe7d5092-c017-4d5e-827e-8a14603bf05e",
  "assessment_id": "118a2584-44d8-4039-a082-bca87bdd5ffd",
  "number": 2,
  "content": "the equation y=mx+b is in []-[] form.",
  "point_value": 3,
  "type": "fill_in",
  "answer_key": ["slope", "intercept"],
  "created_at": "2024-06-25T15:25:14.908718+00:00"
}
DELETE/v1/assessments/questions/delete/:id?type=value

Delete a question

This endpoint allows you to delete a question provided its id and type. The type can be free_response, fill_in, matching, or multiple_choice. THe type must be the correct tyep for this endpoint to work properly.

Request

DELETE
/v1/assessments/questions/delete/273a0384-2408-4eb3-96e4-8c893c22c000?type=multiple_choice
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.delete('273a0384-2408-4eb3-96e4-8c893c22c000', 'multiple_choice')

Was this page helpful?