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

# Getting Started

> Learn the base URL, rate limits, caching and error codes of the free Bila UiTM Cuti API, then make your first UiTM calendar request.

> [!WARNING]
>
> This is an unofficial API and is not affiliated with UiTM. Verify important dates before production use.

## At a Glance

* **Methods** — `GET` only
* **Auth** — No API key
* **Rate limits** — 500/min per endpoint path; +60/min heavy (`all=true`, `allSessions=true`); `/api/health` and `/mcp/health` excluded; `X-RateLimit-*` + `RateLimit` headers on responses
* **Caching** — ETag + Cache-Control; If-None-Match for 304

## Base URL

`https://api.bilauitmcuti.com`

## Authentication

No API key required. Send unauthenticated `GET` requests.

## Rate Limits

Production enforces per-IP limits via Cloudflare Workers Rate Limiting (per edge location):

* **500 requests / 60 seconds** per endpoint path (separate counters per path).
* **60 requests / 60 seconds** additional heavy bucket when `all=true` on calendar/meta, or `allSessions=true` on calendar.
* `GET /api/health` and `GET /mcp/health` are **not** rate limited.

Cacheable successes include `RateLimit-Policy` (per-client remaining is omitted so shared caches cannot replay another client's quota). `429` responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `RateLimit`, `RateLimit-Policy`, and window-aligned `Retry-After` / JSON `retryAfter`. Use `GET /api/v1/rate-limit` for a best-effort remaining peek.

## Rate-Limit Status

`GET` `/api/v1/rate-limit`

Returns published policies and a best-effort remaining quota for the caller. This call does **not** consume rate-limit budget. Optional `pathname` selects which route to inspect (defaults to this endpoint). Optional `heavy=true` includes the heavy bucket in the primary view.

#### Query Parameters

| Name | Type | Description | Example |
| - | - | - | - |
| `pathname` | string | API path to inspect. Must start with `/`. Defaults to `/api/v1/rate-limit`. | /api/v1/calendar |
| `heavy` | string | When true (or "1"/"yes"), response highlights the heavy bucket alongside endpoint policy. | true |

#### Response Fields

| Field | Type | Description | Example |
| - | - | - | - |
| `enforcement` | string | How limits are applied. Remaining is per edge isolate and approximate. | Cloudflare Workers Rate Limiting (per edge location). Remaining counts are approximate per worker isolate and do not consume quota on this endpoint. |
| `pathname` | string | Path being inspected. | /api/v1/calendar |
| `heavyMode` | boolean | Whether the heavy bucket is highlighted. | false |
| `policies` | object\[] | Published `endpoint` (500 / 60s) and `heavy` (60 / 60s) policies. | `[{ "name": "endpoint", "limit": 500, "period": 60 }]` |
| `endpoint` | object | Snapshot: `limit`, `remaining`, `reset`, `retryAfter`. | `{ "name": "endpoint", "limit": 500, "remaining": 499 }` |
| `heavy` | object | Same shape for the heavy bucket. | `{ "name": "heavy", "limit": 60, "remaining": 60 }` |

## How to Start

1. Call [Sessions & Programs (Meta)](https://docs.bilauitmcuti.com/academic-calendar.md) for session options; [Public Holiday Options (Meta)](https://docs.bilauitmcuti.com/public-holidays.md) for holiday filters.
2. Request [Calendar Activities](https://docs.bilauitmcuti.com/academic-calendar.md), [Lecture Weeks (1-14)](https://docs.bilauitmcuti.com/academic-calendar.md), or [Malaysia Public Holidays](https://docs.bilauitmcuti.com/public-holidays.md) data.
3. Use [Playground](https://docs.bilauitmcuti.com/playground.md) to test live.

**Errors:** validation 400; rate limits 429; missing session 404 on calendar and lecture-weeks.

## Agent Skills

The **bilauitmcuti-api** agent skill teaches coding assistants how to call this API — endpoints, query parameters, ETags, and rate limits — in one short reference.

**Why use it:** agents guess less. They pick the right paths, send required `session` / `group` params, and respect caching and rate-limit headers instead of inventing URLs from partial context.

**How to use:** see the [Skill](https://docs.bilauitmcuti.com/skill.md) page for install steps, or install directly from [bilauitmcuti/skills](https://github.com/bilauitmcuti/skills) in Cursor or another agent that supports skills. Also listed on [skills.sh](https://skills.sh/bilauitmcuti/skills).

## Model Context Protocol (MCP)

Claude, Grok, Grok Bot, or Cursor can use read-only MCP at `https://mcp.bilauitmcuti.com/mcp` (hosted Streamable HTTP). Same calendar and holiday data as the REST API; nothing gets written. [MCP Server](https://docs.bilauitmcuti.com/mcp-server.md).

## Contact and Feedback

Questions about the API, product feedback, or reports of wrong or mismatched calendar data — email [hello@bilauitmcuti.com](mailto:hello@bilauitmcuti.com) or send a message on Threads [threads.com/@bilauitmcuti](https://www.threads.com/@bilauitmcuti).


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