> ## 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.

# Public Holiday Options

> Returns public holiday option metadata for building filters and navigation: available years, coverage modes (`all` vs `nationwide`), and the full states/territories list. In holiday rows, nationwide means `states` lists all 16 territory slugs. Use `GET /api/v1/public-holiday` for rows and aggregates (including date range in `meta`).



## OpenAPI

````yaml GET /api/v1/public-holiday/meta
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/public-holiday/meta:
    get:
      summary: Public Holiday Options (Meta)
      description: >-
        Returns public holiday option metadata for building filters and
        navigation: available years, coverage modes (`all` vs `nationwide`), and
        the full states/territories list. In holiday rows, nationwide means
        `states` lists all 16 territory slugs. Use `GET /api/v1/public-holiday`
        for rows and aggregates (including date range in `meta`).
      responses:
        '200':
          description: >-
            Public holiday option metadata including year, coverage, and state
            lists; use /api/v1/public-holiday for row data and aggregates.
          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/PublicHolidayMetaResponse'
        '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
        '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:
    PublicHolidayMetaResponse:
      type: object
      required:
        - apiVersion
        - baseUrl
        - defaultYear
        - yearOptions
        - coverageOptions
        - stateOptions
      properties:
        apiVersion:
          type: string
        baseUrl:
          type: string
        defaultYear:
          type: integer
        yearOptions:
          type: array
          items:
            $ref: '#/components/schemas/PublicHolidayYearOption'
        coverageOptions:
          type: array
          items:
            $ref: '#/components/schemas/PublicHolidayCoverageOption'
        stateOptions:
          type: array
          items:
            $ref: '#/components/schemas/PublicHolidayOption'
      example:
        apiVersion: '1'
        baseUrl: https://api.bilauitmcuti.com
        defaultYear: 2026
        yearOptions:
          - value: 2026
            label: '2026'
        coverageOptions:
          - value: all
            label: All States
          - value: nationwide
            label: Nationwide only
        stateOptions:
          - value: selangor
            label: Selangor
    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.
    PublicHolidayYearOption:
      type: object
      required:
        - value
        - label
      properties:
        value:
          type: integer
        label:
          type: string
    PublicHolidayCoverageOption:
      type: object
      required:
        - value
        - label
      properties:
        value:
          type: string
          enum:
            - all
            - nationwide
        label:
          type: string
    PublicHolidayOption:
      type: object
      required:
        - value
        - label
      properties:
        value:
          type: string
        label:
          type: string

````

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