GET公开接口
获取公开版本列表
面向客户端查询某项目全部公开版本，按发布时间从新到旧排序。
URL
/api/v1/public/{projectKey}/versions鉴权方式
无需鉴权
请求参数
Path 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| projectKey | string | 是 | 项目主键 project_key（大小写不敏感） |
Query 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| platform | windows | linux | macos | ios | android | web | others | 否 | 按平台筛选列表内容（不是客户端平台声明，与请求统计无关）。 对版本与公告这类有发布范围的资源，未限定平台的记录对任何平台都可见。 |
| platform_version | string | 否 | 客户端系统版本明细（等价于 `x-verhub-platform-version` 请求头，优先级低于请求头）。 仅用于请求统计，不影响接口返回内容。 |
| limit | integer | 否 | 分页大小 |
| offset | integer | 否 | 分页偏移 |
| search | string | 否 | 关键字，不区分大小写地匹配 version、comparable_version、title 与 content。 |
| locale | string | 否 | 语言偏好。命中该项目注册过的语言（匹配大小写不敏感）且该版本存有对应译文时， `title` / `content` 返回译文，`locale` 字段标出实际语言； 以下三种情况一律返回版本的默认内容且 `locale` 为 `null`：不传本参数、 传了项目未注册的语言、该版本没有这个语言的译文。回落是逐字段的： 只译了标题的版本，更新说明仍返回默认内容。 |
Header 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| x-verhub-platform | windows | linux | macos | ios | android | web | others | 否 | 客户端平台声明，仅用于请求统计，不影响接口返回内容。 识别优先级：本请求头 > query 参数 `platform` > 请求体 `platform` 字段 > User-Agent 推断。 取值大小写不敏感，无法识别时统计为 OTHERS。 具体系统版本请用 `x-verhub-platform-version` 单独提交；若把版本混在本字段里 （如 `Windows 11`、`ubuntu 24.04`），服务端会拆开，平台与版本分别入库。 建议 SDK 显式声明本请求头：服务端调用的 User-Agent 往往不可靠。 |
| x-verhub-platform-version | string | 否 | 客户端系统版本明细，仅用于请求统计，不影响接口返回内容。 自由文本，如 `11`、`ubuntu 24.04`、`26`；超过 32 字符视为无效直接丢弃。 识别优先级：本请求头 > query 参数 `platform_version` > 请求体 `platform_version` 字段 > 从 `platform` 中拆出的版本 > User-Agent 推断。 |
该接口无需请求体。
响应示例
200 响应
{
"total": 1,
"data": [
{
"id": "ver-001",
"version": "1.0.0",
"comparable_version": "1.0.0",
"title": "首发版本",
"content": "首个正式版本，支持版本发布与公告推送。",
"download_url": "https://example.com/download/verhub-1.0.0.zip",
"download_links": [
{
"url": "https://example.com/download/verhub-1.0.0.zip",
"name": "Windows 包",
"platform": "windows"
}
],
"forced": false,
"is_latest": true,
"is_preview": false,
"is_milestone": true,
"is_deprecated": false,
"platform": "windows",
"platforms": [
"windows",
"mac"
],
"custom_data": {
"channel": "stable"
},
"created_at": 1760000000,
"published_at": 1760000000
}
]
}GET
