公开发布页

列表只展示已开启看板展示且未删除的发布页；按 publish_key 直接访问未删除的发布页不要求开启看板展示。关闭看板展示不会撤销公开链接。接口无需鉴权，因此只能返回发布者明确公开的数据。

获取公开发布页列表

端点：GET /api/v1/public/publishes

查询参数	类型	必填	说明
`account`	string	否	按所属用户账号精确筛选
`category`	string	否	按分类精确筛选
`name`	string	否	按发布页名称模糊搜索

curl 'https://<poco-host>/api/v1/public/publishes?account=zhangsan&category=炼铁&name=日报'

{
  "code": 0,
  "message": "OK",
  "data": [
    {
      "publish_key": "daily-report",
      "name": "日报发布",
      "description": "每日生产日报",
      "category": "炼铁",
      "latest_published_at": "2026-04-30 18:30:00",
      "version_count": 3,
      "created_at": "2026-04-28 09:00:00",
      "updated_at": "2026-04-30 18:30:00",
      "owner": {
        "account": "zhangsan",
        "name": "张三",
        "department": "生产部"
      }
    }
  ]
}

列表接口的时间字段使用北京时间，格式为 YYYY-MM-DD HH:mm:ss。

获取发布页详情

端点：GET /api/v1/public/publishes/{publish_key}

publish_key 也用于公开访问路径 /share/p/{publish_key}。响应 data 中常用字段：

字段	说明
`name`、`description`、`category`	发布页基础信息
`origin`	发布来源标识
`tags`	标签数组
`public_to_board_enabled`	是否公开到发布广场
`latest_share_code`	最新版本分享码
`latest_entry_path`	最新版本入口文件路径
`latest_published_at`	最新发布时间
`distraction_free_mode_enabled`	是否启用沉浸阅读模式
`share_type`	分享资源类型
`workspace_file`	最新有效版本的入口文件

workspace_file 包含 name、path、mimeType、url 和 downloadUrl。预览和下载地址可能具有有效期。

获取版本列表

端点：GET /api/v1/public/publishes/{publish_key}/versions

支持 limit、offset、version_no、date、date_from、date_to 和 tz 查询参数。limit 默认 50、最大 200，offset 非负，version_no 至少为 1。日期筛选的 tz 默认 UTC，与列表时间展示的北京时间不同；需要按北京时间筛选时显式传 Asia/Shanghai。date 不能与日期范围混用，date_to 包含当日，反向范围返回 400。每个版本包含：

字段	说明
`version_no`	版本号
`share_code`	当前版本分享码
`entry_path`	当前版本入口文件路径
`published_at`	发布时间，可能为 `null`
`is_latest`	是否为最新版本

获取指定版本文件

端点：GET /api/v1/public/publishes/{publish_key}/versions/{version_no}/files

返回 FileNode[]。文件夹节点通过 children 形成树形结构；文件节点可能包含 url、downloadUrl、mimeType、oss_status 和 oss_meta。

如果已知 share_code，也可调用：

GET /api/v1/public/shares/{share_code}

该接口可读取对应版本及其 workspace_file。

公开分享资源

公开分享码支持以下匿名接口，仍检查分享类型、有效期和资源可用性：

端点	用途
`GET /api/v1/public/shares/{share_code}`	解析分享及资源信息
`GET /api/v1/public/shares/{share_code}/metadata`	读取分享元数据
`GET/HEAD /api/v1/public/shares/{share_code}/content`	读取入口内容
`GET/HEAD /api/v1/public/shares/{share_code}/assets/{asset_path}`	读取附属资源
`GET/HEAD /api/v1/public/shares/{share_code}/media`	读取共享媒体

内容接口返回文件响应或 HTTP 307 重定向，不使用 JSON 业务封装；客户端应跟随 Location，curl 可使用 -L。分享失效后应重新获取有效资源；预签名 URL 也可能独立过期。

与 WebHook 配合

订阅 publish_page.published 后，可以从事件中获得 publish_key、version_no 和 share_code，再调用本页接口读取对应版本。不要只凭 session.completed 判断发布成功，因为会话完成与发布页生成是两个不同阶段。