openapi: 3.0.1

info:
    version: v2.4.2
    title: TAO LTI 1.3 DevKit - HTTP API

servers:
    - url: http://devkit-lti1p3.localhost
      description: Local TAO LTI 1.3 DevKit (docker)

paths:
    /api/platform/messages/ltiResourceLinkRequest/launch:
        post:
            summary: Generate LtiResourceLinkRequest message launch
            tags:
                - LTI messages
            security:
                -   apiKey: [ ]
            parameters:
                -   in: query
                    name: verbose
                    schema:
                        type: string
                    description: If true, will provide message launch details
                    example: true
            requestBody:
                description: LtiResourceLinkRequest message launch data
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LtiResourceLinkRequestInput'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LtiMessageOutput'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'

    /api/platform/messages/ltiDeepLinkingRequest/launch:
        post:
            summary: Generate LtiDeepLinkingRequest message launch
            tags:
                - LTI messages
            security:
                - apiKey: [ ]
            parameters:
                - in: query
                  name: verbose
                  schema:
                      type: string
                  description: If true, will provide message launch details
                  example: true
            requestBody:
                description: LtiDeepLinkingRequest message launch data
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LtiDeepLinkingRequestInput'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LtiMessageOutput'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'

    /api/platform/messages/ltiStartProctoring/launch:
        post:
            summary: Generate LtiStartProctoring message launch
            tags:
                - LTI messages
            security:
                - apiKey: [ ]
            parameters:
                - in: query
                  name: verbose
                  schema:
                      type: string
                  description: If true, will provide message launch details
                  example: true
            requestBody:
                description: LtiStartProctoring message launch data
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LtiStartProctoringInput'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LtiMessageOutput'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'

    /api/platform/messages/ltiSubmissionReviewRequest/launch:
        post:
            summary: Generate LtiSubmissionReviewRequest message launch
            tags:
                - LTI messages
            security:
                - apiKey: [ ]
            parameters:
                - in: query
                  name: verbose
                  schema:
                      type: string
                  description: If true, will provide message launch details
                  example: true
            requestBody:
                description: LtiSubmissionReviewRequest message launch data
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LtiSubmissionReviewRequestInput'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LtiMessageOutput'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'

    /api/platform/proctoring/assessments:
        get:
            summary: List ACS assessments
            tags:
                - ACS assessments
            security:
                -   apiKey: [ ]
            parameters:
                -   in: query
                    name: limit
                    schema:
                        type: integer
                    description: Pagination limit
                -   in: query
                    name: offset
                    schema:
                        type: integer
                    description: Pagination offset
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssessmentCollection'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
        post:
            summary: Create ACS assessment
            tags:
                - ACS assessments
            security:
                -   apiKey: [ ]
            requestBody:
                description: ACS assessment to create
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AcsAssessment'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Assessment'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                409:
                    $ref: '#/components/responses/ConflictResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
    /api/platform/proctoring/assessments/{assessmentId}:
        get:
            summary: Get ACS assessment
            tags:
                - ACS assessments
            security:
                -   apiKey: [ ]
            parameters:
                -   in: path
                    name: assessmentId
                    schema:
                        type: string
                    description: ACS assessment identifier
                    required: true
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Assessment'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                404:
                    $ref: '#/components/responses/NotFoundResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
        delete:
            summary: Delete ACS assessment
            tags:
                - ACS assessments
            security:
                -   apiKey: [ ]
            parameters:
                -   in: path
                    name: assessmentId
                    schema:
                        type: string
                    description: ACS assessment identifier
                    required: true
            responses:
                204:
                    description: Success
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                404:
                    $ref: '#/components/responses/NotFoundResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
        patch:
            summary: Update ACS assessment
            tags:
                - ACS assessments
            security:
                -   apiKey: [ ]
            parameters:
                -   in: path
                    name: assessmentId
                    schema:
                        type: string
                    description: ACS assessment identifier
                    required: true
            requestBody:
                description: ACS assessment data to update (only status allowed)
                required: false
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                status:
                                    type: string
                                    enum:
                                        - none
                                        - running
                                        - paused
                                        - terminated
                                        - complete
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Assessment'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                404:
                    $ref: '#/components/responses/NotFoundResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
    /api/platform/nrps/memberships:
        get:
            summary: List NRPS memberships
            tags:
                - NRPS memberships
            security:
                -   apiKey: [ ]
            parameters:
            -       in: query
                    name: limit
                    schema:
                        type: integer
                    description: Pagination limit
            -       in: query
                    name: offset
                    schema:
                        type: integer
                    description: Pagination offset
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MembershipCollection'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
        post:
            summary: Create NRPS membership
            tags:
                - NRPS memberships
            security:
                -   apiKey: [ ]
            requestBody:
                description: NRPS membership to create
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NrpsMembership'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Membership'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                409:
                    $ref: '#/components/responses/ConflictResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
    /api/platform/nrps/memberships/{membershipId}:
        get:
            summary: Get NRPS membership
            tags:
                - NRPS memberships
            security:
                -   apiKey: [ ]
            parameters:
                -   in: path
                    name: membershipId
                    schema:
                        type: string
                    description: NRPS membership identifier
                    required: true
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Membership'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                404:
                    $ref: '#/components/responses/NotFoundResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
        delete:
            summary: Delete NRPS membership
            tags:
                - NRPS memberships
            security:
                -   apiKey: [ ]
            parameters:
                -   in: path
                    name: membershipId
                    schema:
                        type: string
                    description: NRPS membership identifier
                    required: true
            responses:
                204:
                    description: Success
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                403:
                    $ref: '#/components/responses/ForbiddenResponse'
                404:
                    $ref: '#/components/responses/NotFoundResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'
        patch:
            summary: Update NRPS membership
            tags:
                - NRPS memberships
            security:
                -   apiKey: [ ]
            parameters:
                -   in: path
                    name: membershipId
                    schema:
                        type: string
                    description: NRPS membership identifier
                    required: true
            requestBody:
                description: NRPS membership data to update (partial representation allowed)
                required: false
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                context:
                                    $ref: '#/components/schemas/NrpsContext'
                                members:
                                    $ref: '#/components/schemas/NrpsMemberCollection'
            responses:
                200:
                    description: Success
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Membership'
                400:
                    $ref: '#/components/responses/BadRequestResponse'
                401:
                    $ref: '#/components/responses/UnauthorizedResponse'
                403:
                    $ref: '#/components/responses/ForbiddenResponse'
                404:
                    $ref: '#/components/responses/NotFoundResponse'
                500:
                    $ref: '#/components/responses/InternalServerErrorResponse'

