AFR.IM · API v1
API 文档
AFR.IM 的所有读取端点均公开：无需 API key、无需认证，并发送 Access-Control-Allow-Origin: *，任何来源的浏览器都可调用。响应是 JSON 快照，与本站渲染的数据同源；评级来自公开、可复现的证据——参见 AFR 标准。
Base URL
https://afr.im端点
GET
/api/v1/sites 分页目录列表。自然结果不包含 Pending（不可评）站点。
category · grade · q · sort (score | rank | new) · page
{
"items": [ { "domain": "github.com", "grade": "A", "score_total": 91,
"strategy_tag": "AI-Open", "verified": true, "scanned_at": "2026-11-10T11:40:00.000Z" } ],
"page": 1, "per_page": 24, "total": 8, "sort": "score"
} GET
/api/v1/sites/:domain 单个站点：最新一次扫描及其完整证据链。
{
"site": { "domain": "github.com", "grade": "A", "score_total": 91 },
"scan": { "engine_version": "afr-1.1.0", "score_l1": 33, "score_l2": 38, "score_l3": 20 },
"evidence": [ { "check_id": "l1.robots.ai-policy", "status": "pass",
"points": 25, "max_points": 25, "evidence_ref": "GET /robots.txt" } ]
} GET
/api/v1/sites/:domain/history 某域名的全部扫描记录，最新在前——驱动分数历史图。
GET
/api/v1/stats 总数、已验证数、Pending 数、平均分与等级分布。
{
"total": 8,
"verified": 4,
"pending": 0,
"avg_score": 58,
"grades": { "A": 1, "B": 2, "C": 2, "D": 2, "F": 1 }
} GET
/api/v1/categories 带各分类评级站点数量的分类树。
GET
/api/v1/leaderboard 按纯 AFR 分数降序的头部站点。绝不混入付费展示。
category · limit (≤ 50)
{
"category": null,
"items": [
{ "rank": 1, "domain": "github.com", "title": "GitHub · Where software is built",
"grade": "A", "score": 91, "category": "dev-tools", "strategy_tag": "AI-Open" }
]
} GET
/api/v1/method 机读 AFR 标准：三层结构、每个子项分值与等级阈值。
GET
/badge/:domain.svg 域名的评级徽章图片（SVG）——色环、等级字母与分数。缓存 1 小时；未知域名显示中性灰徽章。
POST
/api/v1/submissions 申请扫描一个站点。请求体：{ "domain": "example.com", "note": "可选" }。每 IP 每天 5 次。
// POST {"domain": "example.com", "note": "optional"}
{ "ok": true, "id": 1, "domain": "example.com", "status": "queued" }错误
错误为带错误码的 JSON 对象：参数无效返回 400，域名不存在返回 404，提交超限返回 429。断网时 Service Worker 会对 /api/* 返回 503 { "error": "offline" } 及友好提示。
{ "error": "not_found", "domain": "unknown.example" }速率限制
GET 端点无需密钥，除常规礼貌性要求外无限制——标明身份、约每秒一次、缓存响应（见 /agents.md）。POST /api/v1/submissions 为每 IP 每天 5 次。徽章图片上游缓存 1 小时。
机读格式
- OpenAPI 3.1 规范 — /openapi.json —— 供代码生成器与工具使用的 API 描述。
- OpenAPI 镜像 — /.well-known/openapi.yaml —— 同一份规范的 well-known 位置。
- AFR 标准 JSON — /api/v1/method —— 三层结构、每个子项分值与等级阈值。
- llms.txt / llms-full.txt — 面向语言模型读者的目录地图。