Cardiff University Years API

openapi: 3.2.0
info:
  description: The Lookup API provides a simple interface for applications that just want to retrieve a list of items. Using the Lookup API, clients can retrieve lists of level/semester codes, subjects, and schools used within Cardiff University.
  version: v1
  title: LookupsApi Years API
  termsOfService: http://www.cardiff.ac.uk/terms/
  contact:
    name: integration@cardiff.ac.uk
  x-operator: institution
  x-source-contract: openapi/_original/cardiff-lookups.yaml
  x-rebased:
    date: '2026-08-30'
    rebase-method: derived
    source: openapi/_original/cardiff-lookups.yaml
    note: >-
      Repaired by the API Evangelist university pipeline. The refine-openapis per-tag split
      had carried the CoursesApi title, description and base path onto this document; its
      paths come from cardiff-lookups.yaml. Title, description and servers[] re-based from that parent.
      Was: title "CoursesApi Assessments Years API", servers[0] "https://api.data.cardiff.ac.uk/courses/v1".
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.data.cardiff.ac.uk/lookups/v1
security:
- default: []
tags:
- name: Years
paths:
  /years:
    get:
      tags:
      - Years
      summary: Retrieve a list of academic years within the Univesity.
      parameters:
      - name: mode
        in: query
        description: Mode of retrieving the list of year. Options are "current","between" and "amount". For "current" mode, it returns the current academic year in a single object. For "between" mode, input parameters "from" and "to" are used. (e.g. "from=2023&to=2033"). For "amount" mode, input parameters "from" and "numofyears" are used. (e.g. "from=2023&numofyears=12").
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: Using with "between" or "amount" mode. Selected year to start from (e.g. 2023). Default value is current academic year.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: Using with "between" mode. Selected year to end (inclustive) (e.g. 2033).
        required: false
        schema:
          type: string
      - name: numofyears
        in: query
        description: Using with "amount" mode. Number of years to return. It can be a positive number (select N years forward) or a negative number (select N years backward) (e.g. 12, -12)
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Sorts the data by column name, use "-" for descending
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Using without mode. Number of years to return
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Using without mode. Offset of years to return
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Returns a list of academic years
          content:
            application/json:
              schema:
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      years:
                        type: array
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            name:
                              type: string
                            startDate:
                              type: string
                            endDate:
                              type: string
                            current:
                              type: boolean
                          required:
                          - code
                          - name
                  meta:
                    $ref: '#/components/schemas/Meta'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: Unlimited
components:
  schemas:
    Meta:
      type: object
      required:
      - code
      - contentType
      - count
      - errorStatus
      properties:
        errorMessage:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
        count:
          type: integer
          format: int32
        code:
          type: integer
          format: int32
        contentType:
          type: string
        errorStatus:
          type: boolean
      title: meta
  securitySchemes:
    default:
      type: oauth2
      flows:
        implicit:
          scopes:
            clearing: Allows users to see clearing data.
          authorizationUrl: https://api.data.cardiff.ac.uk/authorize