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

# 节假日日历

> 列出、新建、修改和删除每周时段按它算的节假日日历，读 ICS 文件，查看哪些地方在用一份日历。

```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
```

读取需要 `alerts.calendars.read`；新建、修改、删除和读文件需要 `alerts.calendars.manage`。每周时段怎么按日历算，见[节假日日历](https://docs.molesignal.com/zh-Hans/alerting/on-call.md#节假日日历)。

## 新建或修改日历

`POST` 新建一份日历，`PUT` 整份替换。响应是这份日历，带 `id`、`org_id`、`created_by`、`created_at` 和 `updated_at`。

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `name` | string | 是 | 最多 80 个字符，组织内不能重名。 |
| `description` | string | 否 | 最多 500 个字符。 |
| `days` | array | 否 | 最多 2000 天，每天写成 `{"date": "2026-10-01", "kind": "holiday", "name": "国庆节"}`。`kind` 为 `holiday`（放假）或 `workday`（补班，按周一的时段算）；`name` 最多 80 个字符。同一个日期只能出现一次。 |

```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": "中国 2026", "days": [{"date": "2026-10-01", "kind": "holiday", "name": "国庆节"}, {"date": "2026-10-10", "kind": "workday", "name": "补班"}]}'
```

在每周时段的 `calendar` 里写日历的 id 就能用它：`{"calendar_id": "<id>", "holidays": "exclude"}` 把放假的日子去掉，`"holidays": "only"` 只在放假的日子生效。[升级策略](https://docs.molesignal.com/zh-Hans/api/alerting/create-escalation.md)的支持时段、[路由规则](https://docs.molesignal.com/zh-Hans/api/alerting/create-routing-rule.md)和通知策略的时间条件、值班排班的轮值、告警流水线以及每周重复的静默窗口都能带它。保存时日历不在本组织里会返回 `400`。

## 读 ICS 文件

`POST /parse` 接受 `{"content": "<.ics 的内容>"}`，最大 2 MiB，返回 `{"days": [...]}`，什么都不保存：每个全天事件算一天，跨几天的事件每天各算一天，名称含「补班」「上班」或以「班」结尾的算 `workday`。

## 查看哪些地方在用

`GET /{id}/references` 列出按这份日历算的地方，每项是 `{"kind", "id", "name"}`；`kind` 为 `routing_rule`、`escalation_policy`、`schedule`、`mute_rule`、`notify_policy` 或 `alert_pipeline`。列表不为空时 `DELETE` 返回 `409`。

**错误**

| 状态码 | 原因 |
| - | - |
| `400` | 字段超出限制、同一个日期写了两次，或文件读不出来。 |
| `403` | Token 缺少相应权限。 |
| `404` | 本组织里没有这份日历。 |
| `409` | 已有同名日历，或日历还在用。 |


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