openapi: 3.0.0
info:
  description: Serves the Clever Data API
  title: Data Assignments API
  version: 3.1.0
servers:
- url: https://api.clever.com/v3.1
security:
- oauth: []
tags:
- name: Assignments
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
components:
  schemas:
    AssignmentState:
      enum:
      - draft
      - scheduled
      - open
      - locked
      type: string
    GradingScaleEntry:
      properties:
        name:
          type: string
        value:
          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
    AssigneeMode:
      enum:
      - all
      - individuals
      type: string
    NotFound:
      properties:
        message:
          type: string
      type: object
    GradingScale:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/GradingScaleEntry'
          type: array
          nullable: true
        name:
          type: string
      type: object
    SubmissionsLink:
      properties:
        rel:
          enum:
          - next
          type: string
        uri:
          type: string
      type: object
    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
    SubmissionFlag:
      enum:
      - excused
      - late
      - missing
      type: string
    BadRequest:
      properties:
        message:
          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
    AssignmentResponse:
      properties:
        data:
          $ref: '#/components/schemas/Assignment'
      type: object
    SubmissionState:
      enum:
      - created
      - submitted
      - returned
      - reclaimed
      type: string
    GradingType:
      enum:
      - points
      - percent
      - pass_fail
      - letter_grade
      type: string
    Unauthorized:
      properties:
        message:
          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
    AttachmentRequest:
      properties:
        description:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        type:
          enum:
          - file
          type: string
        url:
          type: string
          nullable: true
      type: object
    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
    InternalError:
      properties:
        message:
          type: string
      type: object
    SubmissionType:
      enum:
      - link
      - file
      - text
      - discussion
      type: string
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    NotFound:
      description: Entity Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
    InternalError:
      description: Internal Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
    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: {}
x-samples-languages:
- curl
- node
- ruby
- python
- php
- java
- go