> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub.jerrylu.app/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/analytics
/api/v1/audit
```

## 设计约定

* API 响应为 JSON。
* 请求和响应字段使用 camelCase。
* 数据库管理字段为只读。
* API Key 所属用户决定访问范围。
* 所有订阅查询都会按 API Key owner 过滤。
* `nextPaymentDate` 由服务端根据计费周期字段计算。
* `status` 支持软生命周期状态：`active`、`paused`、`cancelled`。
* 分析端点按币种分别报告金额，不跨币种换算。
* 审计端点暴露开放 API create、update 和 delete 的写操作历史。
* 当字段可修正时，写操作会返回适合 AI 读取的校验错误。

## 面向 AI 的交付物

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

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

## 默认套餐限额

| 套餐      | Active keys |           请求量 |
| ------- | ----------: | ------------: |
| Free    |           1 |   每用户每小时 60 次 |
| Premium |           5 | 每用户每小时 1000 次 |

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

```bash theme={null}
API_FREE_RATE_LIMIT_PER_HOUR=60
API_PREMIUM_RATE_LIMIT_PER_HOUR=1000
API_FREE_ACTIVE_KEYS=1
API_PREMIUM_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 参考](/api-reference)为准。