openapi: 3.2.0
info:
  title: University of Groningen Ocasys Course Catalog Courses API
  version: 2026-2027
  summary: Keyless read API behind Ocasys, the University of Groningen course and programme catalog.
  description: Ocasys (ocasys.rug.nl) is the University of Groningen's own course and degree-programme catalog.
  contact:
    name: University of Groningen — Center for Information Technology
    url: https://www.rug.nl/society-business/center-for-information-technology/
  termsOfService: https://www.rug.nl/info/disclaimer-copyright
  license:
    name: No licence published for the interface or its data
    identifier: NOASSERTION
servers:
- url: https://ocasys.rug.nl/api
  description: Production Ocasys backend (institution-operated, verified live 2026-08-30)
tags:
- name: Courses
  description: Course search and full course descriptions.
paths:
  /{academicYear}/course:
    get:
      tags:
      - Courses
      operationId: searchCourses
      summary: Search courses within one academic year
      parameters:
      - $ref: '#/components/parameters/AcademicYear'
      - name: searchTerm
        in: query
        required: true
        description: Free-text term matched against course code and title. Omitting it returns 400 with a problem+json body.
        schema:
          type: string
      responses:
        '200':
          description: Matching course summaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CourseSummary'
        '400':
          $ref: '#/components/responses/ProblemBadRequest'
  /{academicYear}/course/{courseCode}:
    get:
      tags:
      - Courses
      operationId: getCourse
      summary: Get one course by its catalog code
      parameters:
      - $ref: '#/components/parameters/AcademicYear'
      - $ref: '#/components/parameters/CourseCode'
      responses:
        '200':
          description: Full course record including goals, description, assessments and offerings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Course'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
  /{academicYear}/course/page/{courseCode}:
    get:
      tags:
      - Courses
      operationId: getCoursePage
      summary: Get the catalog page projection of one course
      description: Same course, shaped for the public catalog page — faculty and department are expanded to full organizational-unit objects.
      parameters:
      - $ref: '#/components/parameters/AcademicYear'
      - $ref: '#/components/parameters/CourseCode'
      responses:
        '200':
          description: Course page projection
          content:
            application/json:
              schema:
                type: object
        '404':
          $ref: '#/components/responses/ProblemNotFound'
  /{academicYear}/course-offering:
    get:
      tags:
      - Courses
      operationId: listCourseOfferings
      summary: List course offerings (institutional session required)
      description: Documented as observed, not as callable. Probed 2026-08-30 with no credentials and returned 403 with an empty body. Access is gated behind the University's SAML single sign-on (signon.rug.nl); there is no public key, token or self-service registration for it.
      parameters:
      - $ref: '#/components/parameters/AcademicYear'
      - name: permission
        in: query
        required: false
        schema:
          type: string
      responses:
        '403':
          description: Forbidden without an institutional session
components:
  schemas:
    Course:
      type: object
      description: Full course record as served for a single course code.
      properties:
        id:
          type: string
          format: uuid
        year:
          type: string
        code:
          type: string
        facultyCode:
          type: string
        facultyTitle:
          $ref: '#/components/schemas/LocalizedText'
        title:
          $ref: '#/components/schemas/LocalizedText'
        fullTitle:
          $ref: '#/components/schemas/LocalizedText'
        goals:
          $ref: '#/components/schemas/LocalizedText'
        description:
          $ref: '#/components/schemas/LocalizedText'
        prerequisites:
          $ref: '#/components/schemas/LocalizedText'
        credits:
          type: number
        hours:
          type: integer
          description: Contact hours; -1 where not recorded.
        levels:
          type: array
          items:
            type: string
        formats:
          type: array
          items:
            type: object
        assessments:
          type: array
          items:
            type: object
        courseTypes:
          type: array
          items:
            type: object
        courseOfferings:
          type: array
          items:
            type: object
        organizationalUnit:
          type: string
          format: uuid
        organizationalUnitTitle:
          $ref: '#/components/schemas/LocalizedText'
        sustainableDevelopmentGoals:
          type: object
          description: Per-course flags for the seventeen UN Sustainable Development Goals.
        enlight:
          type: string
          description: Whether the course is offered through the ENLIGHT European university alliance.
        draft:
          type: boolean
        startYear:
          type: string
        endYear:
          type:
          - string
          - 'null'
        modifiedAt:
          type: array
          items:
            type: integer
          description: Java LocalDateTime serialized as an array of integers.
    Problem:
      type: object
      description: RFC 9457 problem detail, as emitted by the Spring backend.
      properties:
        type:
          type: string
          examples:
          - about:blank
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
    LocalizedText:
      type: object
      description: Bilingual string, Dutch and English. The catalog is authored in both languages.
      properties:
        en:
          type: string
        nl:
          type: string
    CourseSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        code:
          type: string
        title:
          $ref: '#/components/schemas/LocalizedText'
        levels:
          type: array
          description: Observed values across the 2026-2027 catalog, in frequency order.
          items:
            type: string
            enum:
            - MASTER
            - BACHELOR
            - EXCHANGE
            - PRE_MASTER
            - UNIVERSITY_LEVEL_MINOR
            - FACULTY_LEVEL_MINOR
            - POST_GRADUATE
        credits:
          type: number
          description: ECTS credits
        otherPeriods:
          type: boolean
        draft:
          type: boolean
  parameters:
    CourseCode:
      name: courseCode
      in: path
      required: true
      description: Catalog course code, e.g. WMMB015-05.
      schema:
        type: string
    AcademicYear:
      name: academicYear
      in: path
      required: true
      description: Academic year in YYYY-YYYY form, e.g. 2026-2027. A value that does not parse returns 400.
      schema:
        type: string
        pattern: ^[0-9]{4}-[0-9]{4}$
  responses:
    ProblemNotFound:
      description: RFC 9457 problem detail
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ProblemBadRequest:
      description: RFC 9457 problem detail
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
x-method: probed
x-generated: '2026-08-30'
x-source:
- https://ocasys.rug.nl/api/year-status
- https://ocasys.rug.nl/api/orgunit/faculties-and-universities
- https://ocasys.rug.nl/api/2026-2027/course?searchTerm=biology
- https://ocasys.rug.nl/api/2026-2027/course/WMMB015-05
- https://ocasys.rug.nl/api/2026-2027/course/page/WMMB015-05
- https://ocasys.rug.nl/api/2026-2027/program?searchTerm=biology
- https://ocasys.rug.nl/api/2026-2027/option-list
- https://ocasys.rug.nl/api/year/next-academic-year-start-date
x-operator: institution