Clever LMS Connect API

Integration layer allowing Learning Management Systems to sync gradebook data, assignments, and course enrollments with Clever. Available as of API v3.1, enabling LMS partners to exchange academic progress data in real time with districts using Clever.

OpenAPI Specification

clever-lms-connect-api-openapi.yml Raw ↑
openapi: 3.0.0
info:
  description: The Clever LMS Connect API
  title: LMS Connect API
  version: 3.1.0
paths:
  "/sections/{section_id}/assignments":
    post:
      description: Creates a new assignment in the specified section
      operationId: createAssignmentForSection
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
      requestBody:
        $ref: "#/components/requestBodies/AssignmentRequest"
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssignmentResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
      tags:
        - Assignments
  "/sections/{section_id}/assignments/{assignment_id}":
    delete:
      description: Deletes an existing assignment in the specified section
      operationId: deleteAssignmentForSection
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
        - in: path
          name: assignment_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK Response
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      tags:
        - Assignments
    get:
      description: Returns a specific assignment for a section
      operationId: getAssignmentForSection
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
        - in: path
          name: assignment_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssignmentResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      tags:
        - Assignments
    patch:
      description: Updates an existing assignment in the specified section
      operationId: updateAssignmentForSection
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
        - in: path
          name: assignment_id
          required: true
          schema:
            type: string
      requestBody:
        $ref: "#/components/requestBodies/AssignmentRequest"
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssignmentResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
      tags:
        - Assignments
  "/sections/{section_id}/assignments/{assignment_id}/submissions":
    get:
      description: Returns the submissions for an assignment.
      operationId: getSubmissionsForAssignment
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
        - in: path
          name: assignment_id
          required: true
          schema:
            type: string
        - in: query
          name: cursor
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmissionsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      tags:
        - Assignments
  "/sections/{section_id}/assignments/{assignment_id}/submissions/{user_id}":
    get:
      description: Returns a specific user's submission for an assignment.
      operationId: getSubmissionForAssignment
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
        - in: path
          name: assignment_id
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
            format: mongo-id
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmissionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
      tags:
        - Submissions
    patch:
      description: Updates an existing submission in the specified assignment for a user.
      operationId: updateSubmissionForAssignment
      parameters:
        - in: path
          name: section_id
          required: true
          schema:
            type: string
            format: mongo-id
        - in: path
          name: assignment_id
          required: true
          schema:
            type: string
        - in: path
          name: user_id
          required: true
          schema:
            type: string
            format: mongo-id
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmissionRequest"
        required: true
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmissionResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
      tags:
        - Submissions
security:
  - oauth: []
x-samples-languages:
  - curl
  - node
  - ruby
  - python
  - php
  - java
  - go
servers:
  - url: https://api.clever.com/v3.1
