> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bilauitmcuti.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar Activities

> Returns calendar activity rows for one session or multiple sessions in a group. Optional filters such as `program` and `type` can narrow the result set.



## OpenAPI

````yaml GET /api/v1/calendar
openapi: 3.0.3
info:
  title: Bila UiTM Cuti API
  version: '1'
  description: >-
    Unofficial API for UiTM academic calendar and Malaysian public holidays. Not
    affiliated with UiTM; verify important dates before production use.


    Rate limits (production): 500 requests per 60s per IP (CF-Connecting-IP) per
    endpoint; heavy calendar/meta modes (60 per 60s additional). GET /api/health
    is excluded. Cacheable successes expose RateLimit-Policy; 429 includes
    X-RateLimit-* / RateLimit / Retry-After. Optional remaining peek: GET
    /api/v1/rate-limit.
servers:
  - url: https://api.bilauitmcuti.com
security: []
paths:
  /api/v1/calendar:
    get:
      summary: Calendar Activities
      description: >-
        Returns calendar activity rows for one session or multiple sessions in a
        group. Optional filters such as `program` and `type` can narrow the
        result set.
      parameters:
        - name: all
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - '1'
              - 'yes'
          description: >-
            When true (or "1"/"yes"), returns the full calendar dataset
            including defaults, options, and activities for all sessions. Legacy
            alias: `entire`.
          example: 'true'
        - name: session
          in: query
          required: false
          schema:
            type: string
          description: >-
            Session id from GET /api/v1/meta (`sessionOptions`). Do not
            hardcode; the published set changes each term. Omit to aggregate all
            sessions in the selected group.
          example: B-20264
        - name: group
          in: query
          required: false
          schema:
            type: string
            enum:
              - A
              - B
          description: Group filter for calendar lookup. Accepted values are "A" or "B".
          example: A
        - name: allSessions
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - '1'
              - 'yes'
          description: >-
            When true (or "1"/"yes"), returns activities for every session in
            the selected group.
          example: 'true'
        - name: program
          in: query
          required: false
          schema:
            type: string
            enum:
              - All
              - PreDiploma
              - Diploma
              - DiplomaPartTime
              - Bachelor
              - BachelorPartTime
              - Master
              - PhD
          description: Program filter, typically used for Group B data.
          example: Diploma
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - lecture
              - break
              - examination
              - registration
              - other
          description: >-
            Activity type filter such as lecture, break, examination,
            registration, or other.
          example: break
      responses:
        '200':
          description: >-
            Calendar data; shape depends on all, allSessions, or single-session
            query.
          headers:
            RateLimit-Policy:
              description: Published policies (RFC 9457).
              schema:
                type: string
                example: '"endpoint";q=500;w=60, "heavy";q=60;w=60'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarSuccessResponse'
        '304':
          description: >-
            Not Modified. Empty body when If-None-Match matches the current
            ETag; Cache-Control and ETag headers are still sent.
          headers:
            RateLimit-Policy:
              description: Published policies (RFC 9457).
              schema:
                type: string
                example: '"endpoint";q=500;w=60, "heavy";q=60;w=60'
            ETag:
              description: Weak entity tag for this representation.
              schema:
                type: string
            Cache-Control:
              description: Caching policy for successful API responses.
              schema:
                type: string
        '400':
          description: >-
            Invalid or conflicting query parameters. Body: { error: string,
            detail?: string }.
          headers:
            X-RateLimit-Limit:
              description: >-
                Maximum requests allowed in the current window for the active
                bucket.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: >-
                Approximate remaining requests in the current window
                (best-effort per worker isolate; not authoritative across edge
                locations).
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when the current rate-limit window resets.
              schema:
                type: integer
            RateLimit-Policy:
              description: Published policies (RFC 9457).
              schema:
                type: string
                example: '"endpoint";q=500;w=60, "heavy";q=60;w=60'
            RateLimit:
              description: Active bucket quota (RFC 9457), e.g. `"endpoint";r=499;t=42`.
              schema:
                type: string
            Retry-After:
              description: Seconds until the current rate-limit window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: >-
            No calendar bucket for the resolved session id (data missing for
            that session). Empty filter results return 200 with activities: [].
            Body: { error: string, detail?: string }.
          headers:
            X-RateLimit-Limit:
              description: >-
                Maximum requests allowed in the current window for the active
                bucket.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: >-
                Approximate remaining requests in the current window
                (best-effort per worker isolate; not authoritative across edge
                locations).
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when the current rate-limit window resets.
              schema:
                type: integer
            RateLimit-Policy:
              description: Published policies (RFC 9457).
              schema:
                type: string
                example: '"endpoint";q=500;w=60, "heavy";q=60;w=60'
            RateLimit:
              description: Active bucket quota (RFC 9457), e.g. `"endpoint";r=499;t=42`.
              schema:
                type: string
            Retry-After:
              description: Seconds until the current rate-limit window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: >-
            Rate limited (500 requests per 60s per endpoint per IP; heavy modes
            add 60 per 60s). Check Retry-After and rate-limit headers. Body
            includes error, detail, and retryAfter (seconds).
          headers:
            X-RateLimit-Limit:
              description: >-
                Maximum requests allowed in the current window for the active
                bucket.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: >-
                Approximate remaining requests in the current window
                (best-effort per worker isolate; not authoritative across edge
                locations).
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when the current rate-limit window resets.
              schema:
                type: integer
            RateLimit-Policy:
              description: Published policies (RFC 9457).
              schema:
                type: string
                example: '"endpoint";q=500;w=60, "heavy";q=60;w=60'
            RateLimit:
              description: Active bucket quota (RFC 9457), e.g. `"endpoint";r=499;t=42`.
              schema:
                type: string
            Retry-After:
              description: Seconds until the current rate-limit window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    CalendarSuccessResponse:
      oneOf:
        - $ref: '#/components/schemas/CalendarAllDataResponse'
        - $ref: '#/components/schemas/CalendarAllSessionsResponse'
        - $ref: '#/components/schemas/CalendarSingleSessionResponse'
      description: >-
        Success shape depends on query: all=true (full export), allSessions=true
        with group (multi-session), or a single resolved session.
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Short machine-friendly error code or message.
        detail:
          type: string
          description: Human-readable explanation (optional).
        retryAfter:
          type: integer
          description: Seconds to wait before retrying; present on 429 responses.
    CalendarAllDataResponse:
      type: object
      required:
        - apiVersion
        - baseUrl
        - all
        - defaultSession
        - sessionOptions
        - programOptions
        - sessions
      properties:
        apiVersion:
          type: string
        baseUrl:
          type: string
        all:
          type: boolean
          enum:
            - true
        defaultSession:
          $ref: '#/components/schemas/DefaultSessionMap'
        sessionOptions:
          type: array
          items:
            $ref: '#/components/schemas/SessionOption'
        programOptions:
          type: array
          items:
            $ref: '#/components/schemas/ProgramOption'
        sessions:
          $ref: '#/components/schemas/EntireSessionsMap'
    CalendarAllSessionsResponse:
      type: object
      required:
        - apiVersion
        - baseUrl
        - allSessions
        - group
        - filters
        - sessions
        - meta
      properties:
        apiVersion:
          type: string
        baseUrl:
          type: string
        allSessions:
          type: boolean
          enum:
            - true
        group:
          type: string
          enum:
            - A
            - B
        filters:
          $ref: '#/components/schemas/FiltersObject'
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/CalendarAllSessionsEntry'
        meta:
          $ref: '#/components/schemas/AllSessionsMeta'
    CalendarSingleSessionResponse:
      type: object
      required:
        - apiVersion
        - baseUrl
        - session
        - filters
        - activities
        - meta
      properties:
        apiVersion:
          type: string
        baseUrl:
          type: string
        session:
          $ref: '#/components/schemas/SessionRef'
        filters:
          $ref: '#/components/schemas/FiltersObject'
        activities:
          type: array
          items:
            $ref: '#/components/schemas/CalendarActivity'
        meta:
          $ref: '#/components/schemas/MetaPerSession'
    DefaultSessionMap:
      type: object
      required:
        - A
        - B
      properties:
        A:
          type: string
          description: Default session id for Group A.
        B:
          type: string
          description: Default session id for Group B.
    SessionOption:
      type: object
      required:
        - id
        - label
        - group
      properties:
        id:
          type: string
        label:
          type: string
        group:
          type: string
          description: A or B.
    ProgramOption:
      type: object
      required:
        - label
        - value
        - group
      properties:
        label:
          type: string
        value:
          type: string
        group:
          type: string
    EntireSessionsMap:
      type: object
      additionalProperties:
        type: object
        required:
          - activities
        properties:
          activities:
            type: array
            items:
              $ref: '#/components/schemas/CalendarActivity'
      description: >-
        Map of session id to activities bucket (same shape as the bundled
        calendar dataset).
    FiltersObject:
      type: object
      properties:
        program:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
    CalendarAllSessionsEntry:
      type: object
      required:
        - session
        - filters
        - activities
        - meta
      properties:
        session:
          $ref: '#/components/schemas/SessionRef'
        filters:
          $ref: '#/components/schemas/FiltersObject'
        activities:
          type: array
          items:
            $ref: '#/components/schemas/CalendarActivity'
        meta:
          $ref: '#/components/schemas/MetaPerSession'
    AllSessionsMeta:
      type: object
      required:
        - sessionCount
        - returnedActivities
      properties:
        sessionCount:
          type: integer
        returnedActivities:
          type: integer
    SessionRef:
      type: object
      required:
        - id
        - label
        - group
      properties:
        id:
          type: string
        label:
          type: string
        group:
          type: string
    CalendarActivity:
      type: object
      required:
        - name
        - startDate
        - endDate
        - type
        - group
      properties:
        name:
          type: string
          description: Activity title or label.
        startDate:
          type: string
          format: date
          description: Start date (ISO date).
        endDate:
          type: string
          format: date
          description: End date (ISO date).
        type:
          type: string
          description: >-
            Activity category (typical values: lecture, break, examination,
            registration, other).
        group:
          type: string
          description: Group code (e.g. A or B).
        duration:
          type: string
        details:
          type: string
        programType:
          type: string
        programTypes:
          type: array
          items:
            type: string
        allStudents:
          type: boolean
          description: When true, row applies to all students / cohort-wide.
        regionalStartDate:
          type: string
        regionalEndDate:
          type: string
    MetaPerSession:
      type: object
      required:
        - totalInSession
        - returned
      properties:
        totalInSession:
          type: integer
        returned:
          type: integer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.