API Reference

Open API 文档

通过 RESTful API 以编程方式管理你的 LitePage 内容，适用于 CI/CD、脚本自动化和第三方集成。

仅专业版会员可用 RESTful · JSON · Bearer Token

认证方式

所有 API 请求必须通过 Authorization 请求头传递 API 密钥：

Authorization: Bearer pg_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

密钥可在控制台 → API 密钥页面创建。密钥创建后仅展示一次，请立即保存。

权限级别

权限 说明 可用操作
read 只读 GET 请求
write 读写 GET / POST / PUT 请求
full 完全控制 所有请求（含 DELETE）

限流策略

每个用户限制 60 次请求/分钟（滑动窗口）。超限返回 429 状态码：

{ "code": 429, "message": "请求频率超限，请稍后重试", "data": null }

响应格式

所有 API 返回统一 JSON 格式：

{
  "code": 200,
  "message": "ok",
  "data": { ... }
}
字段 类型 说明
code Int 状态码（200=成功，4xx/5xx=错误）
message String 消息描述
data Any? 响应数据，错误时为 null

页面管理

基础路径：/open/v1/pages

GET /open/v1/pages?projectId={id} 获取页面列表

权限： read

查询参数

参数 必填 说明
projectId 是 工作区 ID
page 否 页码（默认 1）
size 否 每页数量（默认 20）
响应示例 
{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "隐私政策",
        "slug": "privacy",
        "contentType": "markdown",
        "isPublished": true,
        "createdAt": 1709438400
      }
    ],
    "total": 5,
    "page": 1,
    "size": 20
  }
}
GET /open/v1/pages/{id} 获取页面详情

权限： read

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": {
    "id": 1,
    "title": "隐私政策",
    "slug": "privacy",
    "contentType": "markdown",
    "content": "# 隐私政策\n\n...",
    "templateStyle": "minimal",
    "appName": "",
    "projectId": 1,
    "isPublished": true,
    "showTitle": true,
    "showHeader": false,
    "showFooter": false,
    "hasPassword": false,
    "hiddenFromBlog": false,
    "tags": "",
    "metaDescription": "",
    "ogImage": "",
    "scheduledAt": 0,
    "subscriptionEnabled": false,
    "feedbackEnabled": false,
    "expireAt": 0,
    "viewCount": 42,
    "createdAt": 1709438400,
    "updatedAt": 1709438400
  }
}
POST /open/v1/pages?projectId={id} 创建页面

权限： write

请求体

{
  "title": "使用条款",
  "slug": "terms",
  "content": "# 使用条款\n\n...",
  "contentType": "markdown",
  "templateStyle": "minimal",
  "appName": "",
  "showTitle": true,
  "showHeader": true,
  "showFooter": true,
  "tags": "legal,policy",
  "metaDescription": "使用须知",
  "scheduledAt": 0,
  "subscriptionEnabled": false,
  "feedbackEnabled": false,
  "expireAt": 0
}
字段 必填 说明
title 是 页面标题
slug 是 URL 路径标识（同一项目内唯一）
content 是 页面内容
contentType 否 内容类型：markdown / html / json（默认 markdown）
templateStyle 否 模板风格（默认 minimal，可通过模板接口查询可用值）
appName 否 应用名称（显示在页头）
showTitle 否 是否显示标题（默认 true）
showHeader 否 是否显示页头（默认 true）
showFooter 否 是否显示页脚（默认 true）
password 否 页面访问密码，为空则不设置
tags 否 标签，逗号分隔
metaDescription 否 SEO 描述
ogImage 否 社交分享图片 URL
scheduledAt 否 定时发布时间（Unix 时间戳，0 = 不定时）
subscriptionEnabled 否 是否开启订阅通知（默认 false，开启后页面更新时自动邮件通知订阅者）
feedbackEnabled 否 是否开启页面反馈（默认 false，开启后页面右下角显示反馈按钮，读者可评分和留言）
expireAt 否 页面到期时间（Unix 时间戳，0 = 不到期，到期后自动取消发布）
PUT /open/v1/pages/{id} 更新页面

权限： write

请求体字段与创建接口相同，所有字段可选（仅传需要更新的字段）。更新前会自动保存版本快照。

POST /open/v1/pages/{id}/publish 发布页面

权限： write

将页面状态设为已发布，无需请求体。

POST /open/v1/pages/{id}/unpublish 取消发布

权限： write

将页面状态设为未发布，无需请求体。

