开发者

数据 API 文档

公开榜单接口免费开放、无需注册。订阅接口（历史数据 / 对比 / 导出）按配额计费。本 API 只读——排名不可购买，不存在任何写入接口。

版本 v2 · 最近更新：2026-09-21 · 基础地址 https://ai-bid.sbs

Developers

Data API documentation

The public leaderboard endpoint is free and open, no sign-up required. Subscription endpoints (history / comparison / export) are metered by quota. This API is read-only — rankings cannot be bought, and no write endpoint exists.

Version v2 · Updated 2026-09-21 · Base URL https://ai-bid.sbs

排名不可购买。本 API 只提供公开信号数据的读取；不存在「创建竞价」「占位」「修改名次」类接口——这不是未实现，而是产品设计上没有对应物。数据口径见公开方法论。

一、快速开始

所有请求使用 HTTPS，响应为 JSON，字符集 UTF-8。时间戳为 ISO 8601 字符串或 Unix 秒级整数。公开榜单接口不需要任何鉴权：

bash

curl https://ai-bid.sbs/api/ranking?limit=10

二、接口 · 榜单查询（已上线）

GET /api/ranking — 返回全部收录条目，按公开信号分降序排列（rank 字段已赋值）。响应缓存 60 秒（Cache-Control: public, max-age=60）。

参数	类型	必填	说明
`limit`	integer	否	客户端截断条数；接口本身返回全量，分页在客户端完成
`category`	string	否	分类 key；不过滤时返回全部分类（`categories` 字段含全表）

json

{
  "items": [
    {
      "id": "langchain",
      "name": "LangChain",
      "category": "agent-framework",
      "repo": "langchain-ai/langchain",
      "url": "https://github.com/langchain-ai/langchain",
      "homepage": "https://www.langchain.com",
      "stars": 98000,
      "forks": 15600,
      "score": 101900,
      "language": "Python",
      "pushedAt": "2026-09-20T10:00:00Z",
      "rank": 1
    }
  ],
  "categories": [ /* 6 个分类的 id/name/nameZh */ ],
  "signal": {
    "version": "1.0.0",
    "formula": "score = stars + 0.25 × forks",
    "forkWeight": 0.25
  },
  "updatedAt": "2026-09-21T02:00:00Z",
  "count": 36,
  "source": "snapshot+metrics",
  "attribution": "GitHub public API",
  "notice": null
}

signal 块随响应一起下发——公式版本与权重以它为准，客户端无需硬编码。source 为 snapshot（清单与指标都来自策展快照）或 snapshot+metrics（清单来自快照、指标来自每日自动刷新）。updatedAt 是当前数据实际对应的时点；notice 平时为 null，自动刷新异常时给出 { code, ageHours, at }，用于如实提示数据偏旧。

三、响应字段

字段	说明
`id` / `name` / `category`	策展注册表中的稳定标识、展示名与分类
`repo` / `url` / `homepage`	GitHub 仓库（owner/name）、仓库地址、官方站点（可能为 null）
`stars` / `forks`	采集时点的公开信号原始值
`score`	公开信号分 = stars + 0.25 × forks
`rank`	全量排序后的名次（1 起）；同分规则见方法论
`pushedAt` / `language`	仓库最近推送时间与主语言（可能为 null）
`updatedAt` / `source` / `notice`	数据时点、数据由哪一层构成、自动刷新异常提示（正常为 null）

四、订阅接口（待开通）

尚未开通。以下订阅接口（历史数据、批量对比、导出）在收单方完成开户后随订阅一起开放，届时本节将更新为正式规范并发布 API Key 管理入口。在此期间不存在任何需要付费才能调用的接口，也请勿向任何第三方购买"API Key"。

计划接口	用途	状态
`GET /api/history/{id}`	条目信号与名次的历史序列	待开通
`POST /api/compare`	批量条目横向对比	待开通
`GET /api/export`	榜单与历史数据导出	待开通

开通后：通过 Authorization: Bearer aib_live_… 头鉴权，按订阅档位计配额（见配额规则），超出配额返回 429。API Key 等同于账户凭据，仅存放于服务端，切勿写入前端代码或 Git 仓库。

五、错误码

HTTP	含义	处理建议
200	正常（包括空榜——`items` 为空数组是有效响应）	—
401	订阅 API Key 无效或已吊销（仅订阅接口）	重新签发 Key
403	访问了不存在或未开放的资源	核对本页文档
404	路径不存在	本 API 仅有本页列出的路径
429	触发限流 / 超出配额	按 `Retry-After` 退避
500	服务内部错误	提交工单

六、限流与配额

