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

# Malaysia Public Holidays

> Returns Malaysia public holiday rows from `public-holiday.json`. Optional `year` scopes rows to a calendar year (defaults to `defaultYear` from the dataset, currently 2026 while that year is published). Optional `coverage` selects the full dataset for that year, nationwide-only rows, or (by default) you can filter with `state` for one of 16 states/territories. This endpoint focuses on holiday results and aggregates (including `meta.dateRange`); use `/api/v1/public-holiday/meta` for option lists only.



## OpenAPI

````yaml GET /api/v1/public-holiday
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:
    get:
      summary: Malaysia Public Holidays
      description: >-
        Returns Malaysia public holiday rows from `public-holiday.json`.
        Optional `year` scopes rows to a calendar year (defaults to
        `defaultYear` from the dataset, currently 2026 while that year is
        published). Optional `coverage` selects the full dataset for that year,
        nationwide-only rows, or (by default) you can filter with `state` for
        one of 16 states/territories. This endpoint focuses on holiday results
        and aggregates (including `meta.dateRange`); use
        `/api/v1/public-holiday/meta` for option lists only.
      parameters:
        - name: year
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Calendar year to return (must appear in `yearOptions` from
            `/api/v1/public-holiday/meta`). Omit to use `defaultYear` (the
            recommended active year for the product).
          example: '2026'
        - name: coverage
          in: query
          required: false
          schema:
            type: string
            enum:
              - all
              - nationwide
          description: >-
            Geographic coverage preset. `all` returns every row (ignores
            `state`). `nationwide` returns only rows where `states` lists all 16
            territories (nationwide holidays). Omit to use optional `state`
            filtering: with `state`, returns nationwide rows plus rows that
            include that territory.
          example: nationwide
        - name: state
          in: query
          required: false
          schema:
            type: string
            enum:
              - johor
              - kedah
              - kelantan
              - melaka
              - negeri-sembilan
              - pahang
              - perak
              - perlis
              - pulau-pinang
              - sabah
              - sarawak
              - selangor
              - terengganu
              - kuala-lumpur
              - labuan
              - putrajaya
          description: >-
            State/territory filter (slug format). Ignored when `coverage=all`.
            Accepted values: johor, kedah, kelantan, melaka, negeri-sembilan,
            pahang, perak, perlis, pulau-pinang, sabah, sarawak, selangor,
            terengganu, kuala-lumpur, labuan, putrajaya.
          example: selangor
      responses:
        '200':
          description: >-
            Malaysia public holiday list with optional year, coverage, and state
            filters. Nationwide rows list all 16 territory slugs. Use
            /api/v1/public-holiday/meta for filter options.
          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/PublicHolidaySuccessResponse'
        '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'
        '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:
    PublicHolidaySuccessResponse:
      type: object
      required:
        - apiVersion
        - baseUrl
        - defaultYear
        - yearOptions
        - query
        - total
        - meta
        - holidays
      properties:
        apiVersion:
          type: string
        baseUrl:
          type: string
        defaultYear:
          type: integer
        yearOptions:
          type: array
          items:
            $ref: '#/components/schemas/PublicHolidayYearOption'
        query:
          type: object
          required:
            - year
            - state
            - coverage
          properties:
            year:
              type: integer
              description: >-
                Resolved calendar year for the returned rows (matches `year`
                query or `defaultYear` when omitted).
            state:
              type: string
              nullable: true
            coverage:
              type: string
              nullable: true
              description: 'When set: "all" or "nationwide".'
        total:
          type: integer
        meta:
          type: object
          required:
            - nationwideTotal
            - dateRange
            - stateTotals
          properties:
            nationwideTotal:
              type: integer
            dateRange:
              type: object
              required:
                - startDate
                - endDate
              properties:
                startDate:
                  type: string
                  format: date
                  nullable: true
                endDate:
                  type: string
                  format: date
                  nullable: true
            stateTotals:
              type: array
              items:
                type: object
                required:
                  - state
                  - label
                  - total
                properties:
                  state:
                    type: string
                  label:
                    type: string
                  total:
                    type: integer
        holidays:
          type: array
          items:
            $ref: '#/components/schemas/PublicHolidayItem'
      example:
        apiVersion: '1'
        baseUrl: https://api.bilauitmcuti.com
        defaultYear: 2026
        yearOptions:
          - value: 2026
            label: '2026'
        query:
          year: 2026
          state: selangor
          coverage: null
        total: 1
        meta:
          nationwideTotal: 0
          dateRange:
            startDate: '2026-12-11'
            endDate: '2026-12-11'
          stateTotals:
            - state: selangor
              label: Selangor
              total: 1
        holidays:
          - id: selangor-ruler-birthday
            name: Birthday of Sultan of Selangor
            date: '2026-12-11'
            day: Friday
            states:
              - selangor
            isSubjectToChange: false
    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
    PublicHolidayItem:
      type: object
      required:
        - id
        - name
        - date
        - day
        - states
        - isSubjectToChange
      properties:
        id:
          type: string
        name:
          type: string
        date:
          type: string
          format: date
        day:
          type: string
        states:
          type: array
          items:
            type: string
          description: Territory slugs; nationwide holidays include all 16 slugs.
        isSubjectToChange:
          type: boolean
        notes:
          type: string

````

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