> ## 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. # Declare a lesson version (Curriculum Fixing) > TimeBack fetches every part of the lesson (practice questions from the QTI bank, article and video pages with their checkpoint and media files from the page store), builds the receipt, diffs it against the last declared version and, with dryRun false, writes version n+1 — or answers unchanged and writes nothing. Version 1 is the baseline and re-assigns nobody. From version 2, `changed` is what re-assign eligibility reads. The declarer is the calling credential. Idempotent: the same content declared twice writes once. ## OpenAPI ````yaml /openapi/beyond-ai/powerpath-api.yaml post /powerpath/lessons/{lessonId}/versions 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`, `middleName`, `preferredFirstName`, `preferredMiddleName`, `preferredLastName`, `username`, `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/lessons/{lessonId}/versions: post: tags: - Lesson Plans summary: Declare a lesson version (Curriculum Fixing) description: >- TimeBack fetches every part of the lesson (practice questions from the QTI bank, article and video pages with their checkpoint and media files from the page store), builds the receipt, diffs it against the last declared version and, with dryRun false, writes version n+1 — or answers unchanged and writes nothing. Version 1 is the baseline and re-assigns nobody. From version 2, `changed` is what re-assign eligibility reads. The declarer is the calling credential. Idempotent: the same content declared twice writes once. operationId: declareLessonVersion parameters: - name: lessonId description: Course component sourcedId of the lesson in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: reason: type: string minLength: 1 maxLength: 500 description: The producer's run id, publish job or fix order dryRun: type: boolean default: true description: 'Default true: fetch, diff and answer; write nothing' limit: type: integer minimum: 1 maximum: 5000 default: 500 description: >- Children re-assigned per real run; declare the same lesson again to resume the rest required: - reason additionalProperties: false responses: '200': description: The declaration or preview content: application/json: schema: $ref: '#/components/schemas/LessonVersionDeclaration' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedRequestResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '404': description: Lesson not found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '502': description: A part could not be fetched; nothing was recorded content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' components: schemas: LessonVersionDeclaration: type: object properties: lessonId: type: string dryRun: type: boolean version: type: - integer - 'null' baseline: type: boolean unchanged: type: boolean written: type: boolean changed: type: object properties: items: type: array items: type: string article: type: boolean video: type: boolean checkpoints: type: array items: type: string required: - items - article - video - checkpoints receipt: type: object properties: takenAt: type: string resourceIds: type: array items: type: string parts: type: array items: allOf: - oneOf: - type: object properties: kind: type: string const: practice-set componentResourceId: type: string resourceId: type: - string - 'null' test: type: - string - 'null' items: type: array items: type: object properties: identifier: type: string sha256: type: string updatedAt: type: - string - 'null' version: type: - number - 'null' updatedBy: type: - string - 'null' required: - identifier - sha256 - updatedAt - version - updatedBy required: - kind - componentResourceId - resourceId - test - items - type: object properties: kind: type: string const: article componentResourceId: type: string resourceId: type: - string - 'null' url: type: - string - 'null' fetch: type: string enum: - public - not-public - none page: type: - object - 'null' properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' required: - sha256 - etag - versionId - lastModified checkpoints: type: array items: type: object properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' path: type: string required: - sha256 - etag - versionId - lastModified - path media: type: array items: type: object properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' path: type: string required: - sha256 - etag - versionId - lastModified - path required: - kind - componentResourceId - resourceId - url - fetch - page - checkpoints - media - type: object properties: kind: type: string const: video componentResourceId: type: string resourceId: type: - string - 'null' url: type: - string - 'null' fetch: type: string enum: - public - not-public - none page: type: - object - 'null' properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' required: - sha256 - etag - versionId - lastModified checkpoints: type: array items: type: object properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' path: type: string required: - sha256 - etag - versionId - lastModified - path media: type: array items: type: object properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' path: type: string required: - sha256 - etag - versionId - lastModified - path required: - kind - componentResourceId - resourceId - url - fetch - page - checkpoints - media - type: object properties: kind: type: string const: other componentResourceId: type: string resourceId: type: - string - 'null' url: type: - string - 'null' fetch: type: string enum: - public - not-public - none page: type: - object - 'null' properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' required: - sha256 - etag - versionId - lastModified checkpoints: type: array items: type: object properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' path: type: string required: - sha256 - etag - versionId - lastModified - path media: type: array items: type: object properties: sha256: type: - string - 'null' etag: type: - string - 'null' versionId: type: - string - 'null' lastModified: type: - string - 'null' path: type: string required: - sha256 - etag - versionId - lastModified - path required: - kind - componentResourceId - resourceId - url - fetch - page - checkpoints - media - type: object properties: changed: type: boolean required: - changed required: - takenAt - resourceIds - parts previous: type: - object - 'null' properties: id: type: string version: type: integer declaredAt: type: string declaredByClientId: type: - string - 'null' run: type: - object - 'null' properties: eligible: type: integer minimum: 0 reassigned: type: integer minimum: 0 failed: type: integer minimum: 0 remaining: type: integer minimum: 0 ranAt: type: string reassignedTotal: type: integer minimum: 0 required: - eligible - reassigned - failed - remaining - ranAt required: - id - version - declaredAt - declaredByClientId - run declaredByClientId: type: - string - 'null' declaredAt: type: string population: type: - object - 'null' properties: lessons: type: integer minimum: 0 plans: type: integer minimum: 0 counts: type: object properties: eligible: type: integer minimum: 0 completedNotMastered: type: integer minimum: 0 mastered: type: integer minimum: 0 notAttempted: type: integer minimum: 0 missesUntouched: type: integer minimum: 0 alreadyReassigned: type: integer minimum: 0 operatorSkipped: type: integer minimum: 0 required: - eligible - completedNotMastered - mastered - notAttempted - missesUntouched - alreadyReassigned - operatorSkipped byCourse: type: array items: type: object properties: courseId: type: - string - 'null' plans: type: integer minimum: 0 eligible: type: integer minimum: 0 completedNotMastered: type: integer minimum: 0 required: - courseId - plans - eligible - completedNotMastered items: type: array items: type: object properties: id: type: string firstAnswers: type: integer minimum: 0 correctFirstAnswers: type: integer minimum: 0 firstTimePassRate: type: - number - 'null' required: - id - firstAnswers - correctFirstAnswers - firstTimePassRate required: - lessons - plans - counts - byCourse - items run: type: - object - 'null' properties: eligible: type: integer minimum: 0 reassigned: type: integer minimum: 0 failed: type: integer minimum: 0 remaining: type: integer minimum: 0 ranAt: type: string reassignedTotal: type: integer minimum: 0 required: - eligible - reassigned - failed - remaining - ranAt required: - lessonId - dryRun - version - baseline - unchanged - written - changed - receipt - previous - declaredByClientId - declaredAt - population - run 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 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/powerpath/v1p1/scope/powerpath.lesson-fixes.admin: Declare lesson versions (Curriculum Fixing) 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 ````