接口	配额	说明
`GET /api/ranking`	免费 · 缓存 60s	公开数据，建议客户端自行缓存，勿高频轮询
订阅接口（开通后）	按档位 · 次/月	档位配额加载中… / Loading plan quotas…

配额规则与档位对照见配额规则；响应头 X-RateLimit-Remaining / X-RateLimit-Reset 将在订阅接口开通后提供。

Rankings cannot be bought. This API only serves reads of public signal data. There is no "create bid", "claim a slot", or "change rank" endpoint — not because it is unimplemented, but because the product has no such concept. See the public methodology.

1. Quick start

All requests use HTTPS. Responses are JSON, charset UTF-8. Timestamps are ISO 8601 strings or Unix seconds. The public leaderboard endpoint requires no authentication:

bash

curl https://ai-bid.sbs/api/ranking?limit=10

2. Endpoint · Leaderboard (live)

GET /api/ranking — returns all curated entries sorted by the public signal score (the rank field is pre-assigned). Responses are cached for 60 seconds (Cache-Control: public, max-age=60).

Parameter	Type	Required	Notes
`limit`	integer	No	Client-side truncation hint; the endpoint returns the full set, paginate client-side
`category`	string	No	Category key; when absent, all entries are returned (see the `categories` field)

json

{
  "items": [
    {
      "id": "langchain",
      "name": "LangChain",
      "category": "agent-framework",
      "repo": "langchain-ai/langchain",
      "url": "https://github.com/langchain-ai/langchain",
      "homepage": "https://www.langchain.com",
      "stars": 98000,
      "forks": 15600,
      "score": 101900,
      "language": "Python",
      "pushedAt": "2026-09-20T10:00:00Z",
      "rank": 1
    }
  ],
  "categories": [ /* 6 categories: id/name/nameZh */ ],
  "signal": {
    "version": "1.0.0",
    "formula": "score = stars + 0.25 × forks",
    "forkWeight": 0.25
  },
  "updatedAt": "2026-09-21T02:00:00Z",
  "count": 36,
  "source": "snapshot+metrics",
  "attribution": "GitHub public API",
  "notice": null
}

The signal block ships with every response — treat it as the source of truth for formula version and weights; do not hardcode them client-side. source is snapshot (both the list and the metrics come from the curated snapshot) or snapshot+metrics (list from the snapshot, metrics from the daily automatic refresh). updatedAt is the timestamp the current data actually corresponds to; notice is normally null and becomes { code, ageHours, at } when the automatic refresh is failing, so clients can tell that the data is old.

3. Response fields

Field	Notes
`id` / `name` / `category`	Stable id, display name, and category from the curated registry
`repo` / `url` / `homepage`	GitHub repo (owner/name), repo URL, official site (may be null)
`stars` / `forks`	Raw public signal values at collection time
`score`	Public signal score = stars + 0.25 × forks
`rank`	Position after full sorting (1-based); tie-breaking in the methodology
`pushedAt` / `language`	Repo last-push timestamp and primary language (may be null)
`updatedAt` / `source` / `notice`	Data timestamp, which layer the data comes from, and a stale-refresh notice (normally null)

4. Subscription endpoints & API keys

Key delivery is live. After you subscribe and pay, your API key is auto-provisioned against your subscription email — retrieve it on the "My access" page (access.html). The history / bulk-comparison / export subscription endpoints will open in a later iteration; rankings cannot be bought, payment only unlocks data access.

Planned endpoint	Purpose	Status
`GET /api/history/{id}`	Historical signal and rank series for an entry	Not yet open
`POST /api/compare`	Bulk side-by-side comparison	Not yet open
`GET /api/export`	Board and history export	Not yet open

Once open: authenticate with Authorization: Bearer aib_live_…; quota follows your subscription tier (see the quota rules); over-quota requests return 429. An API key is account credential material — keep it server-side, never in front-end code or a Git repository.

5. Error codes

HTTP	Meaning	Suggested handling
200	OK (an empty board is valid — `items` may be `[]`)	—
401	Subscription API key invalid or revoked (subscription endpoints only)	Issue a new key
403	Requested resource does not exist or is not open	Check this document
404	Unknown path	This API only exposes the paths listed here
429	Rate limited / over quota	Back off per `Retry-After`
500	Internal server error	Open a ticket

6. Rate limits & quotas

Endpoint	Quota	Notes
`GET /api/ranking`	Free · 60s cache	Public data — cache it client-side and avoid high-frequency polling
Subscription endpoints (once open)	Per tier · calls/month	Loading plan quotas… / 档位配额加载中…

Tier details are in the quota rules; the X-RateLimit-Remaining / X-RateLimit-Reset headers will be provided once subscription endpoints open.