DELETE /open/v1/pages/{id} 删除页面

权限： full

注意：删除操作不可恢复。仅 full 权限密钥可执行此操作。

在指定工作区内按标题关键字或标签搜索页面。

GET /open/v1/pages/search?projectId={id} 搜索页面

权限： read

查询参数

参数 必填 说明
projectId 是 工作区 ID
q 否* 标题关键字（与 tag 二选一）
tag 否* 标签名称（优先级高于 q）

* q 和 tag 至少传一个；若都为空则返回全部页面。tag 优先级高于 q。

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "title": "隐私政策",
      "slug": "privacy",
      "tags": "legal,policy",
      "isPublished": true,
      ...
    }
  ]
}

页面统计

获取页面的访问量统计数据。

GET /open/v1/pages/{id}/stats 获取页面访问统计

权限： read

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": {
    "totalViews": 1234,
    "todayViews": 56,
    "last7DaysViews": 320,
    "topReferers": [
      { "referer": "https://google.com", "count": 89 },
      { "referer": "https://twitter.com", "count": 45 }
    ]
  }
}

响应字段

字段 类型 说明
totalViews Long 总访问量
todayViews Long 今日访问量
last7DaysViews Long 近 7 天访问量
topReferers Array Top 5 来源站点

版本历史

查看页面的修改历史版本。每次通过 API 更新页面时，会自动保存一个版本快照。

GET /open/v1/pages/{id}/versions 获取版本列表

权限： read

返回最多 50 条版本记录，按版本号倒序排列。

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 10,
      "pageId": 1,
      "title": "隐私政策 v2",
      "content": "# 隐私政策\n\n更新内容...",
      "contentType": "markdown",
      "templateStyle": "minimal",
      "version": 3,
      "createdAt": 1709524800
    }
  ]
}
GET /open/v1/versions/{versionId} 获取版本详情

权限： read

获取指定版本的完整内容，包含标题、正文、模板等信息。

响应字段

字段 类型 说明
id Long 版本 ID
pageId Long 所属页面 ID
title String 版本标题
content String 版本内容
contentType String 内容类型
templateStyle String 模板风格
version Int 版本号
createdAt Long 快照创建时间

工作区管理

基础路径：/open/v1/workspaces

GET /open/v1/workspaces 获取工作区列表

权限： read

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "name": "我的工作区",
      "spaceName": "myspace",
      "companyName": "某某公司",
      "type": "app",
      "customDomain": "",
      "forceHttps": false,
      "sslEnabled": false,
      "homepageId": 0,
      "createdAt": 1709352000,
      "updatedAt": 1709438400
    }
  ]
}
GET /open/v1/workspaces/{id} 获取工作区详情

权限： read

Webhook 管理

通过 Webhook 接收页面发布、更新等事件推送。基础路径：/open/v1/webhooks

GET /open/v1/webhooks?projectId={id} 获取 Webhook 列表

权限： read

查询参数

参数 必填 说明
projectId 是 工作区 ID
响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "url": "https://example.com/webhook",
      "events": "publish,update",
      "isActive": true,
      "createdAt": 1709438400
    }
  ]
}
POST /open/v1/webhooks?projectId={id} 创建 Webhook

权限： write

请求体

{
  "url": "https://example.com/webhook",
  "secret": "your-webhook-secret",
  "events": "publish,update"
}
字段 必填 说明
url 是 Webhook 回调 URL
secret 否 签名密钥（用于验证推送来源，通过 X-Pages-Signature 头传递 HMAC-SHA256 签名）
events 否 订阅事件，逗号分隔（默认 publish,update）

推送格式

POST https://your-url.com/webhook
Content-Type: application/json
X-Pages-Event: publish
X-Pages-Signature: hmac-sha256-hex-string

{
  "event": "publish",
  "projectId": 1,
  "pageId": 5,
  "pageSlug": "privacy",
  "pageTitle": "隐私政策",
  "timestamp": 1709438400
}
DELETE /open/v1/webhooks/{id} 删除 Webhook

权限： full

数据看板

获取项目级全站访问统计数据。基础路径：/open/v1/analytics

GET /open/v1/analytics/{projectId} 获取项目统计

权限： read

响应字段

