University of Toronto Reference Data API

openapi: 3.2.0
info:
  title: University of Toronto Timetable Builder Reference Data API
  version: '2026-08-19'
  x-operator: institution
  x-provenance:
    generated: '2026-08-19'
    method: derived
    source: Derived by API Evangelist from live, unauthenticated probes of https://api.easi.utoronto.ca/ttb on 2026-08-19 and from the operation constants declared in the official Timetable Builder client bundle at https://ttb.utoronto.ca/main.934e36b03104594f.js. The University of Toronto does not publish an OpenAPI description for this API; this document is a third-party observation, not a University of Toronto artifact.
  description: Unofficial, observation-derived description of the public JSON API behind the University of Toronto Timetable Builder (https://ttb.utoronto.ca), operated by Enterprise Applications and Solutions Integration (EASI) within U of T Information Technology Services.
  contact:
    name: University of Toronto — Enterprise Applications and Solutions Integration (EASI)
    url: https://easi.its.utoronto.ca/
  termsOfService: https://www.utoronto.ca/privacy
servers:
- url: https://api.easi.utoronto.ca/ttb
  description: Production Timetable Builder API (probed live 2026-08-19)
tags:
- name: Reference Data
  description: Sessions, divisions, campuses and other search facets.
paths:
  /reference-data:
    get:
      tags:
      - Reference Data
      operationId: getReferenceData
      summary: Retrieve every search facet the Timetable Builder UI offers
      description: 'Returns the current sessions, divisions, campuses, degree requirements, course levels, delivery modes, day and time preferences, credit weights and sort directions. Verified live 2026-08-19: HTTP 200, application/json, ~11.7 KB.'
      responses:
        '200':
          description: Reference data envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceDataEnvelope'
              examples:
                live:
                  summary: Live capture, lists trimmed
                  externalValue: ../examples/ttb-reference-data-response.json
        '404':
          $ref: '#/components/responses/GatewayNotFound'
  /current-session:
    get:
      tags:
      - Reference Data
      operationId: getCurrentSession
      summary: List the sessions currently open in the timetable
      description: 'Returns the session options (for example "Summer 2026", value 20265) that a course search may be scoped to. Verified live 2026-08-19: HTTP 200, application/json.'
      responses:
        '200':
          description: Session option list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionListEnvelope'
              examples:
                live:
                  externalValue: ../examples/ttb-current-session-response.json
        '404':
          $ref: '#/components/responses/GatewayNotFound'
  /getMatchingDivisions:
    get:
      tags:
      - Reference Data
      operationId: getMatchingDivisions
      summary: Type-ahead lookup of academic divisions
      description: Returns divisions whose name matches the supplied query, as option objects carrying the division code in `value` (for example APSC for the Faculty of Applied Science & Engineering). Verified live 2026-08-19 with query=arts.
      parameters:
      - name: query
        in: query
        required: true
        description: Free-text fragment matched against division names.
        schema:
          type: string
        example: arts
      responses:
        '200':
          description: Matching divisions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionListEnvelope'
              examples:
                live:
                  externalValue: ../examples/ttb-matching-divisions-response.json
        '404':
          $ref: '#/components/responses/GatewayNotFound'
components:
  schemas:
    ApplicationStatus:
      type: object
      description: Business-level status returned inside the response body. Observed value 4404 = no results. The University publishes no catalogue of these codes; see errors/ for what has been observed.
      properties:
        code:
          type: integer
          example: 4404
        message:
          type: string
          example: No results found. Please try modifying your search criteria.
    OptionListEnvelope:
      type: object
      properties:
        payload:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        status:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationStatus'
    ReferenceDataEnvelope:
      type: object
      properties:
        payload:
          type: object
          properties:
            currentSessions:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            divisions:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            campuses:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            requirements:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            courseLevels:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            temporaryDeliveryModes:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            deliveryModes:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            dayPreferences:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            timePreferences:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            creditWeights:
              type: array
              items:
                $ref: '#/components/schemas/Option'
            directions:
              type: object
              additionalProperties:
                type: string
        status:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationStatus'
    Option:
      type: object
      description: A selectable facet value used by the Timetable Builder UI.
      properties:
        label:
          type: string
          example: Summer 2026
        value:
          type: string
          example: '20265'
        selected:
          type: boolean
        header:
          type: boolean
          description: True when the option is a non-selectable group heading.
        group:
          type:
          - string
          - 'null'
          example: Summer-20265
        metadata:
          type: object
          properties:
            name:
              type:
              - string
              - 'null'
            type:
              type:
              - string
              - 'null'
    GatewayError:
      type: object
      description: Edge-level error emitted by the api.easi.utoronto.ca gateway before the TTB service is reached.
      properties:
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: Resource not found
  responses:
    GatewayNotFound:
      description: The gateway did not match a route.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          examples:
            live:
              externalValue: ../examples/ttb-gateway-404-response.json