五分钟跑通第一个请求
Base URL：https://api.databridge.world/v1。 这页是公开的摘要。完整文档和你的真实 token 在控制台里。
快速开始
-
拿到 token
注册后在控制台「API」页生成。前缀 dbw_live_ 是正式额度，dbw_test_ 只能访问样例数据，不消耗配额。
-
挑一个源
在 数据源目录 里选，或直接调 GET /v1/sources 看全量列表与当前状态。
-
发第一个请求
下面三种写法等价，复制就能跑。
curl -s "https://api.databridge.world/v1/feeds/tech-github-releases/items?limit=20" \
-H "Authorization: Bearer $DBW_TOKEN"import os, requests
r = requests.get(
"https://api.databridge.world/v1/feeds/tech-github-releases/items",
params={"limit": 20},
headers={"Authorization": f"Bearer {os.environ['DBW_TOKEN']}"},
timeout=15,
)
r.raise_for_status()
for item in r.json()["items"]:
print(item["published_at"], item["title"])const res = await fetch(
"https://api.databridge.world/v1/feeds/tech-github-releases/items?limit=20",
{ headers: { Authorization: `Bearer ${process.env.DBW_TOKEN}` } }
);
const { items } = await res.json();
console.log(items.map((i) => i.title));鉴权
所有请求走 Bearer token，放在 Authorization 头里。token 与控制台账号绑定，删除即失效。
Authorization: Bearer dbw_live_9f21c8d4e7a04b31浏览器里直接调用会暴露 token。需要前端取数时，用你自己的服务端中转。 给第三方的 token 限到单个源，泄露了也只影响那一个。
端点
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /sources | 全部源、所属分类、最近抓取时间、健康状态 |
| GET | /feeds | 当前账号可访问的 feed 列表 |
| GET | /feeds/{feed_id} | 单源元信息：描述、频率、字段映射 |
| GET | /feeds/{feed_id}/items | 条目列表，支持 since / until / q / cursor / limit |
| GET | /feeds/{feed_id}/items/{item_id} | 单条详情，含 revision 历史 |
| POST | /webhooks | 配置推送地址（Premium） |
响应格式
所有条目同构，跨源字段名一致。下面是完整的单条结构。
{
"feed": {
"id": "tech-github-releases",
"name": "GitHub · 仓库 Release",
"category": "tech",
"updated_at": "2026-11-04T09:12:40Z"
},
"items": [
{
"id": "tech-github-releases:9f21c8d4",
"title": "v2.4.0 — streaming parser rewrite",
"url": "https://example.com/releases/v2.4.0",
"summary": "Replaces the buffered reader with an incremental...",
"content": null,
"author": "example",
"published_at": "2026-11-04T08:41:00Z",
"updated_at": null,
"lang": "en",
"tags": ["release"],
"hash": "9f21c8d4",
"revision": 0,
"deleted": false
}
],
"next_cursor": "eyJvIjoyMH0"
}分页与增量
第一次拉全量，之后只取增量。cursor 基于条目位置而非偏移量，翻到第 200 页和第一页一样快。
# 增量：只要 11 月 1 日之后的
GET /v1/feeds/fin-cn-macro/items?since=2026-11-01T00:00:00Z
# 续页：把上次响应里的 next_cursor 原样带回
GET /v1/feeds/fin-cn-macro/items?cursor=eyJvIjoyMH0
# next_cursor 为 null 表示已经到底去重建议：用 id 做唯一键 upsert。 同一源内 id 永不变；跨源重复的内容不会自动合并，用 hash 自行判断。
配额与限流
配额按自然日（UTC+8）重置。响应头里带实时读数，可以编程判断，不用靠猜。
X-Quota-Limit: 20000
X-Quota-Used: 3412
X-Quota-Reset: 2026-11-05T00:00:00+08:00
X-Rate-Limit: 20 # 每秒请求数上限
X-Rate-Remaining: 17超配额返回 402，超速率返回 429 并带 Retry-After。 两种都不扣费、不封号，退避重试即可。
错误码
| 状态码 | code | 含义与处理 |
|---|---|---|
| 401 | invalid_token | token 缺失或已删除。去控制台重新生成。 |
| 403 | source_not_in_plan | 该源不在当前套餐内。升级或换源。 |
| 404 | feed_not_found | feed_id 拼错，或该源已下线。 |
| 402 | quota_exceeded | 当日配额用完。次日 0 点重置。 |
| 429 | rate_limited | 超过每秒上限。按 Retry-After 退避。 |
| 410 | feed_disabled | 源站改版导致连续失败，已暂停抓取。 |
| 503 | upstream_unavailable | 源站暂时不可达。指数退避重试。 |
Webhook（Premium）
不想轮询就配推送。新条目入库后立刻 POST 到你给的地址，带签名头，验签后再处理。
POST https://your-app.example.com/hooks/dbw
X-DBW-Signature: sha256=6b1f...e0
X-DBW-Feed: tech-github-releases
X-DBW-Delivery: 01JC2F8Q
{ "feed_id": "tech-github-releases", "items": [ { "id": "...", "title": "..." } ] }签名 = HMAC-SHA256(原始请求体, webhook_secret)。失败重试 5 次，间隔指数增长（10s → 160s）， 仍失败则记入控制台的投递日志，可手动重放。
这里只是市场站的摘要。字段名、端点、配额以控制台文档为准。两边对不上时听控制台的，顺便告诉我们一声。