跳转到主要内容

​
开放 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 schemafunction/tool 定义、风险等级和确认策略
AI 工具使用指南调用选择、提示词和安全策略

​
默认套餐限额

套餐Active keys请求量
Free1每用户每小时 60 次
Premium5每用户每小时 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

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