字段 类型 说明
totalViews Long 总 PV
todayViews Long 今日 PV
last7DaysViews Long 近 7 天 PV
last30DaysViews Long 近 30 天 PV
totalUV Long 总独立访客
todayUV Long 今日独立访客
last7DaysUV Long 近 7 天独立访客
last30DaysUV Long 近 30 天独立访客
weekGrowth Double 周环比增长率 (%)
monthGrowth Double 月环比增长率 (%)
dailyTrend Array 30 天每日 PV [{date, count}]
hourlyDistribution Array 24 小时时段分布 [{hour, count}]
topPages Array 热门页面 Top 10
topReferers Array 来源 Top 10（按域名分组）
deviceBreakdown Object 设备分析 {mobile, desktop, bot}
browsers Array 浏览器分析 [{name, count}]
osList Array 操作系统分析 [{name, count}]
GET /open/v1/analytics/{projectId}/export 导出统计 CSV

权限： read

返回 CSV 格式文件，包含每日趋势、热门页面、来源分析、浏览器和操作系统数据。响应 Content-Type 为 text/csv。

表单收集

管理表单收集器及查看提交记录。基础路径：/open/v1/forms

GET /open/v1/forms?projectId={id} 获取表单列表

权限： read

查询参数

参数 必填 说明
projectId 是 工作区 ID
响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "name": "用户反馈",
      "slug": "a1b2c3d4",
      "fields": "[{...}]",
      "submitCount": 42,
      "isActive": true,
      "createdAt": 1709438400
    }
  ]
}
GET /open/v1/forms/{id} 获取表单详情

权限： read

返回表单的完整信息，包括字段定义和提交统计。

GET /open/v1/forms/{id}/submissions 获取提交记录

权限： read

查询参数

参数 必填 说明
page 否 页码（默认 1）
size 否 每页数量（默认 20）
响应示例 
{
  "code": 200,
  "message": "ok",
  "data": {
    "total": 42,
    "items": [
      {
        "id": 1,
        "formData": "{\"name\":\"张三\",\"email\":\"test@example.com\"}",
        "ip": "127.0.0.1",
        "createdAt": 1709438400
      }
    ]
  }
}
GET /open/v1/forms/{id}/export 导出提交记录 CSV

权限： read

返回 CSV 格式文件，包含表单所有提交记录。响应 Content-Type 为 text/csv。

用户信息

查询当前 API Key 关联的用户信息和会员状态。

GET /open/v1/user/me 获取当前用户信息

权限： read

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": {
    "id": 1,
    "phone": "138****1234",
    "username": "demo_user",
    "role": 20,
    "createdAt": 1709352000
  }
}

响应字段

字段 类型 说明
id Long 用户 ID
phone String 手机号
username String 用户名
role Int 角色（0=普通, 20=认证用户, 40=管理员）
createdAt Long 注册时间（Unix 时间戳）
GET /open/v1/user/membership 获取会员状态

权限： read

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": {
    "plan": 3,
    "planName": "专业",
    "endTime": 1740960000,
    "storageUsed": 52428800,
    "apiEnabled": true,
    "quota": {
      "plan": 3,
      "planName": "专业",
      "maxPages": 2147483647,
      "maxWorkspaces": 2147483647,
      "maxStorageBytes": 1073741824,
      "canHideHeaderFooter": true,
      "canExport": true,
      "allStyles": true,
      "canUseApi": true,
      "maxApiKeys": 10,
      "endTime": 1740960000,
      "storageUsed": 52428800
    }
  }
}

响应字段

字段 类型 说明
plan Int 当前套餐（0=免费, 1=基础, 2=进阶, 3=专业）
planName String 套餐名称
endTime Long 到期时间（Unix 时间戳）
storageUsed Long 已用存储（字节）
apiEnabled Boolean API 是否已开启
quota Object 详细配额信息

订阅管理

查看和管理项目下的订阅者（页面级订阅 + 博客级订阅）。基础路径：/open/v1/subscribers

GET /open/v1/subscribers?projectId={id} 获取订阅者列表

权限： read

查询参数

参数 必填 说明
projectId 是 工作区 ID
响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "id": 1,
      "projectId": 2,
      "email": "user@example.com",
      "type": "blog",
      "createdAt": 1709438400
    },
    {
      "id": 2,
      "pageId": 5,
      "email": "reader@example.com",
      "type": "page",
      "pageTitle": "更新日志",
      "pageSlug": "changelog",
      "createdAt": 1709524800
    }
  ]
}

响应字段