components:
    securitySchemes:
        apiKey:
            type: http
            scheme: bearer
            bearerFormat: TAO LTI 1.3 DevKit API key
    schemas:
        LtiResourceLinkRequestInput:
            type: object
            properties:
                registration:
                    description: Registration identifier to use for the launch
                    example: 'devkit'
                    type: string
                user:
                    description: User details to use for the launch
                    type: object
                    properties:
                        id:
                            description: User id, will generate uuidv4 if not provided
                            example: 'user-id'
                            type: string
                        name:
                            description: User name
                            example: 'John Alex Doe'
                            type: string
                        email:
                            description: User email
                            example: 'john-doe@platform.example.edu'
                            type: string
                        locale:
                            description: User locale
                            example: 'en'
                            type: string
                target_link_uri:
                    description: The target_link_uri to use for the launch, if not provided, will use default tool launch url
                    example: 'http://devkit-lti1p3.localhost/tool/launch'
                    type: string
                deployment_id:
                    description: The deployment_id to use for the launch, if not provided, will use default registration deployment id
                    example: 'deploymentId1'
                    type: string
                claims:
                    description: The claims to use for the launch
                    type: object
                    additionalProperties:
                        type: string
                    example:
                        a: b
                        'https://purl.imsglobal.org/spec/lti/claim/roles':
                            - 'http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'
            required:
                - registration
        LtiDeepLinkingRequestInput:
            type: object
            properties:
                registration:
                    description: Registration identifier to use for the launch
                    example: 'devkit'
                    type: string
                deep_linking_settings:
                    description: Deep linking launch settings
                    type: object
                    properties:
                        accept_types:
                            description: Deep linking accepted types (default ['ltiResourceLink'])
                            type: object
                            additionalProperties:
                                type: string
                            example:
                                - 'link'
                                - 'file'
                                - 'html'
                                - 'ltiResourceLink'
                                - 'image'
                        accept_presentation_document_targets:
                            description: Deep linking accepted presentation document targets (default ['window'])
                            type: object
                            additionalProperties:
                                type: string
                            example:
                                - 'iframe'
                                - 'window'
                                - 'embed'
                        accept_media_types:
                            description: Deep linking accepted media types (default empty)
                            example: 'image/*,text/html'
                            type: string
                        accept_multiple:
                            description: If accept multiple (default true)
                            type: boolean
                        auto_create:
                            description: If should auto create (default false)
                            type: boolean
                            example: false
                        title:
                            description: Title
                            type: string
                        text:
                            description: Text
                            type: string
                user:
                    description: User details to use for the launch
                    type: object
                    properties:
                        id:
                            description: User id, will generate uuidv4 if not provided
                            example: 'user-id'
                            type: string
                        name:
                            description: User name
                            example: 'John Alex Doe'
                            type: string
                        email:
                            description: User email
                            example: 'john-doe@platform.example.edu'
                            type: string
                        locale:
                            description: User locale
                            example: 'en'
                            type: string
                target_link_uri:
                    description: The target_link_uri to use for the deep linking launch, if not provided, will use default tool deep linking launch url
                    example: 'http://devkit-lti1p3.localhost/tool/launch'
                    type: string
                deployment_id:
                    description: The deployment_id to use for the launch, if not provided, will use default registration deployment id
                    example: 'deploymentId1'
                    type: string
                claims:
                    description: The claims to use for the launch
                    type: object
                    additionalProperties:
                        type: string
                    example:
                        a: b
                        'https://purl.imsglobal.org/spec/lti/claim/roles':
                            - 'http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'
            required:
                - registration
        LtiStartProctoringInput:
            type: object
            properties:
                registration:
                    description: Registration identifier to use for the launch
                    example: 'devkit'
                    type: string
                proctoring_start_assessment_url:
                    description: Proctroring start assessment url
                    example: 'http://devkit-lti1p3.localhost/platform/message/return/proctoring'
                    type: string
                proctoring_attempt_number:
                    description: Proctroring attempt number (default 1)
                    example: 1
                    type: integer
                user:
                    description: User details to use for the launch
                    type: object
                    properties:
                        id:
                            description: User id, will generate uuidv4 if not provided
                            example: 'user-id'
                            type: string
                        name:
                            description: User name
                            example: 'John Alex Doe'
                            type: string
                        email:
                            description: User email
                            example: 'john-doe@platform.example.edu'
                            type: string
                        locale:
                            description: User locale
                            example: 'en'
                            type: string
                target_link_uri:
                    description: The target_link_uri to use for the launch, if not provided, will use default tool launch url
                    example: 'http://devkit-lti1p3.localhost/tool/launch'
                    type: string
                deployment_id:
                    description: The deployment_id to use for the launch, if not provided, will use default registration deployment id
                    example: 'deploymentId1'
                    type: string
                claims:
                    description: The claims to use for the launch
                    type: object
                    additionalProperties:
                        type: string
                    example:
                        a: b
                        'https://purl.imsglobal.org/spec/lti/claim/roles':
                            - 'http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'
            required:
                - registration
                - proctoring_start_assessment_url
        LtiSubmissionReviewRequestInput:
            type: object
            properties:
                registration:
                    description: Registration identifier to use for the launch
                    example: 'devkit'
                    type: string
                ags_line_item_url:
                    description: AGS line item url
                    example: 'http://devkit-lti1p3.localhost/platform/service/ags/default/lineitems/default'
                    type: string
                ags_scopes:
                    description: AGS scopes
                    type: object
                    additionalProperties:
                        type: string
                    example:
                        - 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'
                        - 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly'
                        - 'https://purl.imsglobal.org/spec/lti-ags/scope/score'
                        - 'https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly'
                submission_owner:
                    description: User who made the submission that is to be reviewed (if not provided, will use launch user information)
                    type: object
                    properties:
                        id:
                            description: Submission owner id, will generate uuidv4 if not provided
                            example: 'submission-owner-id'
                            type: string
                        name:
                            description: Submission owner name
                            example: 'Jane Polly Doe'
                            type: string
                        email:
                            description: Submission owner email
                            example: 'jane-doe@platform.example.edu'
                            type: string
                        roles:
                            description: Submission owner roles
                            type: object
                            additionalProperties:
                                type: string
                            example:
                                - 'http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'
                user:
                    description: User details to use for the launch
                    type: object
                    properties:
                        id:
                            description: User id, will generate uuidv4 if not provided
                            example: 'user-id'
                            type: string
                        name:
                            description: User name
                            example: 'John Alex Doe'
                            type: string
                        email:
                            description: User email
                            example: 'john-doe@platform.example.edu'
                            type: string
                        locale:
                            description: User locale
                            example: 'en'
                            type: string
                target_link_uri:
                    description: The target_link_uri to use for the launch, if not provided, will use default tool launch url
                    example: 'http://devkit-lti1p3.localhost/tool/launch'
                    type: string
                deployment_id:
                    description: The deployment_id to use for the launch, if not provided, will use default registration deployment id
                    example: 'deploymentId1'
                    type: string
                claims:
                    description: The claims to use for the launch
                    type: object
                    additionalProperties:
                        type: string
                    example:
                        a: b
                        'https://purl.imsglobal.org/spec/lti/claim/roles':
                            - 'http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'
            required:
                - registration
                - ags_line_item_url
                - ags_scopes
        LtiMessageOutput:
            type: object
            properties:
                link:
                    description: Generated ltiResourceLinkRequest launch complete url
                    example: 'http://devkit-lti1p3.localhost/lti1p3/oidc/initiation?iss=http%3A%2F%2Fdevkit-lti1p3.localhost%2Fplatform&login_hint=%7B%22type%22%3A%22custom%22%2C%22user_id%22%3A%22userIdentifier%22%2C%22user_name%22%3Anull%2C%22user_email%22%3Anull%2C%22user_locale%22%3Anull%7D&target_link_uri=http%3A%2F%2Fdevkit-lti1p3.localhost%2Ftool%2Flaunch&lti_message_hint=eyJ0e...&lti_deployment_id=deploymentId1&client_id=client_id'
                    type: string
                details:
                    description: User details to use for the launch
                    type: object
                    properties:
                        url:
                            description: Generated ltiResourceLinkRequest launch base url
                            example: 'http://devkit-lti1p3.localhost/lti1p3/oidc/initiation'
                            type: string
                        parameters:
                            type: object
                            properties:
                                iss:
                                    example: 'http://devkit-lti1p3.localhost/platform'
                                    type: string
                                login_hint:
                                    example: '"{\"type\":\"custom\",\"user_id\":\"userIdentifier\",\"user_name\":null,\"user_email\":null,\"user_locale\":null}"'
                                    type: string
                                target_link_uri:
                                    example: 'http://devkit-lti1p3.localhost/tool/launch'
                                    type: string
                                lti_message_hint:
                                    example: 'eyJ0e...'
                                    type: string
                                lti_deployment_id:
                                    example: 'deploymentId1'
                                    type: string
                                client_id:
                                    example: 'client_id'
                                    type: string
            required:
                - link
        AssessmentCollection:
            type: object
            properties:
                assessments:
                    type: array
                    items:
                        $ref: '#/components/schemas/Assessment'
        Assessment:
            type: object
            properties:
                assessment:
                    $ref: '#/components/schemas/AcsAssessment'
                acs_url:
                    description: Assessment ACS url
                    example: 'http://devkit-lti1p3.localhost/platform/service/acs/custom-assessment'
                    type: string
        AcsAssessment:
            type: object
            properties:
                id:
                    description: Assessment identifier
                    example: 'custom-assessment'
                    type: string
                status:
                    description: Assessment status
                    type: string
                    enum:
                        - none
                        - running
                        - paused
                        - terminated
                        - complete
            required:
                - id
                - status
        MembershipCollection:
            type: object
            properties:
                memberships:
                    type: array
                    items:
                        $ref: '#/components/schemas/Membership'
        Membership:
            type: object
            properties:
                membership:
                    $ref: '#/components/schemas/NrpsMembership'
                nrps_url:
                    description: Membership NRPS url
                    example: 'http://devkit-lti1p3.localhost/platform/service/nrps/custom-context/memberships/custom-membership'
                    type: string
        NrpsMembership:
            type: object
            properties:
                id:
                    description: Membership identifier
                    example: 'custom-membership'
                    type: string
                context:
                    $ref: '#/components/schemas/NrpsContext'
                members:
                    $ref: '#/components/schemas/NrpsMemberCollection'
            required:
                - id
                - context
        NrpsContext:
            type: object
            properties:
                id:
                    description: Context identifier
                    example: 'custom-context'
                    type: string
                label:
                    description: Context label
                    example: 'Context label'
                    type: string
                title:
                    description: Context title
                    example: 'Context title'
                    type: string
            required:
                - id
        NrpsMemberCollection:
            type: array
            items:
                $ref: '#/components/schemas/NrpsMember'
        NrpsMember:
            type: object
            properties:
                user_id:
                    description: Member identifier
                    example: 'user-id'
                    type: string
                roles:
                    type: array
                    items:
                        type: string
                        example: 'http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor'
                status:
                    description: Member status
                    example: 'Active'
                    type: string
                name:
                    description: Member name
                    example: 'John Alex Doe'
                    type: string
                picture:
                    description: Member picture
                    example: 'https://platform.example.edu/john-doe.jpg'
                    type: string
                given_name:
                    description: Member given name
                    example: 'John'
                    type: string
                family_name:
                    description: Member family name
                    example: 'Doe'
                    type: string
                middle_name:
                    description: Member middle name
                    example: 'Alex'
                    type: string
                email:
                    description: Member email
                    example: 'john-doe@platform.example.edu'
                    type: string
                lis_person_sourcedid:
                    description: LIS sourced id
                    example: 'lis-sourced-id'
                    type: string
            required:
                - user_id
                - roles
        Error:
            type: object
            properties:
                message:
                    description: Error message
                    example: Error message
                    type: string
    responses:
        BadRequestResponse:
            description: Bad request
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
        UnauthorizedResponse:
            description: Unauthorized
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
        ForbiddenResponse:
            description: Forbidden
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
        NotFoundResponse:
            description: Not found
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
        ConflictResponse:
            description: Conflict
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
        InternalServerErrorResponse:
            description: Internal server error
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
