REST API

通过 HTTPS 搜索目录、读取免费方案、规划组合和检查项目。无需密钥。

基础地址：https://api.clearvia.app/api/zero。响应为 JSON，无需 API 密钥。交互式 OpenAPI 文档见 api.clearvia.app/docs。

接口

方法与路径	用途
`GET /categories`	各分类的方案数与目录数据
`GET /offers`	搜索与筛选免费方案
`GET /offers/{slug}`	单个免费方案，含证据、替代方案和近期变更
`GET /providers/{slug}`	服务商及其免费方案
`GET /compare`	并排对比两到四个免费方案
`GET /changes`	变更记录，按时间倒序（用 `before` 翻页）
`GET /stats`	目录数据
`GET /catalog`	全部服务商与方案（含证据），用于离线使用
`POST /plan`	规划零成本组合
`POST /check`	检查项目的依赖清单

加上 locale=zh-CN 即可读取简体中文的名称、简介、理由和风险。名称和简介始终包含两种语言；说明以 note（英文）和 noteZh（简体中文）两个字段提供。

如果每日核验已找不到某条记录的引用，该记录会带有 review: { since, fields }，直到有人修正；其他情况下 review 为 null。

变更记录中的每一条都有 kind：服务商修改了方案时为 change，Clearvia 更正自己的记录时为 correction。给 GET /changes 加上 kind=change 或 kind=correction 即可只看其中一类；目录的“30 天内变更”只统计服务商的变更，不含更正和新收录的方案。

搜索免费方案

curl 'https://api.clearvia.app/api/zero/offers?role=postgres&commercialOnly=true&noIdlePause=true&locale=zh-CN'

筛选参数：q、category、role、provider、freeType、commercialOnly、noCard、noIdlePause、chinaOk、limit（最多 500）和 offset。

q 的每个词都要命中名称、简介、方案、服务商、分类或角色（中英文均可）。常用说法也会对应到目录术语：登录 能找到认证服务，大模型 能找到模型 API。

对比免费方案

curl 'https://api.clearvia.app/api/zero/compare?offers=neon-free,supabase-free&locale=zh-CN'

offers 列出两到四个方案，返回顺序与传入顺序一致。limits 把衡量同一事物、周期相同且适用角色有重叠的额度对齐，每个方案一项（方案未说明时为 null），额度不同时 differs 为 true。differences 列出其他存在差异的事实，例如 overage 或 flags.idlePauseDays。

规划组合

curl -X POST https://api.clearvia.app/api/zero/plan \
  -H 'content-type: application/json' \
  -d '{
    "needs": ["web-app", "postgres", "auth", "transactional-email"],
    "constraints": { "commercial": true, "audience": "cn", "noCard": true },
    "scale": { "monthlyActiveUsers": 2000, "databaseGb": 0.3, "emailsPerMonth": 1500 },
    "locale": "zh-CN"
  }'

needs 接受的用途包括 static-site、web-app、serverless-functions、postgres、sqlite、redis、queue、object-storage、auth、transactional-email、llm、embeddings、vector-db、search、error-tracking 和 analytics。约束：commercial、audience（global、cn、eea）、noCard、noPhone、noIdlePause、noDataTraining。用量：monthlyActiveUsers、requestsPerMonth、databaseGb、fileStorageGb、bandwidthGbPerMonth、emailsPerMonth、tokensPerMonth。用 prefer 和 exclude 指定方案或服务商的 slug。

响应包含 zeroCost、每项需求对应的 picks（选择、替代方案、已排除）、warnings、官方开通命令 commands、dataAsOf 以及 disclosure。

检查项目

curl -X POST https://api.clearvia.app/api/zero/check \
  -H 'content-type: application/json' \
  -d '{"files":[{"path":"package.json","content":"{\"dependencies\":{\"@supabase/supabase-js\":\"^2\"}}"}],"commercial":true,"locale":"zh-CN"}'

请发送 .env.example，而不是真实的 .env。环境变量的值只用于识别主机名，不会被返回。

已保存的组合

组织的已保存组合位于 https://api.clearvia.app/api/stacks，需要用 API 密钥以 Bearer 令牌访问。密钥只在所属组织内生效；请传入该组织的 ID（新建密钥时会显示）。

curl 'https://api.clearvia.app/api/stacks?organizationId=ORG_ID' \
  -H "Authorization: Bearer $CLEARVIA_API_KEY"

方法与路径	用途	密钥权限
`GET /api/stacks`	组织的组合，以及各自的状态和未读变化	读取
`GET /api/stacks/{stackId}`	单个组合：规划条件、当前方案和尚未查看的变化	读取
`POST /api/stacks`	保存组合：`organizationId`、`name` 和规划器的 `request`	读取并保存

保存时会像控制台一样用规划器重新规划，方案始终来自规划器。密钥过期、被撤销或其所有者已离开组织时返回 401，并说明原因；访问其他组织的组合返回 403。

缓存与限额

读取接口返回 ETag 和 Cache-Control: public, max-age=60, stale-while-revalidate=86400。发送 If-None-Match，在数据未变时会得到 304 Not Modified。要同步全部数据，GET /catalog 最高效。
每个 IP 每分钟最多 600 次读取、60 次规划或检查调用，超出时返回 429 和 Retry-After。
错误以 JSON 返回 message；不存在的方案和服务商返回 404。

披露

展示带有 commercial.referral: true 的结果时，请在链接旁展示其 commercial.disclosure。规划与检查的响应带有 disclosure，请与结果一起展示。

使用数据

你可以在自己的项目和产品（包括商业产品）中免费使用 API。向他人展示事实时，请保留每条事实的来源链接和新鲜度，注明数据来自 Clearvia 并链接到 clearvia.app，且不要表述为你自己的核验结果。将目录作为数据集转售，或用它构建与之竞争的目录，需要我们的书面同意。详见服务条款。

本页目录