字段 类型 说明
id Long 订阅记录 ID
email String 订阅者邮箱
type String blog（博客订阅）或 page（页面订阅）
pageTitle String? 页面标题（仅 page 类型）
pageSlug String? 页面 slug（仅 page 类型）
createdAt Long 订阅时间（Unix 时间戳）
DELETE /open/v1/subscribers/{id}?projectId={pid} 删除订阅者

权限： full

删除指定的订阅记录。此操作不可恢复。

模板查询

查询可用的页面模板风格，此接口无需认证。

GET /open/v1/templates 获取模板列表

权限： 无需认证（公开接口）

响应示例 
{
  "code": 200,
  "message": "ok",
  "data": [
    { "id": "minimal", "name": "极简风", "desc": "Apple HIG" },
    { "id": "md3", "name": "Material 3", "desc": "圆角 · 紫色" },
    { "id": "legal", "name": "法务正式", "desc": "衬线 · 缩进" },
    { "id": "tech", "name": "科技感", "desc": "等宽 · 渐变" },
    { "id": "warm", "name": "温暖柔和", "desc": "圆体 · 暖色" },
    { "id": "notion", "name": "Notion 风", "desc": "清爽 · 结构化" },
    { "id": "glass", "name": "毛玻璃", "desc": "渐变 · 磨砂" },
    { "id": "brutal", "name": "粗野主义", "desc": "粗边框 · 撞色" },
    { "id": "terminal", "name": "极客终端", "desc": "暗黑 · 代码风" },
    { "id": "academic", "name": "学术论文", "desc": "衬线 · 严谨排版" },
    { "id": "journal", "name": "手账日记", "desc": "温馨 · 手写风" },
    { "id": "cyberpunk", "name": "赛博朋克", "desc": "霓虹 · 故障科技" },
    { "id": "retro", "name": "8-Bit 复古", "desc": "像素 · 街机风" },
    { "id": "magazine", "name": "时尚杂志", "desc": "大字号 · 图文排版" },
    { "id": "kids", "name": "纯真童趣", "desc": "圆润 · 马卡龙色" }
  ]
}

响应字段

字段 类型 说明
id String 模板标识，用于创建/更新页面时的 templateStyle 参数
name String 模板名称
desc String 模板简述

博客管理

批量操作博客相关功能。基础路径：/open/v1/pages

PUT /open/v1/pages/batch-style?projectId={id} 批量更新页面模板样式

权限： write

将指定工作区下所有页面的模板样式统一设置为目标值。适用于一键同步博客主题到所有页面。

查询参数

参数 必填 说明
projectId 是 工作区 ID

请求体

{
  "style": "notion"
}
字段 必填 说明
style 是 模板样式标识（可通过模板接口查询可用值）
响应示例 
{
  "code": 200,
  "message": "ok",
  "data": "已更新 5 个页面"
}
提示：页面更新接口 PUT /open/v1/pages/{id} 现已支持 hiddenFromBlog 字段（Boolean）， 设为 true 可将页面从博客首页隐藏。

错误码

状态码 说明
200 成功
400 请求参数错误
401 认证失败（密钥无效、已过期或已禁用）
403 权限不足（密钥权限级别不够）
404 资源不存在
429 请求过于频繁（超出 60 次/分钟限制）
500 服务器内部错误

快速开始

cURL 示例

# 获取工作区列表
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/workspaces

# 创建页面
curl -X POST \
  -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"测试","slug":"test","content":"# Hello","contentType":"markdown"}' \
  "https://litepage.cn/open/v1/pages?projectId=1"

# 发布页面
curl -X POST \
  -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/pages/1/publish

# 搜索页面
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  "https://litepage.cn/open/v1/pages/search?projectId=1&q=隐私"

# 获取页面统计
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/pages/1/stats

# 获取版本历史
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/pages/1/versions

# 创建 Webhook
curl -X POST \
  -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","secret":"s3cret","events":"publish,update"}' \
  "https://litepage.cn/open/v1/webhooks?projectId=1"

# 获取当前用户信息
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/user/me

# 获取会员状态
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/user/membership

# 获取项目统计
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/analytics/1

# 导出统计 CSV
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  -o analytics.csv \
  https://litepage.cn/open/v1/analytics/1/export

# 获取表单列表
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  "https://litepage.cn/open/v1/forms?projectId=1"

# 获取表单提交记录
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  https://litepage.cn/open/v1/forms/1/submissions

# 导出表单 CSV
curl -H "Authorization: Bearer pg_ak_YOUR_KEY" \
  -o submissions.csv \
  https://litepage.cn/open/v1/forms/1/export