openapi: 3.1.0
info:
  title: Schoology REST API v1
  description: |
    REST API for the Schoology K-12 LMS (a PowerSchool company). Provides access
    to realm resources (users, courses, sections), realm objects (enrollments,
    assignments, grades, submissions), and multi-call helpers.
    Source: https://developers.schoology.com/api-documentation/rest-api-v1
  version: "1.0"
servers:
  - url: https://api.schoology.com/v1
    description: Schoology REST API v1
security:
  - OAuth: []
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      tags: [Users]
      responses:
        "200":
          description: A collection of users.
  /users/{id}:
    get:
      summary: Get user
      operationId: getUser
      tags: [Users]
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: A single user.
  /users/ext/{external_id}:
    get:
      summary: Get user by external ID
      operationId: getUserByExternalId
      tags: [Users]
      parameters:
        - name: external_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: A single user.
  /users/{id}/sections:
    get:
      summary: List sections for a user
      operationId: listUserSections
      tags: [Users, Sections]
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Sections the user is enrolled in.
  /users/{id}/groups:
    get:
      summary: List groups for a user
      operationId: listUserGroups
      tags: [Users, Groups]
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Groups the user belongs to.
  /users/{id}/grades:
    get:
      summary: Get grades for a user
      operationId: getUserGrades
      tags: [Users, Grades]
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Grades for the user.
  /courses:
    get:
      summary: List courses
      operationId: listCourses
      tags: [Courses]
      responses:
        "200":
          description: A collection of courses.
  /courses/{id}:
    get:
      summary: Get course
      operationId: getCourse
      tags: [Courses]
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: A single course.
  /sections:
    get:
      summary: List sections
      operationId: listSections
      tags: [Sections]
      responses:
        "200":
          description: A collection of sections.
  /sections/{id}:
    get:
      summary: Get section
      operationId: getSection
      tags: [Sections]
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: A single section.
  /sections/ext/{external_id}:
    get:
      summary: Get section by external ID
      operationId: getSectionByExternalId
      tags: [Sections]
      parameters:
        - name: external_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: A single section.
  /sections/{section_id}/enrollments:
    get:
      summary: List enrollments in a section
      operationId: listSectionEnrollments
      tags: [Enrollments]
      parameters:
        - $ref: "#/components/parameters/SectionId"
      responses:
        "200":
          description: Enrollments in the section.
    post:
      summary: Create an enrollment in a section
      operationId: createSectionEnrollment
      tags: [Enrollments]
      parameters:
        - $ref: "#/components/parameters/SectionId"
      responses:
        "201":
          description: Enrollment created.
  /groups/{group_id}/enrollments:
    get:
      summary: List enrollments in a group
      operationId: listGroupEnrollments
      tags: [Enrollments, Groups]
      parameters:
        - name: group_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Enrollments in the group.
  /sections/{section_id}/assignments:
    get:
      summary: List assignments in a section
      operationId: listAssignments
      tags: [Assignments]
      parameters:
        - $ref: "#/components/parameters/SectionId"
      responses:
        "200":
          description: Assignments in the section.
    post:
      summary: Create assignment
      operationId: createAssignment
      tags: [Assignments]
      parameters:
        - $ref: "#/components/parameters/SectionId"
      responses:
        "201":
          description: Assignment created.
  /sections/{section_id}/assignments/{id}:
    get:
      summary: Get assignment
      operationId: getAssignment
      tags: [Assignments]
      parameters:
        - $ref: "#/components/parameters/SectionId"
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: An assignment.
  /sections/{section_id}/grades:
    get:
      summary: List grades in a section
      operationId: listSectionGrades
      tags: [Grades]
      parameters:
        - $ref: "#/components/parameters/SectionId"
      responses:
        "200":
          description: Grades in the section.
  /sections/{section_id}/submissions/{grade_item_id}:
    get:
      summary: List submissions for a grade item
      operationId: listSubmissions
      tags: [Submissions]
      parameters:
        - $ref: "#/components/parameters/SectionId"
        - name: grade_item_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Submissions for the grade item.
  /sections/{section_id}/submissions/{grade_item_id}/{user_id}:
    get:
      summary: Get a user's submission for a grade item
      operationId: getSubmission
      tags: [Submissions]
      parameters:
        - $ref: "#/components/parameters/SectionId"
        - name: grade_item_id
          in: path
          required: true
          schema: { type: string }
        - name: user_id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: A submission.
  /multiget:
    post:
      summary: Multi-call GET
      operationId: multiget
      tags: [Multi-Call]
      responses:
        "200":
          description: Results of multiple GET requests.
  /multioptions:
    post:
      summary: Multi-call OPTIONS
      operationId: multioptions
      tags: [Multi-Call]
      responses:
        "200":
          description: Results of multiple OPTIONS requests.
components:
  securitySchemes:
    OAuth:
      type: oauth2
      description: OAuth 1.0a / 2.0 per Schoology Authentication docs.
      flows:
        authorizationCode:
          authorizationUrl: https://api.schoology.com/v1/oauth/authorize
          tokenUrl: https://api.schoology.com/v1/oauth/access_token
          scopes: {}
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: { type: string }
    SectionId:
      name: section_id
      in: path
      required: true
      schema: { type: string }