openapi: 3.2.0
info:
  title: KU Leuven ICTS Data Services Programs API
  description: Institution-operated read API for KU Leuven's public reference data, run by KU Leuven ICTS and documented at https://admin.kuleuven.be/icts/services/dataservices. The gateway at dataservice.kuleuven.be exposes an OpenSearch/Elasticsearch query surface over eight public indices — staff directory (wie-is-wie), academic CVs, organisational chart, educational offering (programme guide), research projects, research teams, research infrastructure and job vacancies — each published in a Dutch and an English index. Reads are unauthenticated and were confirmed live on 2026-08-19; the underlying data is governed by the KU Leuven Data Service terms of use.
  version: '2026-08-19'
  contact:
    name: KU Leuven ICTS Data Services
    url: https://admin.kuleuven.be/icts/services/dataservices/data-service-vraag
  termsOfService: https://admin.kuleuven.be/icts/services/dataservices/gebruiksvoorwaarden.html
  x-operator: institution
  x-provenance:
    generated: '2026-08-19'
    method: derived
    source: Derived from KU Leuven ICTS Data Services documentation pages (admin.kuleuven.be/icts/services/dataservices/*) and confirmed against live unauthenticated responses from https://dataservice.kuleuven.be on 2026-08-19. No endpoint, parameter or field appears here that is not documented by KU Leuven or observed in a live response.
servers:
- url: https://dataservice.kuleuven.be
  description: KU Leuven ICTS Data Services production query gateway
tags:
- name: Programs
  description: Educational offering — degree programmes in the programme guide (onderwijsaanbod).
paths:
  /pg/_search:
    get:
      summary: Search the current-academic-year programme guide index
      description: '`pg` aliases the current academic year. Year-specific indices are addressable directly as `pg<year>` (for example `pg2025`); the academic year rolls over on 15 July.'
      operationId: pg_search_get
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search hits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/QueryError'
      tags:
      - Programs
      x-verified: '2026-08-19'
  /pg{year}/_search:
    get:
      summary: Search a specific academic year's programme guide index
      operationId: pg_year_search_get
      parameters:
      - name: year
        in: path
        required: true
        description: Four-digit academic year, e.g. 2025 or 2026.
        schema:
          type: string
          pattern: ^[0-9]{4}$
      responses:
        '200':
          description: Search hits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
      tags:
      - Programs
      x-verified: '2026-08-19'
  /pg/_doc/{id}:
    get:
      summary: Retrieve one programme document by identifier
      operationId: pg_doc_get
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/SourceFields'
      responses:
        '200':
          description: Document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '404':
          $ref: '#/components/responses/DocumentNotFound'
      tags:
      - Programs
components:
  responses:
    QueryError:
      description: Malformed query document.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    DocumentNotFound:
      description: No document with that identifier in the index.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DocumentResponse'
  schemas:
    SearchRequest:
      type: object
      description: OpenSearch query document as documented by KU Leuven ICTS.
      properties:
        query:
          type: object
          description: Query clause, e.g. `match_all` or `query_string`.
        aggs:
          type: object
          description: Aggregations, previously described by ICTS as filters or facets.
        _source:
          type: array
          description: Field list to return (ICTS documents this as returnFields).
          items:
            type: string
        from:
          type: integer
          description: Start position for pagination.
        size:
          type: integer
          description: Number of hits to return. Default 10.
          default: 10
    SearchResponse:
      type: object
      description: Standard OpenSearch search response envelope, as returned live on 2026-08-19.
      properties:
        took:
          type: integer
        timed_out:
          type: boolean
        _shards:
          type: object
          properties:
            total:
              type: integer
            successful:
              type: integer
            skipped:
              type: integer
            failed:
              type: integer
        hits:
          type: object
          properties:
            total:
              type: object
              properties:
                value:
                  type: integer
                relation:
                  type: string
                  enum:
                  - eq
                  - gte
            max_score:
              type:
              - number
              - 'null'
            hits:
              type: array
              items:
                $ref: '#/components/schemas/Hit'
        aggregations:
          type: object
          description: Present when the request supplied `aggs`.
    DocumentResponse:
      type: object
      description: Single-document response from `_doc/{id}`.
      properties:
        _index:
          type: string
        _id:
          type: string
        found:
          type: boolean
        _source:
          type: object
    Hit:
      type: object
      properties:
        _index:
          type: string
          description: Physical index name. Snapshot indices carry a build timestamp, e.g. `employee_2026-07-08_12h33m04s211`, which reveals the refresh date of the data.
        _id:
          type: string
        _score:
          type:
          - number
          - 'null'
        _source:
          type: object
          description: The document. Field sets differ per index.
    ErrorResponse:
      type: object
      description: OpenSearch error envelope, captured live from a malformed query on 2026-08-19.
      properties:
        error:
          type: object
          properties:
            root_cause:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  reason:
                    type: string
                  line:
                    type: integer
                  col:
                    type: integer
            type:
              type: string
            reason:
              type: string
            caused_by:
              type: object
        status:
          type: integer
  parameters:
    SourceFields:
      name: _source
      in: query
      required: false
      description: Comma-separated list of fields to return.
      schema:
        type: string
    DocId:
      name: id
      in: path
      required: true
      description: Document identifier within the index.
      schema:
        type: string