components:
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BadRequest"
    InternalError:
      description: Internal Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InternalError"
    NotFound:
      description: Entity Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/NotFound"
    Unauthorized:
      description: Not authorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Unauthorized"
  requestBodies:
    AssignmentRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AssignmentRequest"
      required: true
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://clever.com/oauth/authorize
          tokenUrl: https://clever.com/oauth/tokens
          scopes: {}
  schemas:
    AssigneeMode:
      enum:
        - all
        - individuals
      type: string
    Assignment:
      properties:
        assignee_ids:
          items:
            type: string
          type: array
          x-omitempty: true
        assignee_mode:
          $ref: "#/components/schemas/AssigneeMode"
        attachments:
          items:
            $ref: "#/components/schemas/Attachment"
          type: array
          x-omitempty: true
        category_id:
          type: string
          nullable: true
        created:
          format: datetime
          type: string
          nullable: true
        description:
          type: string
        description_plaintext:
          type: string
          nullable: true
        display_date:
          format: datetime
          type: string
          nullable: true
        due_date:
          format: datetime
          type: string
          nullable: true
        end_date:
          format: datetime
          type: string
          nullable: true
        grading_scale:
          items:
            $ref: "#/components/schemas/GradingScale"
          type: array
          x-omitempty: true
        grading_type:
          $ref: "#/components/schemas/GradingType"
        id:
          type: string
        last_modified:
          format: datetime
          type: string
          nullable: true
        max_attempts:
          type: integer
          x-omitempty: true
        points_possible:
          format: float
          type: number
          nullable: true
        start_date:
          format: datetime
          type: string
          nullable: true
        state:
          $ref: "#/components/schemas/AssignmentState"
        submission_types:
          items:
            $ref: "#/components/schemas/SubmissionType"
          type: array
          x-omitempty: true
        term_id:
          type: string
          nullable: true
        title:
          type: string
      type: object
    AssignmentRequest:
      properties:
        assignee_ids:
          items:
            type: string
          type: array
          x-omitempty: true
        assignee_mode:
          $ref: "#/components/schemas/AssigneeMode"
        attachments:
          items:
            $ref: "#/components/schemas/AttachmentRequest"
          type: array
          x-omitempty: true
        description:
          type: string
          nullable: true
        description_plaintext:
          type: string
          nullable: true
        display_date:
          format: datetime
          type: string
          nullable: true
        due_date:
          format: datetime
          type: string
          nullable: true
        end_date:
          format: datetime
          type: string
          nullable: true
        grading_type:
          $ref: "#/components/schemas/GradingType"
        max_attempts:
          type: integer
          x-omitempty: true
        points_possible:
          format: float
          type: number
          nullable: true
        start_date:
          format: datetime
          type: string
          nullable: true
        submission_types:
          items:
            $ref: "#/components/schemas/SubmissionType"
          type: array
          x-omitempty: true
        term_id:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
      type: object
    AssignmentResponse:
      properties:
        data:
          $ref: "#/components/schemas/Assignment"
      type: object
    AssignmentState:
      enum:
        - draft
        - scheduled
        - open
        - locked
      type: string
    Attachment:
      properties:
        description:
          type: string
          nullable: true
        file_external_id:
          type: string
          nullable: true
        size:
          format: float
          type: number
          x-omitempty: true
        thumbnail_url:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        type:
          type: string
        url:
          type: string
          nullable: true
      type: object
    AttachmentRequest:
      properties:
        description:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        type:
          enum:
            - file
          type: string
        url:
          type: string
          nullable: true
      type: object
    BadRequest:
      properties:
        message:
          type: string
      type: object
    GradingScale:
      properties:
        entries:
          items:
            $ref: "#/components/schemas/GradingScaleEntry"
          type: array
          nullable: true
        name:
          type: string
      type: object
    GradingScaleEntry:
      properties:
        name:
          type: string
        value:
          type: string
      type: object
    GradingType:
      enum:
        - points
        - percent
        - pass_fail
        - letter_grade
      type: string
    InternalError:
      properties:
        message:
          type: string
      type: object
    NotFound:
      properties:
        message:
          type: string
      type: object
    Submission:
      properties:
        assignment_id:
          type: string
        attachments:
          items:
            $ref: "#/components/schemas/Attachment"
          type: array
          x-omitempty: true
        created:
          format: datetime
          type: string
          nullable: true
        extra_attempts:
          type: integer
          x-omitempty: true
        flags:
          items:
            $ref: "#/components/schemas/SubmissionFlag"
          type: array
          x-omitempty: true
        grade:
          type: string
          nullable: true
        grade_comment:
          type: string
          nullable: true
        grade_points:
          format: float
          type: number
          x-omitempty: true
        grader_id:
          type: string
          nullable: true
        id:
          description: >
            Deprecated. The Clever unique identifier of the submission. Will
            always be empty if the

            upstream LMS provider is Google Classroom; it is currently still present for Canvas and

            Schoology LMSs but will be removed in the near future.
          type: string
        last_modified:
          format: datetime
          type: string
          nullable: true
        override_due_date:
          format: datetime
          type: string
          nullable: true
        state:
          $ref: "#/components/schemas/SubmissionState"
        user_id:
          type: string
      type: object
    SubmissionFlag:
      enum:
        - excused
        - late
        - missing
      type: string
    SubmissionRequest:
      properties:
        attachments:
          items:
            $ref: "#/components/schemas/AttachmentRequest"
          type: array
          x-omitempty: true
        extra_attempts:
          type: integer
          x-omitempty: true
        flags:
          items:
            $ref: "#/components/schemas/SubmissionFlag"
          type: array
          x-omitempty: true
        grade:
          type: string
          nullable: true
        grade_comment:
          type: string
          nullable: true
        grade_points:
          format: float
          type: number
          x-omitempty: true
        grader_id:
          type: string
          nullable: true
        override_due_date:
          format: datetime
          type: string
          nullable: true
        state:
          $ref: "#/components/schemas/SubmissionState"
      type: object
    SubmissionResponse:
      properties:
        data:
          $ref: "#/components/schemas/Submission"
      type: object
    SubmissionState:
      enum:
        - created
        - submitted
        - returned
        - reclaimed
      type: string
    SubmissionType:
      enum:
        - link
        - file
        - text
        - discussion
      type: string
    SubmissionsLink:
      properties:
        rel:
          enum:
            - next
          type: string
        uri:
          type: string
      type: object
    SubmissionsResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/Submission"
          type: array
        links:
          items:
            $ref: "#/components/schemas/SubmissionsLink"
          type: array
          x-omitempty: true
      type: object
    Unauthorized:
      properties:
        message:
          type: string
      type: object