开放 API 概览

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

Base path

https://your-site.example/api/v1

主要接口组位于：

/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	接口 schema、示例、认证方式，以及 `x-ai` 任务元数据
AI tool schema	function/tool 定义、风险等级和确认策略
AI 工具使用指南	调用选择、提示词和安全策略

默认套餐限额

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

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

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 参考为准。