> ## 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. # Create a self-elected student test-out assignment > Creates an AlphaTest test-out assignment for a student on a given subject. The endpoint performs the following steps: 1. Looks up the student's email using their OneRoster sourcedId 2. Checks eligibility: the student must have an active enrollment in a non-placeholder course for the subject 3. Resolves eligibility and the target grade atomically 4. When advancing from mastered K-2 Reading to the next grade's test-out, requires a passed ORF screener at the mastered grade (summer-experience students retain their configured waiver while its feature flag is enabled) 5. Assigns exactly the target grade returned by the eligibility decision 6. For FastMath Kindergarten and above, selects the first unpassed operation from the active sequence and forwards its exact gradeAssessmentTag The assignment payload sent to AlphaTest includes: - `test_type`: "test out" - `origin`: "self-elected" - `metadata.gradeAssessmentTag` for FastMath Kindergarten and above (PreK accuracy assignments remain untagged) Will fail if: - The student does not exist or has no email - The student does not have an active enrollment for the subject (or the course has placementPlaceholder set to true) - The assignment would be the student's entry into a gated subject and the subject's all-source placement prerequisites are unmet while FF_TEST_OUT_ENTRY_PLACEMENT_GATE is enabled - Advancing from mastered K-2 Reading is still blocked by that grade's ORF gate - The test-out grade cannot be determined (no highest grade mastered and no active course sequence with assessment stages) - The AlphaTest API returns an error ## OpenAPI ````yaml /openapi/beyond-ai/powerpath-api.yaml post /powerpath/test-out/makeExternalStudentTestOutAssignment 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/makeExternalStudentTestOutAssignment: post: tags: - Test Out summary: Create a self-elected student test-out assignment description: >- Creates an AlphaTest test-out assignment for a student on a given subject. The endpoint performs the following steps: 1. Looks up the student's email using their OneRoster sourcedId 2. Checks eligibility: the student must have an active enrollment in a non-placeholder course for the subject 3. Resolves eligibility and the target grade atomically 4. When advancing from mastered K-2 Reading to the next grade's test-out, requires a passed ORF screener at the mastered grade (summer-experience students retain their configured waiver while its feature flag is enabled) 5. Assigns exactly the target grade returned by the eligibility decision 6. For FastMath Kindergarten and above, selects the first unpassed operation from the active sequence and forwards its exact gradeAssessmentTag The assignment payload sent to AlphaTest includes: - `test_type`: "test out" - `origin`: "self-elected" - `metadata.gradeAssessmentTag` for FastMath Kindergarten and above (PreK accuracy assignments remain untagged) Will fail if: - The student does not exist or has no email - The student does not have an active enrollment for the subject (or the course has placementPlaceholder set to true) - The assignment would be the student's entry into a gated subject and the subject's all-source placement prerequisites are unmet while FF_TEST_OUT_ENTRY_PLACEMENT_GATE is enabled - Advancing from mastered K-2 Reading is still blocked by that grade's ORF gate - The test-out grade cannot be determined (no highest grade mastered and no active course sequence with assessment stages) - The AlphaTest API returns an error operationId: makeExternalStudentTestOutAssignment requestBody: content: application/json: schema: type: object properties: oneRosterSourcedId: type: string minLength: 1 description: >- The OneRoster sourcedId of the student who will take the test subject: type: string description: >- The subject for which the student will test out (e.g. Math, FastMath, Reading, Language, Science, Writing, Vocabulary) required: - oneRosterSourcedId - subject responses: '200': description: Assignment created content: application/json: schema: type: object properties: success: type: boolean data: type: object additionalProperties: {} required: - success '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' '409': description: >- Student already has a pending test for this subject and grade. When provided, use data.existing_assignment.test_url to direct the student to the existing test. A conflict may omit assignment details. content: application/json: schema: type: object properties: httpStatus: type: number const: 409 success: type: boolean const: false error: type: string example: Assignment already exists data: type: object properties: existing_assignment: type: object properties: id: type: number test_url: type: string status: type: string test_name: type: string expires_at: type: string message: type: string additionalProperties: true required: - httpStatus - success - error '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 ````