> ## Documentation Index > Fetch the complete documentation index at: https://docs.timeback.com/llms.txt > Use this file to discover all available pages before exploring further. # Search and filter assessment items > Search and retrieve assessment items (questions) with advanced filtering capabilities. Supports text search across titles and identifiers, filtering by type, sorting, and pagination. Assessment items are the core content units that contain questions, answer choices, and scoring logic. ## OpenAPI ````yaml /openapi/beyond-ai/qti-api.yaml get /assessment-items openapi: 3.1.0 info: title: QTI API version: 1.0.0 description: >- A robust assessment engine implementing the QTI 3.0 specification, designed for creating, managing, and delivering educational assessments. servers: - url: https://qti.alpha-1edtech.ai/api description: Main Server security: - OAuth2: [] - MCP: [] tags: - name: Validation description: >- Validate XML strings against QTI compliant XSD files. XSD version supported is 3.0.0 (3p0) - name: Feedback description: Feedback for questions and lessons - name: Assessment Test Management description: >- Enables the management of Assessment Tests. Assessment Tests are the main entities that contain Assessment Test Parts, Sections, and Assessment Items. - name: Test Part Management description: >- Enables the management of Test Parts. Assessment Test Parts are used to group sections inside of an Assessment Test. - name: Section Management description: >- Enables the management of Sections. Assessment Sections are used to group Assessment Items. - name: Assessment Item Management description: >- Enables the management of Assessment ITems. Assessment Items are made up of QTI Interactions (e.g. questions, multiple choice, etc.). - name: Stimulus Management description: >- Enables the management of Stimuli. Stimuli are shared content pieces (text, images, audio, video) that provide context for assessment items and can be referenced by multiple questions. paths: /assessment-items: get: tags: - Assessment Item Management summary: Search and filter assessment items description: >- Search and retrieve assessment items (questions) with advanced filtering capabilities. Supports text search across titles and identifiers, filtering by type, sorting, and pagination. Assessment items are the core content units that contain questions, answer choices, and scoring logic. operationId: searchAssessmentItems parameters: - in: query name: query description: >- Search title and identifier fields using a search term. This is a fuzzy search. schema: type: string description: >- Search title and identifier fields using a search term. This is a fuzzy search. - in: query name: page description: Page number for pagination schema: type: string default: '1' description: Page number for pagination example: 1 - in: query name: limit description: Number of items per page schema: type: string default: '10' description: Number of items per page example: 10 - in: query name: sort description: Field to sort by schema: type: string enum: - title - identifier - type - createdAt - updatedAt default: createdAt description: Field to sort by example: createdAt - in: query name: order description: Sort order schema: type: string enum: - asc - desc default: desc description: Sort order example: desc - in: query name: filter description: >- Advanced filter expression using =, !=, >, >=, <, <=, ~ and logical AND/OR. Example: type='choice' schema: type: string description: >- Advanced filter expression using =, !=, >, >=, <, <=, ~ and logical AND/OR. Example: type='choice' example: type='choice' - in: query name: subject description: >- Filter by subject from qti-parent-tests array (indexed for fast lookup) schema: type: string description: >- Filter by subject from qti-parent-tests array (indexed for fast lookup) example: Math - in: query name: grade description: >- Filter by grade from qti-parent-tests array (indexed for fast lookup) schema: type: string description: >- Filter by grade from qti-parent-tests array (indexed for fast lookup) example: '5' - in: query name: type description: Filter by question type - native field with simple index schema: type: string description: Filter by question type - native field with simple index example: choice - in: query name: search description: Full-text search on qti-prompt-text field (uses text index) schema: type: string description: Full-text search on qti-prompt-text field (uses text index) example: pythagorean responses: '200': description: List of assessment items with pagination metadata content: application/json: schema: type: object properties: items: type: array items: type: object properties: identifier: type: string description: >- Unique identifier for the entity on the service provider. title: type: string description: >- Human-readable title of the entity on the service provider. type: type: string enum: - choice - text-entry - extended-text - inline-choice - match - order - associate - select-point - graphic-order - graphic-associate - graphic-gap-match - hotspot - hottext - slider - drawing - media - upload description: >- Assessment item interaction types that are supported by the service provider. customInteractionTypeIdentifier: type: string description: >- For portable-custom interactions, the custom-interaction-type-identifier attribute from the QTI XML element. qtiVersion: type: string default: '3.0' description: QTI version of the assessment item timeDependent: type: boolean default: false description: >- Indicates whether the candidate's response time affects the scoring or outcome of this assessment item. When true, timing data is used in response processing calculations. adaptive: type: boolean default: false description: >- Indicates whether this assessment item adapts its presentation or behavior based on the candidate's responses. Adaptive items can modify their content, difficulty, or available options during the assessment session. responseDeclarations: type: array items: type: object properties: identifier: type: string description: >- Unique identifier for this response variable within the item; must be distinct from other item variables and cannot use reserved names (completionStatus, numAttempts, duration). cardinality: type: string enum: - single - multiple - ordered - record description: >- Specifies how many values the response variable can hold and whether order matters. baseType: type: string enum: - identifier - boolean - integer - float - string - point - pair - directedPair - duration - file - uri description: >- Primitive data type for each answer stored in the variable (e.g., integer, string, boolean). Omit when cardinality is 'record', because each field in a record may have its own type. correctResponse: type: object properties: value: type: array items: type: string required: - value description: >- Optional model answer; must conform to the variable's cardinality (single = one value, multiple/ordered = ordered or unordered list); omit when no optimal answer exists (e.g., essays); delivery engines may display it as the solution in review mode. required: - identifier - cardinality - correctResponse outcomeDeclarations: type: array items: type: object properties: identifier: type: string description: >- Unique identifier for this response variable within the item; must be distinct from other item variables and cannot use reserved names (completionStatus, numAttempts, duration). cardinality: type: string enum: - single - multiple - ordered - record description: >- Specifies how many values the response variable can hold and whether order matters. baseType: type: string enum: - identifier - boolean - integer - float - string - point - pair - directedPair - duration - file - uri description: >- Primitive data type for each answer stored in the variable (e.g., integer, string, boolean). Omit when cardinality is 'record', because each field in a record may have its own type. required: - identifier - cardinality responseProcessing: type: object properties: templateType: type: string enum: - match_correct - map_response description: >- Response processing template type. 'match_correct' compares the candidate's response directly against the correct response and assigns binary feedback. 'map_response' uses mapping rules to assign scores and feedback based on response values. responseDeclarationIdentifier: type: string description: >- Identifier of the response declaration that this response processing rule applies to. Must match an existing responseDeclaration identifier within the same assessment item. outcomeIdentifier: type: string description: >- Identifier of the outcome variable that will be set by this response processing rule. Common values include 'SCORE' for numeric scoring or 'FEEDBACK' for feedback identifiers. correctResponseIdentifier: type: string description: >- Identifier value assigned to the outcome variable when the candidate's response is evaluated as correct. Used primarily with match_correct template type. incorrectResponseIdentifier: type: string description: >- Identifier value assigned to the outcome variable when the candidate's response is evaluated as incorrect. Used primarily with match_correct template type. inlineFeedback: type: object properties: outcomeIdentifier: type: string description: >- Identifier of the outcome variable to be set with the inline feedback value. variableIdentifier: type: string description: >- Identifier of the variable whose value will be assigned to the outcome variable during response processing. required: - outcomeIdentifier - variableIdentifier description: >- Optional inline feedback configuration that sets an outcome variable based on another variable's value during response processing. required: - templateType - responseDeclarationIdentifier - outcomeIdentifier - correctResponseIdentifier - incorrectResponseIdentifier description: >- Response processing is the process by which the Delivery Engine assigns outcomes based on the candidate's responses. The outcomes may be used to provide feedback to the candidate. Response processing must only take place in direct response to a user action or in response to some expected event, such as the end of a test. metadata: type: object properties: subject: type: string description: Subject area for the assessment item example: Math grade: type: string enum: - '-1' - '0' - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '12' - '13' description: >- Grade level for the assessment item. Must use a value from K-12 example: '10' difficulty: type: string enum: - easy - medium - hard description: Difficulty level of the assessment item example: easy learningObjectiveSet: type: array items: type: object properties: source: type: string description: >- The source of the learning objective set or learning standards. example: CASE learningObjectiveIds: type: array items: type: string description: >- Array of learning objective identifiers. If source is 'CASE', these can be the CFItem sourcedIds or CFItem's Human Coding Schema. example: - D1.5.6-8 - C2.6.7-8 - E3.1.2-3 required: - source - learningObjectiveIds description: >- Learning objectives associated with this assessment item example: - source: CASE learningObjectiveIds: - id-123 - id-456 - id-789 additionalProperties: true description: >- Additional custom metadata for assessment items with validation for specific fields used by external applications rawXml: type: string description: >- Raw XML representation of the entity, automatically generated from the JSON or XML sent when creating entities on the service provider. The rawxml field will contain all content sent when creating the entity on the service provider. This field is stable and should be used when working within this QTI API. content: type: object properties: qti-assessment-item: type: object properties: _attributes: type: object properties: xmlns: type: string xmlns:xsi: type: string xsi:schemaLocation: type: string identifier: type: string title: type: string adaptive: type: string time-dependent: type: string required: - xmlns - xmlns:xsi - xsi:schemaLocation - identifier - title - adaptive - time-dependent qti-response-declaration: type: array items: type: object properties: _attributes: type: object properties: identifier: type: string cardinality: type: string baseType: type: string required: - identifier - cardinality - baseType qti-correct-response: type: object properties: qti-value: type: array items: type: string required: - qti-value required: - _attributes - qti-correct-response qti-outcome-declaration: type: array items: type: object properties: _attributes: type: object properties: identifier: type: string cardinality: type: string baseType: type: string required: - identifier - cardinality - baseType required: - _attributes qti-assessment-stimulus-ref: type: array items: type: object properties: _attributes: type: object properties: identifier: type: string href: type: string title: type: string required: - identifier - href - title required: - _attributes qti-item-body: {} qti-response-processing: {} required: - _attributes - qti-response-declaration - qti-outcome-declaration required: - qti-assessment-item description: >- Parsed XML content generated by the service provider. For production use, rawXml is recommended over this parsed structure. modalFeedback: type: array items: type: object properties: outcomeIdentifier: type: string description: >- Identifier of the outcome variable that controls when this feedback is displayed. The feedback is shown or hidden based on the value of this outcome variable after response processing. identifier: type: string description: >- Unique identifier for this specific feedback element within the assessment item. Used to reference and control this particular piece of feedback. showHide: type: string enum: - show - hide description: >- Determines the feedback visibility behavior. 'show' displays the feedback when the outcome variable matches the identifier, 'hide' conceals it when the outcome variable matches. content: type: string description: >- The HTML or text content to be displayed as feedback to the candidate. title: type: string description: >- Optional title displayed in the modal feedback dialog header. Only used with modal feedback presentations. required: - outcomeIdentifier - identifier - showHide - content - title description: >- Modal feedback shown to candidates in popup dialogs immediately following response processing. Cannot contain interaction elements and is displayed based on outcome variable values. feedbackInline: type: array items: type: object properties: outcomeIdentifier: type: string description: >- Identifier of the outcome variable that controls when this feedback is displayed. The feedback is shown or hidden based on the value of this outcome variable after response processing. identifier: type: string description: >- Unique identifier for this specific feedback element within the assessment item. Used to reference and control this particular piece of feedback. showHide: type: string enum: - show - hide description: >- Determines the feedback visibility behavior. 'show' displays the feedback when the outcome variable matches the identifier, 'hide' conceals it when the outcome variable matches. content: type: string description: >- The HTML or text content to be displayed as feedback to the candidate. class: type: array items: type: string description: >- CSS class names applied to the feedback element for styling purposes. Multiple classes can be specified for flexible presentation control. required: - outcomeIdentifier - identifier - showHide - content - class description: >- Inline feedback embedded within interaction elements, displayed alongside choices or input areas. Provides contextual feedback. feedbackBlock: type: array items: type: object properties: outcomeIdentifier: type: string description: >- Identifier of the outcome variable that controls when this feedback is displayed. The feedback is shown or hidden based on the value of this outcome variable after response processing. identifier: type: string description: >- Unique identifier for this specific feedback element within the assessment item. Used to reference and control this particular piece of feedback. showHide: type: string enum: - show - hide description: >- Determines the feedback visibility behavior. 'show' displays the feedback when the outcome variable matches the identifier, 'hide' conceals it when the outcome variable matches. content: type: string description: >- The HTML or text content to be displayed as feedback to the candidate. class: type: array items: type: string description: >- CSS class names applied to the feedback element for styling purposes. Multiple classes can be specified for flexible presentation control. required: - outcomeIdentifier - identifier - showHide - content - class description: >- Inline feedback embedded within interaction elements, displayed alongside choices or input areas. Provides contextual feedback. createdAt: type: string format: date-time description: ISO 8601 timestamp when the entity was created updatedAt: type: string format: date-time description: ISO 8601 timestamp when the entity was last updated __v: type: number description: >- MongoDB version key for optimistic concurrency control required: - identifier - title - type - qtiVersion - timeDependent - adaptive - rawXml - content - createdAt - updatedAt description: Array of assessment items that match the search criteria total: type: number description: >- The total number of entities that match the search criteria. page: type: number description: >- The page number of the entities that match the search criteria. default: 1 pages: type: number description: >- The total number of pages of entities that match the search criteria. limit: type: number description: The number of entities per page. default: 10 sort: type: string description: The field to sort the entities by. order: type: string enum: - asc - desc description: The order to sort the entities by. Either 'asc' or 'desc'. required: - items - total - page - pages - limit - sort - order description: >- Paginated response containing all assessment items available on the service provider with navigation metadata '400': description: Validation failed content: application/json: schema: type: object properties: error: type: string description: High-level error message code: type: string description: Machine code identifying error type details: type: string description: Additional human details meta: type: object properties: issues: type: array items: type: object properties: field: type: string description: Parameter name message: type: string description: Validation message code: type: string description: Zod issue code required: - field - message - code description: Array of individual validation errors eventId: type: string description: Sentry event id required: - issues description: Structured metadata from validation layer required: - error - code - meta '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string description: Error type identifier message: type: string description: Human-readable error message eventId: type: string description: Sentry event ID for error tracking details: type: string description: Stack trace or additional error details required: - error - message - details description: Internal server error response components: securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: scopes: https://purl.imsglobal.org/spec/qti/v3/scope/readonly: Read access to QTI https://purl.imsglobal.org/spec/qti/v3/scope/createput: Create and update access to QTI https://purl.imsglobal.org/spec/qti/v3/scope/delete: Delete access to QTI tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token MCP: type: oauth2 flows: authorizationCode: authorizationUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/authorize tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token scopes: https://purl.imsglobal.org/spec/qti/v3/scope/readonly: Read access to QTI ````