> ## 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. # Check if a student is eligible to self-request a test-out > Checks whether a student can self-request an assessment to test out of their current grade level for a given subject. The endpoint performs the following checks in order: 1. Verifies the student has an active enrollment for the subject in a non-placeholder course (endDate is null or in the future, and course metadata does not have placementPlaceholder set to true) 2. Fetches the student's highest grade mastered for the subject 3. If the highest grade mastered is available, queries the assessment_results table for any existing fully-graded self-elected test-out at the next grade level (highestGradeMastered + 1) 4. If the highest grade mastered is not available, falls back to the active course sequence to determine the lowest assessment grade for the subject and checks for a prior test-out at that grade Returns `eligible: true` if no prior test-out exists at the target grade. Returns `eligible: false` with a reason if the student has no qualifying active enrollment, or has already tested out. Subject matching is case-insensitive. Supported subjects: Math, Reading, Language, Science, Writing, Vocabulary. ## OpenAPI ````yaml /openapi/beyond-ai/powerpath-api.yaml get /powerpath/test-out/getTestOutEligibility/{studentId}/{subject} openapi: 3.1.0 info: title: PowerPath API version: 1.0.0 description: > TimeBack PowerPath 100 API # Authentication All endpoints require authentication using the `Authorization: Bearer ` header. The token can be obtained with: ``` curl -X POST https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=&client_secret=" ``` Use the correct IDP server depending on the environment you're using: IDP Server for this environment: ``` https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com ``` Reach out to the platform team to get a client/secret pair for your application. # Pagination Our API uses offset pagination for list endpoints. Paginated responses include the following fields: - `offset`: Offset for the next page of results - `limit`: Number of items per page (default: 100, maximum: 3000) **Note:** While the OneRoster specification does not define a maximum limit, this implementation enforces a maximum of 3000 items per page to prevent abuse and ensure optimal performance. Example request: ``` GET /ims/oneroster/rostering/v1p2/users?offset=20&limit=20 ``` All listing endpoints support offset pagination. # Filtering All listing endpoints support filtering using the `filter` query parameter, following 1EdTech's filtering specification. The filter should be a string with the following format: ``` ?filter=[field][operator][value] ``` Example request: ``` GET /ims/oneroster/rostering/v1p2/users?filter=status='active' ``` Example request with multiple filters: ``` GET /ims/oneroster/rostering/v1p2/users?filter=status='active' AND name='John' ``` **Filtering by nested relations is not supported**. # Sorting All listing endpoints support sorting using the `sort` and `orderBy` query parameters, following 1EdTech's sorting specification Example request: ``` GET /ims/oneroster/rostering/v1p2/users?sort=lastName&orderBy=asc ``` # Proprietary Extensions This implementation includes proprietary extensions that extend beyond the official OneRoster 1.2 specification to provide additional functionality. ## Search Parameter In addition to the standard `filter` parameter, this implementation provides a `search` query parameter for simplified free-text searching: ``` GET /ims/oneroster/rostering/v1p2/users?search=john ``` **Purpose**: The `search` parameter enables convenient text-based queries across multiple fields simultaneously, whereas the standard `filter` parameter requires specifying exact field names and operators: ``` # Search parameter - searches across multiple fields automatically GET /ims/oneroster/rostering/v1p2/users?search=john # Equivalent using standard filter parameter GET /ims/oneroster/rostering/v1p2/users?filter=givenName~'john' OR familyName~'john' ``` The `search` parameter performs case-insensitive partial matching across predefined fields for each endpoint, providing a more user-friendly querying experience. ## OneRoster 1.2 Standard Parameters The official OneRoster 1.2 specification defines these standard parameters: - `limit` - pagination limit - `offset` - pagination offset - `sort` - field to sort by - `orderBy` - sort direction (asc/desc) - `filter` - filtering expression - `fields` - field selection ## Affected Endpoints The proprietary `search` parameter is available on the following endpoints: **Rostering API**: - `GET /ims/oneroster/rostering/v1p2/academicSessions/` - `GET /ims/oneroster/rostering/v1p2/classes/` - `GET /ims/oneroster/rostering/v1p2/classes/{classSourcedId}/students` - `GET /ims/oneroster/rostering/v1p2/classes/{classSourcedId}/teachers` - `GET /ims/oneroster/rostering/v1p2/courses/` - `GET /ims/oneroster/rostering/v1p2/courses/{courseSourcedId}/classes` - `GET /ims/oneroster/rostering/v1p2/demographics/` - `GET /ims/oneroster/rostering/v1p2/enrollments/` - `GET /ims/oneroster/rostering/v1p2/schools/{schoolSourcedId}/classes/{classSourcedId}/students` - `GET /ims/oneroster/rostering/v1p2/users/` **Gradebook API**: - `GET /ims/oneroster/gradebook/v1p2/assessmentLineItems/` - `GET /ims/oneroster/gradebook/v1p2/assessmentResults/` - `GET /ims/oneroster/gradebook/v1p2/classes/{classSourcedId}/students/{studentSourcedId}/results` - `GET /ims/oneroster/gradebook/v1p2/results/` **Resources API**: - `GET /ims/oneroster/resources/v1p2/resources/` ## Parameter Usage Guide ### Filter Parameter The standard `filter` parameter provides precise control over queries using these operators: - `=` - Exact match - `!=` - Not equal - `~` - Contains (case-insensitive) - `>`, `>=`, `<`, `<=` - Comparison operators - `@` - In list (comma-separated values) ### Logical Operators Combine multiple conditions in filter expressions: - `AND` - Both conditions must be true - `OR` - Either condition must be true ### Usage Examples ```bash # Simple text search across multiple fields GET /users?search=john # Equivalent precise filtering GET /users?filter=givenName~'john' OR familyName~'john' # Complex filtering with multiple conditions GET /users?filter=status='active' AND givenName~'john' # Advanced filtering with different operators GET /users?filter=dateLastModified>'2023-01-01' AND status='active' ``` ## Search Fields by Endpoint Different endpoints search across these predefined fields: - **Users**: `givenName`, `familyName`, `email` - **Courses**: `title`, `courseCode` - **Classes**: `title` - **Organizations**: `name` ## Interoperability Notes The `search` parameter is a proprietary extension specific to this implementation. Other OneRoster-compliant systems may only support the standard `filter` parameter. When building applications that need to work with multiple OneRoster providers, consider using the standard filtering approach. ## Additional Schema Fields ### AssessmentLineItem Extensions The AssessmentLineItem schema includes two proprietary fields that extend curriculum mapping capabilities: #### Component Field - **Field**: `component` - **Type**: Object reference (`{ sourcedId: string }`) - **Purpose**: Direct association between assessment line items and course components, enabling enhanced curriculum mapping and learning pathway tracking. #### ComponentResource Field - **Field**: `componentResource` - **Type**: Object reference (`{ sourcedId: string }`) - **Purpose**: Direct association between assessment line items and specific learning resources, supporting detailed content-to-assessment relationships and adaptive learning features. **Example Usage**: ```json { "sourcedId": "assessment-123", "title": "Chapter 5 Quiz", "component": { "sourcedId": "component-456" }, "componentResource": { "sourcedId": "resource-789" } } ``` ## Affected Endpoints ### Schema Extensions Availability The proprietary schema fields are available in: **Gradebook API**: - `GET /ims/oneroster/gradebook/v1p2/assessmentLineItems/` - Returns assessmentLineItems with `component` and `componentResource` fields - `GET /ims/oneroster/gradebook/v1p2/assessmentLineItems/{sourcedId}` - Returns individual assessmentLineItem with extended fields - `POST /ims/oneroster/gradebook/v1p2/assessmentLineItems/` - Accepts `component` and `componentResource` in request body - `PUT /ims/oneroster/gradebook/v1p2/assessmentLineItems/{sourcedId}` - Accepts extended fields for updates servers: - url: https://api.alpha-1edtech.ai description: PowerPath API security: - OAuth2: [] tags: - name: Course Mastery - name: Course Sequence description: >- Manage course sequences and query course sequence to get the next stage in the student learning path - name: Lesson Mastery description: >- Track and manage student mastery of lesson objectives, through PowerPath 100 lessons - name: Lesson Plans description: Manage lesson plans and instructional content - name: Placement - name: Test Assignments - name: Test Out description: >- Self-elected test-out endpoints for students to verify mastery and advance to the next grade level paths: /powerpath/test-out/getTestOutEligibility/{studentId}/{subject}: get: tags: - Test Out summary: Check if a student is eligible to self-request a test-out description: >- Checks whether a student can self-request an assessment to test out of their current grade level for a given subject. The endpoint performs the following checks in order: 1. Verifies the student has an active enrollment for the subject in a non-placeholder course (endDate is null or in the future, and course metadata does not have placementPlaceholder set to true) 2. Fetches the student's highest grade mastered for the subject 3. If the highest grade mastered is available, queries the assessment_results table for any existing fully-graded self-elected test-out at the next grade level (highestGradeMastered + 1) 4. If the highest grade mastered is not available, falls back to the active course sequence to determine the lowest assessment grade for the subject and checks for a prior test-out at that grade Returns `eligible: true` if no prior test-out exists at the target grade. Returns `eligible: false` with a reason if the student has no qualifying active enrollment, or has already tested out. Subject matching is case-insensitive. Supported subjects: Math, Reading, Language, Science, Writing, Vocabulary. operationId: getTestOutEligibility parameters: - name: studentId description: The OneRoster sourcedId of the student in: path required: true schema: type: string - name: subject description: The subject to check eligibility for in: path required: true schema: type: string responses: '200': description: Eligibility result content: application/json: schema: type: object properties: eligible: type: boolean description: Whether the student is eligible to test out reason: type: string description: >- The reason the student is not eligible, only present when eligible is false required: - eligible '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedRequestResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: Unprocessable Entity / Validation Error content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' components: schemas: BadRequestResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: invaliddata description: The field value for the minor code example: invaliddata required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor UnauthorizedRequestResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: unauthorisedrequest description: The field value for the minor code example: unauthorisedrequest required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor ForbiddenResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: forbidden description: The field value for the minor code example: forbidden required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor NotFoundResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: unknownobject description: The field value for the minor code example: unknownobject required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor UnprocessableEntityResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: invaliddata description: The field value for the minor code example: invaliddata required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor TooManyRequestsResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: server_busy description: The field value for the minor code example: server_busy required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor InternalServerErrorResponse: type: object properties: imsx_codeMajor: type: string default: failure description: The major response code example: failure imsx_severity: type: string default: error description: The severity of the response example: error imsx_description: type: string imsx_CodeMinor: type: object properties: imsx_codeMinorField: type: array items: type: object properties: imsx_codeMinorFieldName: type: string default: TargetEndSystem description: The field name for the minor code example: TargetEndSystem imsx_codeMinorFieldValue: type: string default: internal_server_error description: The field value for the minor code example: internal_server_error required: - imsx_codeMinorFieldName - imsx_codeMinorFieldValue required: - imsx_codeMinorField imsx_error_details: type: array items: type: object additionalProperties: type: string required: - imsx_codeMajor - imsx_severity - imsx_description - imsx_CodeMinor securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: scopes: https://purl.imsglobal.org/spec/or/v1p1/scope/admin: Admin access to the API https://purl.imsglobal.org/spec/or/v1p2/scope/admin.own: Admin access restricted to own resources https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly: Read access to roster core https://purl.imsglobal.org/spec/or/v1p1/scope/roster.readonly: Read access to roster https://purl.imsglobal.org/spec/or/v1p1/scope/roster.createput: Create and update access to roster https://purl.imsglobal.org/spec/or/v1p1/scope/roster.delete: Delete access to roster https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.readonly: Read access to roster demographics https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.createput: Create and update access to roster demographics https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.delete: Delete access to roster demographics https://purl.imsglobal.org/spec/or/v1p1/scope/resource.readonly: Read access to resource https://purl.imsglobal.org/spec/or/v1p1/scope/resource.createput: Create and update access to resource https://purl.imsglobal.org/spec/or/v1p1/scope/resource.delete: Delete access to resource https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.readonly: Read access to gradebook https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.createput: Create and update access to gradebook https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.delete: Delete access to gradebook https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.readonly: Read access to powerpath https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.createput: Create and update access to powerpath https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.delete: Delete access to powerpath https://purl.imsglobal.org/spec/powerpath/v1p1/scope/powerpath.admin: Admin access to powerpath https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.readonly: Read your issued badges https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.upsert: Store new badges in your account https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.delete: Delete access to open badges https://purl.imsglobal.org/spec/ob/v3p0/scope/credential.admin: Administrative access to open badges https://purl.imsglobal.org/spec/clr/v2p0/scope/credential.readonly: Read access to CLR https://purl.imsglobal.org/spec/clr/v2p0/scope/credential.upsert: Create and update access to CLR https://purl.imsglobal.org/spec/clr/v2p0/scope/credential.admin: Administrative access to CLR https://api.alpha-1edtech.ai/edubridge/progression.readonly: Browse lesson catalog via progression proxy https://api.alpha-1edtech.ai/edubridge/progression.createput: Create hole-filling courses via progression proxy tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token ````