openapi: 3.0.3
info:
  title: PowerSchool SIS REST Authentication District API
  description: The PowerSchool SIS REST API provides programmatic access to student information system data including student demographics, enrollment records, grades, attendance, master scheduling, and district reporting. The API uses OAuth 2.0 client credentials for authentication and returns data in JSON format. Endpoints follow the /ws/v1/ path convention and support GET, POST, PUT, and DELETE HTTP methods for full CRUD operations on supported resources. Authentication tokens are obtained via /oauth/access_token/ using Basic auth with client credentials provisioned through the PowerSchool Plugin Management Dashboard.
  version: 1.0.0
  contact:
    name: PowerSchool Developer Support
    url: https://help.powerschool.com/
  termsOfService: https://www.powerschool.com/legal/
servers:
- url: https://{district}.powerschool.com
  description: District PowerSchool instance
  variables:
    district:
      description: The subdomain of the school district's PowerSchool installation
      default: demo
security:
- BearerAuth: []
tags:
- name: District
  description: District-level resources
paths:
  /ws/v1/district/school:
    get:
      operationId: getSchools
      summary: List all schools in district
      description: Returns all schools in the current district, sorted by name. Supports pagination via pagesize and page query parameters.
      tags:
      - District
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Projection'
      responses:
        '200':
          description: List of schools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchoolsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ws/v1/district/school/count:
    get:
      operationId: getSchoolsCount
      summary: Count schools in district
      description: Returns the total count of schools in the current district.
      tags:
      - District
      responses:
        '200':
          description: Count of schools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCount'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ws/v1/district/student:
    get:
      operationId: getStudentsInDistrict
      summary: List all students in district
      description: Returns all students enrolled in the current district. Supports pagination via pagesize and page query parameters, and filtering via the q parameter (e.g., q=id=ge=10000).
      tags:
      - District
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Projection'
      responses:
        '200':
          description: List of students
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ws/v1/district/student/count:
    get:
      operationId: getStudentsInDistrictCount
      summary: Count students in district
      description: Returns the total count of students enrolled in the current district.
      tags:
      - District
      responses:
        '200':
          description: Count of students
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCount'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ws/schema/table/{tableName}:
    get:
      operationId: getSchemaTable
      summary: Query a schema table
      description: Returns records from a named schema table. Supports filtering via q parameter and pagination. Common tables include students, schools, sections, cc (current courses), attendance, and more.
      tags:
      - District
      parameters:
      - name: tableName
        in: path
        required: true
        schema:
          type: string
        description: The name of the schema table (e.g., schools, students, sections)
        example: schools
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Projection'
      responses:
        '200':
          description: Table records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaTableResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Table not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ws/schema/table/{tableName}/count:
    get:
      operationId: getSchemaTableCount
      summary: Count records in a schema table
      description: Returns the count of records in a named schema table.
      tags:
      - District
      parameters:
      - name: tableName
        in: path
        required: true
        schema:
          type: string
        description: The name of the schema table
      responses:
        '200':
          description: Record count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceCount'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Student:
      type: object
      description: A student record with demographics and contact information
      required:
      - id
      properties:
        id:
          type: integer
          description: Student DCID (district-level unique identifier)
        local_id:
          type: integer
          description: Student number (local identifier within district)
        student_username:
          type: string
          description: Student's portal username
        name:
          $ref: '#/components/schemas/Name'
        demographics:
          $ref: '#/components/schemas/Demographics'
        addresses:
          $ref: '#/components/schemas/Addresses'
        phones:
          $ref: '#/components/schemas/Phones'
    SchemaTableResponse:
      type: object
      description: Records from a schema table query
      properties:
        record:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Array of records from the table; field names match column names in the schema table
    School:
      type: object
      description: A school within a district
      required:
      - id
      properties:
        id:
          type: integer
          description: School DCID (district-level unique identifier)
        school_number:
          type: integer
          description: School number (local identifier)
        name:
          type: string
          description: Full name of the school
        state_province_id:
          type: string
          description: State or province identifier
        low_grade:
          type: integer
          description: Lowest grade level served (e.g., -2 for pre-K, 0 for K, 1-12)
        high_grade:
          type: integer
          description: Highest grade level served
        alternate_school_number:
          type: integer
          description: Alternate school number if applicable
        addresses:
          $ref: '#/components/schemas/Addresses'
        phones:
          $ref: '#/components/schemas/Phones'
        principal:
          $ref: '#/components/schemas/SchoolPrincipal'
        assistant_principal:
          $ref: '#/components/schemas/SchoolPrincipal'
    PhoneNumber:
      type: object
      properties:
        number:
          type: string
          description: Phone number string
    SchoolPrincipal:
      type: object
      description: Principal or assistant principal contact info
      properties:
        email:
          type: string
          format: email
          description: Principal's email address
        name:
          $ref: '#/components/schemas/Name'
    Name:
      type: object
      description: A person's name parts
      properties:
        first_name:
          type: string
          description: Given name
        middle_name:
          type: string
          description: Middle name
        last_name:
          type: string
          description: Surname / family name
    Phones:
      type: object
      description: Phone numbers for a person or school
      properties:
        fax:
          $ref: '#/components/schemas/PhoneNumber'
        home_phone:
          $ref: '#/components/schemas/PhoneNumber'
        main:
          $ref: '#/components/schemas/PhoneNumber'
    SchoolsResponse:
      type: object
      description: Paginated list of school records
      properties:
        schools:
          type: object
          properties:
            school:
              oneOf:
              - $ref: '#/components/schemas/School'
              - type: array
                items:
                  $ref: '#/components/schemas/School'
              description: Single school or array of schools
    Address:
      type: object
      description: A mailing or physical address
      properties:
        city:
          type: string
          description: City name
        postal_code:
          type: integer
          description: ZIP or postal code
        state_province:
          type: string
          description: State or province abbreviation
        street:
          type: string
          description: Street address line
    Demographics:
      type: object
      description: Demographic information for a student
      properties:
        birth_date:
          type: string
          format: date
          description: Student's date of birth (YYYY-MM-DD)
        district_entry_date:
          type: string
          format: date
          description: Date the student entered the district
        gender:
          type: string
          description: Gender identifier as defined by the school/district
        projected_graduation_year:
          type: integer
          description: Projected graduation year
    Error:
      type: object
      description: API error response
      properties:
        message:
          type: string
          description: Human-readable error description
        error:
          type: string
          description: Error code or type
        status:
          type: integer
          description: HTTP status code
    Addresses:
      type: object
      description: Collection of address types for a person or school
      properties:
        home:
          $ref: '#/components/schemas/Address'
        mailing:
          $ref: '#/components/schemas/Address'
        physical:
          $ref: '#/components/schemas/Address'
    StudentsResponse:
      type: object
      description: Paginated list of student records
      properties:
        students:
          type: object
          properties:
            student:
              oneOf:
              - $ref: '#/components/schemas/Student'
              - type: array
                items:
                  $ref: '#/components/schemas/Student'
              description: Single student object or array of student objects depending on result count
    ResourceCount:
      type: object
      description: Count of a resource collection
      properties:
        resource:
          type: object
          properties:
            count:
              type: integer
              description: Total number of records in the resource collection
  parameters:
    PageSize:
      name: pagesize
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
      description: Number of records to return per page.
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number for paginated results (1-indexed).
    Projection:
      name: projection
      in: query
      required: false
      schema:
        type: string
      description: Comma-separated list of fields to include in the response. Omit to return all fields.
      example: id,name,school_number
    Query:
      name: q
      in: query
      required: false
      schema:
        type: string
      description: 'Filter expression using FIQL-like syntax. Example: id=ge=10000 to filter records with id >= 10000.'
      example: id=ge=10000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from /oauth/access_token/ using client credentials. Tokens expire and must be refreshed.
    BasicAuth:
      type: http
      scheme: basic
      description: Basic auth with Base64-encoded client_id:client_secret for the token endpoint only.