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

# Holiday calendars

> List, create, change, and delete the holiday calendars that weekly hours count by, read an ICS file, and see what uses a calendar.

```http theme={null}
GET    /api/v1/alerts/holiday-calendars
POST   /api/v1/alerts/holiday-calendars
GET    /api/v1/alerts/holiday-calendars/{id}
PUT    /api/v1/alerts/holiday-calendars/{id}
DELETE /api/v1/alerts/holiday-calendars/{id}
GET    /api/v1/alerts/holiday-calendars/{id}/references
POST   /api/v1/alerts/holiday-calendars/parse
```

Reading requires `alerts.calendars.read`; creating, changing, deleting, and reading a file require `alerts.calendars.manage`.
See [Holiday calendars](https://docs.molesignal.com/en-US/alerting/on-call.md#holiday-calendars) for how weekly hours count by them.

## Create or change a calendar

`POST` creates a calendar and `PUT` replaces one. The response is the calendar, with its `id`,
`org_id`, `created_by`, `created_at`, and `updated_at`.

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Up to 80 characters, unique in the organization. |
| `description` | string | No | Up to 500 characters. |
| `days` | array | No | Up to 2,000 days, each `{"date": "2026-10-01", "kind": "holiday", "name": "National Day"}`. `kind` is `holiday` (a day off) or `workday` (a make-up workday, counted as a Monday); `name` is up to 80 characters. A date may appear once. |

```bash cURL theme={null}
curl -X POST http://localhost:5080/api/v1/alerts/holiday-calendars \
  -H "authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name": "China 2026", "days": [{"date": "2026-10-01", "kind": "holiday", "name": "National Day"}, {"date": "2026-10-10", "kind": "workday", "name": "Make-up workday"}]}'
```

A calendar is used by putting its id in the `calendar` of weekly hours:
`{"calendar_id": "<id>", "holidays": "exclude"}` leaves the days off out, and `"holidays": "only"`
applies the hours on days off only. Weekly hours take it in the support hours of
[escalation policies](https://docs.molesignal.com/en-US/api/alerting/create-escalation.md), the time conditions of
[routing rules](https://docs.molesignal.com/en-US/api/alerting/create-routing-rule.md) and notify policies, rotations of on-call
schedules, alert pipelines, and weekly silence windows. Saving any of them with a calendar that is not in
the organization fails with `400`.

## Read an ICS file

`POST /parse` takes `{"content": "<the .ics text>"}`, up to 2 MiB, and returns `{"days": [...]}` without
saving anything: every all-day event becomes a day, an event of several days becomes each of its days,
and a name that contains 补班 or 上班, or ends with 班, becomes a `workday`.

## See what uses a calendar

`GET /{id}/references` lists what counts by the calendar, as `{"kind", "id", "name"}`; `kind` is
`routing_rule`, `escalation_policy`, `schedule`, `mute_rule`, `notify_policy`, or `alert_pipeline`.
`DELETE` fails with `409` while the list is not empty.

**Errors**

| Status | Reason |
| - | - |
| `400` | A field is out of its limits, a date is given twice, or the file cannot be read. |
| `403` | The token lacks the permission. |
| `404` | No such calendar in the organization. |
| `409` | Another calendar has the name, or the calendar is in use. |


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