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

# 开放 API 概览

> 使用 Developer API Key 通过 v1 开放 API 管理订阅生命周期、分析和审计。

# 开放 API 概览

v1 开放 API 通过 Developer API Key 提供订阅生命周期管理、分析和审计访问能力。它主要面向脚本、Agent、自动化工具和第三方集成。

## Base path

```text theme={null}
https://your-site.example/api/v1
```

主要接口组位于：

```text theme={null}
/api/v1/subscriptions
/api/v1/notification-settings
/api/v1/analytics
/api/v1/audit
```

## 设计约定

* API 响应为 JSON。
* 请求和响应字段使用 camelCase。
* 数据库管理字段为只读。
* API Key 所属用户决定访问范围。
* 所有订阅查询都会按 API Key owner 过滤。
* `nextPaymentDate` 是权威续费日期；月付计划会保留原始的每月固定日期。
* `status` 会在记录中返回，也可作为列表过滤参数，但不能通过公开 API 写入。
* 通知设置仅开放 `enabled` 与 `daysBefore` 的写入；Bark URL、test push、timeZone、locale 仍由网页管理。
* 分析端点按币种分别报告金额，不跨币种换算。
* 审计端点暴露开放 API create、update 和 delete 的写操作历史。
* 当字段可修正时，写操作会返回适合 AI 读取的校验错误。

## 面向 AI 的交付物

接入 AI 助手或 Agent 框架时，优先使用这些文件：

| 交付物 | 用途 |
| - | - |
| [OpenAPI schema](/docs/api/openapi.yaml) | 接口 schema、示例、认证方式，以及 `x-ai` 任务元数据 |
| [AI tool schema](/docs/api/ai-tools.json) | function/tool 定义、风险等级和确认策略 |
| [AI 工具使用指南](/docs/api/ai-tools) | 调用选择、提示词和安全策略 |

## 默认套餐限额

| 套餐 | Active keys | 请求量 |
| - | -: | -: |
| Free | 5 | 每账户每分钟 60 次 |
| Premium | 5 | 每账户每分钟 60 次 |

可以用服务端环境变量覆盖默认值：

```bash theme={null}
API_RATE_LIMIT_PER_MINUTE=60
API_MAX_ACTIVE_KEYS=5
API_FAILED_AUTH_RATE_LIMIT_PER_HOUR=300
API_RATE_LIMIT_RETENTION_HOURS=48
```

## Endpoints

| Method | Path | 说明 |
| - | - | - |
| `GET` | `/api/v1/subscriptions` | 获取订阅列表 |
| `GET` | `/api/v1/subscriptions/{id}` | 获取单个订阅 |
| `POST` | `/api/v1/subscriptions` | 创建订阅 |
| `PATCH` | `/api/v1/subscriptions/{id}` | 更新可写字段 |
| `DELETE` | `/api/v1/subscriptions/{id}` | 删除订阅 |
| `GET` | `/api/v1/analytics/summary` | 按币种/分类汇总支出并返回即将续费项 |
| `GET` | `/api/v1/analytics/duplicates` | 查找重复订阅候选 |
| `GET` | `/api/v1/analytics/optimizations` | 返回不虚构折扣的优化候选 |
| `GET` | `/api/v1/audit` | 开放 API 写操作审计日志 |

## API 参考

接口 schema、参数和响应示例以生成的 [API 参考](/docs/api-reference)为准。


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