openapi: 3.0.3
info:
  title: PowerSchool SIS REST Authentication Students 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: Students
  description: Student demographics, enrollment, and records
paths:
  /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:
      - Students
      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:
      - Students
      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/v1/district/student/{studentDcid}:
    get:
      operationId: getStudent
      summary: Get a specific student
      description: Returns a single student record by their DCID (district-level unique identifier).
      tags:
      - Students
      parameters:
      - name: studentDcid
        in: path
        required: true
        schema:
          type: integer
        description: The student's DCID (not student ID or student number)
      - $ref: '#/components/parameters/Projection'
      responses:
        '200':
          description: Student record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Student not found
          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'
    PhoneNumber:
      type: object
      properties:
        number:
          type: string
          description: Phone number string
    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'
    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
    StudentResponse:
      type: object
      description: Single student record response
      properties:
        student:
          $ref: '#/components/schemas/Student'
    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.