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

# 通知设置

> 通过开放 API 读取和更新全局提醒设置，不暴露 Bark 密钥。

# 通知设置

全局提醒设置位于 `/api/v1/notification-settings`。

该端点刻意收窄：

| 字段                    | API                      |
| --------------------- | ------------------------ |
| `enabled`             | 可读可写                     |
| `daysBefore`          | 可读可写（`1`、`3`、`7` 或 `14`） |
| `timeZone`            | 只读                       |
| `locale`              | 只读                       |
| `barkConfigured`      | 只读布尔值                    |
| Bark URL / device key | 不开放                      |
| Test push             | 不开放                      |

请先在网页端 **设置 → 通知** 配置好 Bark。见[续费提醒指南](/zh-CN/user-guide/reminders)。之后 Agent 可以通过本接口开关全局提醒、修改提前天数。单个订阅的提醒开关仍使用订阅上的 `notificationEnabled`。

## 读取设置

`GET /api/v1/notification-settings`

```bash theme={null}
curl -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  https://your-site.example/api/v1/notification-settings
```

```json theme={null}
{
  "data": {
    "enabled": true,
    "daysBefore": 3,
    "timeZone": "Asia/Shanghai",
    "locale": "zh-CN",
    "barkConfigured": true,
    "updatedAt": "2026-06-16T00:00:00.000Z"
  },
  "requestId": "request-..."
}
```

如果账号从未在网页端保存过通知设置，API 会返回 `404 notification_settings_not_found`，并引导到网页提醒配置。

## 更新设置

`PATCH /api/v1/notification-settings` 需要 `write` scope。

```bash theme={null}
curl -X PATCH \
  -H "Authorization: Bearer $SUBSCRIPTION_MANAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"daysBefore":7}' \
  https://your-site.example/api/v1/notification-settings
```

请求里如果带上 `barkUrl`、`timeZone`、`locale` 等不可写字段，会返回 `400 invalid_notification_settings_field`，并附带 `writableFields: ["daysBefore","enabled"]`。

## Agent 行为

如果用户想粘贴 Bark URL 或发送测试推送，应拒绝，并引导到网页端与[续费提醒指南](/zh-CN/user-guide/reminders)。不要编造凭证。