Politecnico di Torino
PoliTO REST API (api-spec)

The official OpenAPI 3.0.3 specification for the REST API of Politecnico di Torino, maintained as the single source of truth for planning, implementation, testing, documentation, and tooling. It backs the official students mobile application and is authored in TypeSpec, with a generated openapi.yaml, a Dockerized Swagger UI, and Prism mock support. The API is consumed by first-party apps via the app.didattica.polito.it host; there is no documented self-service public sign-up.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: Polito Students API
  version: 0.0.1
  license:
    name: CC BY-NC 4.0
    url: https://creativecommons.org/licenses/by-nc/4.0/
tags:
  - name: Announcements
  - name: Auth
  - name: Bookings
  - name: Courses
  - name: Lectures
  - name: News
  - name: People
  - name: Places
  - name: Esc
  - name: Exams
  - name: Job offers
  - name: Offering
  - name: Student
  - name: Surveys
  - name: Tickets
paths:
  /announcements:
    get:
      operationId: Announcements_getAnnouncements
      summary: List announcements | Lista annunci
      parameters:
        - name: new
          in: query
          required: false
          schema:
            type: boolean
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Announcement'
                required:
                  - data
              example:
                data:
                  - id: abc-123
                    title: Welcome to the app
                    contents: Here is a quick guide to get started.
                    description: Onboarding announcement
                    scope: onboarding
                    seen: false
                    date: '2026-01-01T12:00:00Z'
                  - id: def-456
                    title: New feature available
                    contents: Check out the new booking system.
                    scope: appInfo
                    seen: true
                    date: '2026-02-15T09:30:00Z'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Announcements
  /announcements/{announcementId}/read:
    put:
      operationId: Announcements_markAnnouncementAsRead
      summary: Mark announcement as read | Segna annuncio come letto
      parameters:
        - name: announcementId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Announcements
  /auth/client:
    patch:
      operationId: Auth_appInfo
      summary: Update client version fields | Aggiorna i campi di versione del client
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UpdateInfo'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppInfoRequest'
  /auth/login:
    post:
      operationId: Auth_login
      summary: Login
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Identity'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      security:
        - {}
  /auth/logout:
    delete:
      operationId: Auth_logout
      summary: Logout
      description: Invalidates the provided token
      parameters: []
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
  /auth/mfa/challenge:
    get:
      operationId: Mfa_fetchChallenge
      summary: Fetch pending challenge
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    allOf:
                      - $ref: '#/components/schemas/MfaChallenge'
                    nullable: true
                required:
                  - data
              example:
                data:
                  serial: EDUP000123456
                  challenge: dGhpcyBzaG91bGQgYmUgYW4gZWNkcyBwdWJsaWMga2V5Li4uIHdoYXQgZGlkIHlvdSB0aGluayB0aGlzIHdhcz8hIPCfp5AK
                  requestTs: '2025-01-01T00:00:00Z'
                  expirationTs: '2025-01-01T01:00:00Z'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
  /auth/mfa/enrol:
    post:
      operationId: Mfa_enrolMfa
      summary: Enroll a new PUSH token
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      serial:
                        type: string
                        example: EDUP000123456
                    required:
                      - serial
                required:
                  - data
              example:
                data:
                  serial: EDUP000123456
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrolMfaRequest'
  /auth/mfa/status:
    get:
      operationId: Mfa_getMfaStatus
      summary: Get MFA status for the current user
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MfaStatusResponse'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
  /auth/mfa/validate:
    post:
      operationId: Mfa_validateMfa
      summary: Validate a challenge
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                    required:
                      - success
                required:
                  - data
              example:
                data:
                  success: true
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateMfaRequest'
  /auth/serviceLink/liveClass/{meetingID}:
    get:
      operationId: ServiceLink_getLiveClassLink
      summary: Get authorised service link for LiveClass meeting
      parameters:
        - name: meetingID
          in: path
          required: true
          description: LiveClass meeting identifier
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LinkToService'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
  /auth/serviceLink/mail:
    get:
      operationId: ServiceLink_getMailLink
      summary: Get authorised service link for Mail
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LinkToService'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
  /auth/serviceLink/moodle/{course}:
    get:
      operationId: ServiceLink_getMoodleLink
      summary: Get authorised service link for Moodle course
      parameters:
        - name: course
          in: path
          required: true
          description: Moodle course identifier
          schema:
            type: integer
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LinkToService'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
  /auth/switch-career:
    post:
      operationId: Auth_switchCareer
      summary: Switch career | Cambia carriera
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Identity'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchCareerRequest'
  /booking-topics:
    get:
      operationId: BookingTopics_getBookingTopics
      summary: List booking topics | Elenca ambiti di prenotazione
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BookingTopic'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
  /booking-topics/{bookingTopicId}/slots:
    get:
      operationId: BookingTopics_getBookingSlots
      summary: Show booking slots | Mostra turni prenotabili
      parameters:
        - name: bookingTopicId
          in: path
          required: true
          schema:
            type: string
        - name: fromDate
          in: query
          required: false
          description: First day - defaults to monday of current week
          schema:
            type: string
            format: date
          explode: false
        - name: toDate
          in: query
          required: false
          description: Last day - defaults to sunday of current week
          schema:
            type: string
            format: date
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BookingSlot'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
  /booking-topics/{bookingTopicId}/slots/{bookingSlotId}/seats:
    get:
      operationId: BookingTopics_getBookingSeats
      summary: Show seats for a booking slots | Mostra posti prenotabili
      parameters:
        - name: bookingTopicId
          in: path
          required: true
          schema:
            type: string
        - name: bookingSlotId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BookingSeats'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
  /bookings:
    get:
      operationId: BookingsManagement_getBookings
      summary: List bookings | Elenca prenotazioni
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Booking'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
    post:
      operationId: BookingsManagement_createBooking
      summary: Create booking | Crea prenotazione
      parameters: []
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBookingRequest'
  /bookings/{bookingId}:
    delete:
      operationId: BookingsManagement_deleteBooking
      summary: Delete booking | Cancella prenotazione
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
    patch:
      operationId: BookingsManagement_updateBooking
      summary: Update booking | Aggiorna prenotazione
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Bookings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBookingRequest'
  /courses/{courseId}:
    get:
      operationId: Courses_getCourse
      summary: Show course | Mostra corso
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Course'
                required:
                  - data
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Courses
  /courses/{courseId}/assignments:
    get:
      operationId: Courses_getCourseAssignments
      summary: List assignments | Elenca elaborati
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CourseAssignment'
                required:
                  - data
              example:
                data:
                  - id: 1003948
                    description: extrapoints2
                    mimeType: application/x-zip-compressed
                    filename: extrapoints2.zip
                    uploadedAt: '2022-01-21T14:38:00Z'
                    deletedAt: null
                    url: https://file.didattica.polito.it/down/ELABORATI_PRE/1003948/S290683/14576f69df588d55b631c3c3c30de3f5/6305eae6
                    sizeInKiloBytes: 195
                  - id: 993784
                    description: extrapoints1
                    mimeType: application/x-zip-compressed
                    filename: extrapoints1.zip
                    uploadedAt: '2022-01-10T18:53:00Z'
                    deletedAt: null
                    url: https://file.didattica.polito.it/down/ELABORATI_PRE/993784/S290683/15c275f7f7682c6acb5acd07d24590a9/6305eae6
                    sizeInKiloBytes: 401
                  - id: 982517
                    description: lab_09
                    mimeType: application/zip
                    filename: lab_09.zip
                    uploadedAt: '2021-12-16T22:48:00Z'
                    deletedAt: null
                    url: https://file.didattica.polito.it/down/ELABORATI_PRE/982517/S290683/29288344d27567de6ddf0fa718b980a5/6305eae6
                    sizeInKiloBytes: 126
                  - id: 934034
                    description: lab_01
                    mimeType: application/x-zip-compressed
                    filename: lab_01.zip
                    uploadedAt: '2021-10-13T11:20:00Z'
                    deletedAt: null
                    url: https://file.didattica.polito.it/down/ELABORATI_PRE/934034/S290683/fd675d8a411d0747885b24e473a5d683/6305eae6
                    sizeInKiloBytes: 144
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Courses
    post:
      operationId: Courses_uploadCourseAssignment
      summary: Upload assignment | Carica elaborato
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Courses
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CourseAssignmentUpload'
  /courses/{courseId}/assignments/{assignmentId}:
    patch:
      operationId: Courses_updateAssignment
      summary: Update assignment | Aggiorna elaborato
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: integer
        - name: assignmentId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
        - Courses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssignmentRequest'
  /courses/{courseId}/files:
    get:
      operationId: Courses_getCourseFiles
      summary: List files | Elenca file
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CourseDirectoryContent'
                required:
                  - data
              example:
                data:
                  - id: '33248655'
                    name: videolectures
                    type: directory
                    files:
                      - id: '33248890'
                        name: HCI2021-L01 2021-09-28 13-06-26.m4v
                        sizeInKiloBytes: 123428
                        mimeType: video/x-m4v
                        createdAt: '2021-09-28T16:31:43Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000000
                      - id: '33251708'
                        name: HCI2021-L02 2021-09-30 08-34-32.mp4
                        sizeInKiloBytes: 248172
                        mimeType: video/mp4
                        createdAt: '2021-09-30T10:20:50Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000001
                      - id: '33256476'
                        name: HCI2021-L03 2021-10-05 13-06-47.mp4
                        sizeInKiloBytes: 243792
                        mimeType: video/mp4
                        createdAt: '2021-10-05T15:00:15Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000002
                      - id: '33257988'
                        name: HCI2021-L04 2021-10-07 08-35-46.mp4
                        sizeInKiloBytes: 244993
                        mimeType: video/mp4
                        createdAt: '2021-10-07T11:12:25Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000003
                      - id: '33262287'
                        name: HCI2021-L05 2021-10-12 13-05-46.mp4
                        sizeInKiloBytes: 298172
                        mimeType: video/mp4
                        createdAt: '2021-10-12T16:11:46Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000004
                      - id: '33265387'
                        name: HCI2021-L06 2021-10-14 08-35-12.mp4
                        sizeInKiloBytes: 285926
                        mimeType: video/mp4
                        createdAt: '2021-10-14T11:25:20Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000005
                      - id: '33269079'
                        name: HCI2021-L07 2021-10-19 13-10-40.mp4
                        sizeInKiloBytes: 234466
                        mimeType: video/mp4
                        createdAt: '2021-10-19T15:02:22Z'
                        type: file
                        checksum: deadbeefcafebabe0000000000000006
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  

# --- truncated at 32 KB (219 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/politecnico-di-torino/refs/heads/main/openapi/politecnico-di-torino-students-api.yaml
PoliTO REST API (api-spec)

Documentation

Specifications

Other Resources

OpenAPI Specification
