以稳定的 JSON 呈现证据。

请求与缓存

每个响应都是 application/json，并带有 Cache-Control: public, s-maxage=60, stale-while-revalidate=300。遵守该标头不会给你带来任何成本，还能让索引的提供更省资源，因此请从缓存读取，而不是轮询。只提供 GET 和 HEAD；任何其他方法都会返回 405，并带有 Allow 标头。

错误绝不会只返回一个状态。响应正文始终是一个对象，其中包含可安全用于分支判断的 code，以及为人类编写的 message：

{ "error": { "code": "invalid_limit", "message": "limit must be an integer from 1 to 100" } }

列出服务器

GET /api/v1/servers

q

针对标题、注册表名称和描述进行匹配的自由文本。

state

verified、stale、broken、auth_required 或 unverifiable 之一。

package

软件包注册表类型：npm、pypi 或 oci。

transport

Registry 记录声明的传输方式，例如 stdio。

client

客户端 slug，如 Clients 页面所列——例如 claude-code。 公共 API

limit

1 到 100 之间的整数。默认为 25。超出该范围的值会被拒绝，而不是被截断，因此客户端拿到的行数绝不会与它请求的不同却未被告知。

cursor

上一个响应中的 nextCursor。第一页请省略；最后一页为 null。

GET /api/v1/servers?state=verified&package=npm&limit=2

{
  "data": [
    {
      "id": "srv_01J…",
      "registryName": "example/one",
      "title": "Example Server",
      "description": "What the server says it does.",
      "state": "verified",
      "observedAt": "2026-09-15T00:00:00.000Z",
      "toolCount": 3,
      "url": "/servers/example/one"
    }
  ],
  "nextCursor": null
}

服务器详情

GET /api/v1/servers/:namespace/:name

在 data 下返回某个服务器的 Registry 元数据、可运行的软件包以及公开观测历史。该历史中的每次运行都会指明它所测试的确切软件包版本，而这通常不是今天发布的版本。未知的组合会返回 404，code 为 not_found。

验证运行

GET /api/v1/verification-runs/:id

按标识符返回一次观测。尚未通过确认规则的运行不会出现在这里，并返回 404，code 为 not_found——与从未存在过的运行给出相同答案，因为两者之间的任何差异都会泄露该规则旨在不予披露的失败。

数据集统计

GET /api/v1/stats

{ "data": { "indexedServers": 979, "verifiedServers": 0, "observedAt": null } }

错误码

invalid_limit

400 — limit 不是 1 到 100 之间的整数。

invalid_cursor

400 — cursor 格式错误，或是针对不同的排序顺序生成的。请从第一页重新开始。

not_found

404 — 没有这样的服务器，或没有使用该标识符的可发布运行。

method_not_allowed

405 — 该 API 是只读的。响应会列出所提供的方法。

不公开的内容

内部 stderr、工作进程租约和待确认详情永远不会发布，并且状态始终带有它所描述的那次观测的时间戳，而不是你请求它的时间。