本页内容以 12.0.2 为准（发布日期 2026-10-26），接口清单取自运行实例的 OpenAPI 定义；历史版本差异见《版本发布记录》。

API 体系总览

PowerCMS 12 是 Headless CMS：内容模型与内容统一存储，任何前端（网站、App、小程序、大屏）都可以通过标准接口取数渲染。开放面包括：

通道	入口	用途
管理端 REST API	`/api/v1/...`	站点、内容模型、内容、媒体、工作流等后台能力；需认证
Delivery API	`/api/v1/delivery/...`	面向前台站点的公开只读取数接口
GraphQL	`/graphql/sites/{siteId}`	按站点查询内容，一次请求取关联结构
MCP Server	`/api/mcp`	面向 AI 客户端的标准 MCP 工具面
OpenAPI 文档	`/swagger-ui.html` 与 `/v3/api-docs`	在线浏览与调试全部 REST 端点，可直接导出 OpenAPI 定义

本文示例中的 {siteId} 均为站点 UUID，可在管理端「站点」页或 GET /api/v1/sites 返回结果中获取。建议开发时对照你所在环境的 Swagger 页面核对参数细节。

认证与授权

2.1 会话登录（管理端 / 脚本）

POST /api/v1/auth/login
Content-Type: application/json

{"username": "admin", "password": "******"}

# 200 OK
{"authenticated": true, "username": "admin", "loginMode": "BACKEND"}

登录成功后建立会话 Cookie；GET /api/v1/auth/me / /auth/status 可查询当前登录状态，POST /api/v1/auth/logout 退出。后台登录与前台会员登录是不同通道（/auth/backend/login 与 /auth/frontend/login），后台会话才可访问管理 API。

2.2 API Token（服务端集成推荐）

在管理端「个人中心」创建 API Token（对应 POST /api/v1/me/tokens），之后以 Bearer 方式调用，适合 CI 脚本与服务端集成：

curl -H "Authorization: Bearer pcm_xxxxxxxx" \
     https://<host>:8080/api/v1/sites

Token 前缀 pcm_...；OAuth 访问令牌为 pcm_oat_...（配合 /oauth/token 等标准端点，绑定 DPoP 时需携带匹配的 DPoP 证明）；
令牌过期与非法返回可区分的 401（含 RFC 6750 invalid_token 挑战），调用方可据此判断是否重新签发；
可随时在 DELETE /api/v1/me/tokens/{id} 吊销。

2.3 统一错误体

所有 JSON 接口的错误返回统一结构，traceId 可直接用于运维排查：

{"code": "BAD_REQUEST",
 "message": "请求参数错误",
 "traceId": "3a84fa0d090a40308cdddf2cb9eece1b",
 "details": []}

管理端 REST API

管理端 API 覆盖平台全部后台能力（40 余个资源组、610 余条端点路径），全部以 /api/v1 为前缀，资源按站点隔离。常用资源组：

资源组	代表端点	说明
站点	`GET /api/v1/sites`、`POST /api/v1/sites`、`DELETE /api/v1/sites/{siteId}`	站点与环境（preview / staging / production）、域名管理；已归档站点可物理删除，删除前用 `GET /api/v1/sites/{siteId}/deletion-preview` 查看级联影响
内容模型	`/api/v1/sites/{siteId}/content-types` 及版本、字段、生命周期子资源	内容类型的定义、版本与发布
内容	`POST /api/v1/sites/{siteId}/contents`、`GET /api/v1/contents/{id}`、`DELETE /api/v1/contents/{id}`	内容条目的创建、检索、状态流转与删除；批量操作走 `/sites/{siteId}/contents/batch-status`、`/batch-delete`
内容分享	`GET /api/v1/sites/{siteId}/contents/{contentId}/shares`	资源分享链接签发与吊销（`POST /shares`、`POST /shares/{shareId}/revoke`）
会员	`POST /api/v1/sites/{siteId}/frontend-users/{id}/approve`、`/unlock`	会员注册审核通过与账号解锁
知识库（doc-kb）	`/api/v1/sites/{siteId}/doc-kb/documents`、`/{docUnitId}/chunks`、`/publish`	12.0.1 新增：文档解析与知识库（RAG）管理面，详见 §3.1
分类与标签	`GET /api/v1/categories/{categoryId}/contents`	栏目 / 分类体系
媒体	`/api/v1/sites/{siteId}/media/**`	媒体库、文件夹、转码、Knox 对接、字幕 / 转写等；列表与分页支持 `folderPath` 按目录浏览，文档预览按 `/media-preview/{siteId}/{assetId}?page=N` 取指定页
页面与模板	`/api/v1/sites/{siteId}/pages/**`、`template-projects`	页面组装、模板工程与主题
工作流	`/api/v1/workflows/{id}/publish` 等	审批流定义与版本管理
身份与权限	`/api/v1/users`、`roles`、`access-policies`	用户、角色与访问策略
检索	`GET /api/v1/sites/{siteId}/contents/search`	后台全文检索
AI	`GET /api/v1/ai/embedding-cache`（`siteId` 可选）	向量缓存用量与清理效果观测
媒体端点登记	`POST /api/v1/knox/register`	媒体服务器启动时凭 `client_secret` 登记端点，已注册则保持原配置
系统	`/api/v1/tasks`、`system-logs`、`notifications`	异步任务、系统日志、通知

3.1 12.0.1 新增：知识库（doc-kb）接口组

文档解析与知识库是本版本主线，对应一套 /api/v1/sites/{siteId}/doc-kb/** 管理接口（均需站点级权限）：

端点	方法	说明
`/doc-kb/documents`	GET / POST	文档单元列表与创建
`/doc-kb/documents/{docUnitId}`	GET	文档单元详情（含解析状态与索引对账信息）
`/doc-kb/documents/{docUnitId}/chunks`	GET	该文档的分块列表
`/doc-kb/documents/{docUnitId}/publish`	POST	发布 / 下线，驱动访客所见索引同步
`/doc-kb/documents/{docUnitId}/resync-public-index`	POST	对账并重建公开索引
`/doc-kb/documents/{docUnitId}/rechunk`	POST	重新分块（结构调整后使用）
`/doc-kb/documents/{docUnitId}/citation-check`	POST	引用链接自检
`/doc-kb/documents/{docUnitId}/preview`	GET	解析结果预览
`/doc-kb/documents/{docUnitId}/chunk-stats`	GET	单文档分块统计与异常识别
`/doc-kb/chunks/{chunkId}`、`/history`、`/rollback`	GET / GET / POST	分块详情、修订历史与回滚
`/doc-kb/documents/{docUnitId}/chunks/{ordinal}/rollback`	POST	按序号回滚指定分块
`/doc-kb/revisions/{revisionId}/diff`、`/revisions/diff`	GET	分块修订比对结果
`/doc-kb/stats`	GET	知识库整体统计（配额页数据源）
`/doc-kb/batch/{operation}`、`/batch/{operation}/preview`	POST / GET	批量操作与执行前预览

完整清单以 /swagger-ui.html 为准；各端点的请求 / 响应 schema 也可从 /v3/api-docs 导出后生成客户端 SDK。知识库检索侧的多层 ACL、跨源 RRF 融合与重排降级对用户可见，详见 12.0.1 发布说明。

Delivery API（前台取数）

Delivery API 面向站点前台公开（只读），无需登录即可按站点获取已发布内容，是 Headless 场景下前端取数的主通道：

端点	参数	说明
`GET /api/v1/delivery/sites/{siteId}/contents`	`categoryId`、`page`、`size`	按分类分页列出已发布内容
`GET /api/v1/delivery/sites/{siteId}/contents/{contentId}`	—	内容详情（含动态字段）
`GET /api/v1/delivery/sites/{siteId}/contents/query`	`contentType`（必填）、`limit`、`orderBy`、`status`、`forViewer`	按内容模型编码查询内容列表；`forViewer` 按当前访客权限过滤
`GET /api/v1/delivery/sites/{siteId}/folders`	—	前台可见目录树（配合数字资源库按栏目浏览）
`GET /api/v1/delivery/sites/{siteId}/content-forms/{code}`	路径参数 `code`	按编码取表单定义（12.0.1 起开放）
`GET /api/v1/delivery/sites/{siteId}/contents/{contentId}/actions`、`POST /contents/{contentId}/like`	—	内容可用动作查询与点赞上报
`GET /api/v1/delivery/sites/{siteId}/me/favorites`、`PUT\|DELETE /me/favorites/{contentId}`	—	会员收藏列表、加入收藏与取消收藏
`GET /api/v1/delivery/sites/{siteId}/me/history`、`POST /me/history/{contentId}`	—	会员浏览历史列表与上报
`GET /api/v1/delivery/sites/{siteId}/me/inbox`、`POST /me/inbox/read`、`POST /me/inbox/comments/{messageId}/replies`	—	消息收件箱、已读标记与楼中楼回复
`GET /api/v1/delivery/sites/{siteId}/me/uploads`、`POST /me/uploads/contents`、`POST /me/uploads/files`、`DELETE /me/uploads/{contentId}`	—	会员上传中心：列表、创建条目、上传文件与删除
`GET\|POST /api/v1/delivery/sites/{siteId}/me/shares`、`POST /me/shares/{shareId}/revoke`	—	会员分享链接创建、列表与吊销
`POST /api/v1/delivery/sites/{siteId}/me/password`	—	会员修改密码
`GET\|POST /api/v1/delivery/sites/{siteId}/member-registration`	—	会员注册项查询与注册提交（12.0.1 起走注册审核流程）
`GET /api/v1/delivery/sites/{siteId}/shares/{token}`	路径参数 `token`	凭分享令牌获取分享内容
`GET /api/v1/delivery/sites/{siteId}/viewer`	—	当前访客身份与权限上下文
`GET /api/v1/delivery/sites/{siteId}/pages`	—	页面树 / 页面数据
`GET /api/v1/delivery/sites/{siteId}/search`	关键词等	前台全文搜索
`POST /api/v1/delivery/sites/{siteId}/media/{assetId}/play-token`	—	签发受控播放令牌（音视频点播）
`POST /api/v1/delivery/sites/{siteId}/contents/{contentId}/views`	—	浏览计数上报

查询结果中，内容模型的自定义字段同时以 fields 对象与平铺键两种形式返回（字段名带类型后缀，如 tel_s、sort_order_i）：

curl "https://<host>:8080/api/v1/delivery/sites/{siteId}/contents/query?contentType=about-contact&limit=1"

[{
  "id": "093e3c5b-...", "title": "宝丽星通联系方式",
  "status": "PUBLISHED", "routePath": null,
  "fields": { "tel_s": "010-62129317", "sales_s": "sales@example.com" },
  "tel_s": "010-62129317", "sales_s": "sales@example.com"
}]

Delivery API 默认匿名可读。若站点内容涉密，可通过访问策略限制公开范围，仅放行需要公开的模型与字段。

4.1 站点应用（webapps）部署与取数

除 Headless 取数与 MVC 渲染外，12.0.1 起可把 React / Vue 前端产物直接部署为「站点应用」：

按站点 Key 部署到 webapps/{siteKey}/，入口 GET /webapps/{siteKey}，匿名公开；
缺失尾斜杠的请求会 302 补斜杠并保留查询参数，避免 Vite 相对资源路径 404；
应用内可相对路径寻址 API（如 ./api/v1/delivery/...），由请求改写过滤器归一到站点维度，前端无需硬编码站点 ID；
资源详情页等场景会自动注入第一方统计脚本 analytics.js，按资源上报 PAGEVIEW / CONTENT_VIEW / DOWNLOAD（预览与编辑态不注入，避免污染统计）。

GraphQL

每个站点拥有独立 GraphQL Schema，适合一次请求取回内容及其关联结构（如文章 + 作者 + 栏目）：

端点	说明
`POST /graphql/sites/{siteId}`	标准 GraphQL 查询入口（body 为 `{"query": "..."}`）
`GET /graphql/sites/{siteId}/schema`	查看该站点的 GraphQL Schema
`POST /api/v1/sites/{siteId}/graphql-schema/rebuild`	内容模型变更后重建站点 Schema（系统管理员）

curl -X POST "https://<host>:8080/graphql/sites/{siteId}" \
     -H "Content-Type: application/json" \
     -d '{"query":"{ __schema { queryType { name } } }"}'

FreeMarker 模板开发

除了 Headless 取数，PowerCMS 12 也支持服务端渲染：页面、区块与组件模板使用 FreeMarker（.ftl）编写，由平台渲染后输出 HTML。内容类型的 displayTemplate 指向模板路径（如 /templates/about-contact.ftl）。

6.1 渲染模型：顶层变量（以 12.0.2 为准）

模板渲染时平台注入统一的顶层模型。已登记的顶层变量全集如下（引用未登记的顶层名字会在模板保存校验时报错）：

类别	变量
页面渲染核心	`zones`（页面区块集合）、`renderedZones`（已渲染区块 HTML）、`renderComponent`（渲染组件的方法）、`page`、`currentPage`、`title`、`id`
内容	`content`、`contentModel`（当前内容条目，二者同源）、`category`、`fields`、`pagination`
站点与配置	`site`、`siteConfig`、`siteContext`、`globalProperties`、`language`、`locale`
请求上下文	`request`、`requestParameters`、`cookies`、`session`、`currentUser`、`now`、`modePreview`（是否预览态）、`route`、`routePath`、`url`
导航	`navigation`、`navTreeBuilder`、`navBreadcrumbBuilder`、`renderBreadcrumb`
主题包装	`pageBody`、`body`、`htmlHead`、`header`、`footer`
扩展与兼容	`application`、`applicationContext`、`siteItemService`、`urlTransformationService`、`crafterEnv`、`flags` 等

6.2 页面模板：区块（Zone）与组件

页面模板由「区块」组织：zones 是「区块 key → 组件实例列表」的 Map，renderedZones 保存各区块的渲染结果。renderComponent 按组件路径（/site/components/...）或引用名渲染组件，还可传入父组件 ID 与附加模型，典型写法：

<#-- 页面骨架模板 -->
<!DOCTYPE html>
<html lang="${locale}">
<head>
  <title>${title!""}</title>
  ${htmlHead!""}
</head>
<body>
  ${renderComponent("/site/components/header")}
  <main>
    <#-- 按引用名渲染，可选：父组件 ID、附加模型 -->
    ${renderComponent("/site/components/content-body")}
    <#-- 直接遍历区块中的组件实例 -->
    <#list (zones["main"])![] as component>
      ${renderComponent(component.reference)}
    </#list>
  </main>
  ${renderComponent("/site/components/footer")}
</body>
</html>

6.3 容器与组件模板

容器模板可使用的顶层变量包括 siteId、pageId 与 contentQuery（在模板中直接按条件查询内容的取数方法）。组件模板可用 content / contentModel（当前组件数据）、params（组件参数）、templateModel 与 additionalModel（附加模型），以及 editableText 方法——输出可被可视化编辑器行内编辑的文本，第一个参数为字段名，后两个为可选的编辑器形态与格式：

<#-- 组件模板示例：图文卡片 -->
<div class="card">
  <h3>${editableText("title_s")!""}</h3>
  <p>${editableText("summary_s", "minimal", "text")!""}</p>
</div>

6.4 模板校验与最佳实践

落库前试渲染：模板保存时平台会做"顶层严格、数据宽松"的试渲染——引用未登记的顶层名字（如把 @powercms.zone 指向不存在的命名空间）会直接报错，数据字段缺失则放行，便于先存模板后补数据；
对可能缺省的变量统一使用 FreeMarker 空值处理（! 默认值、?? 判空），避免渲染期空指针；
模板放版本库管理（配合 Git 组件），走发布流程进入各环境，避免直接改生产模板；
预览与线上使用同一套渲染引擎（GET /api/v1/preview/page、/preview/template），所见即所得。

可视化组件接入（UVE）

可视化编辑器（UVE）通过 iframe 加载站点预览页，并在编辑态注入桥接脚本 /api/v1/preview/uve-bridge.js。只要模板输出符合下方标记约定，页面即可在编辑器中被选中、拖拽排序与行内编辑。

7.1 结构标记属性

属性	位置	说明
`data-pcms-zone-root`	区块容器	标记一个区块（Zone），值为区块 key
`data-pcms-component`	组件根元素	标记组件，值为组件实例 ID，编辑器据此定位与排序
`data-pcms-zone`	组件根元素	组件所属区块 key
`data-pcms-index`	组件根元素	组件在区块内的序号
`data-pcms-kind`	组件根元素	组件类型（如 `EMBEDDED`）
`data-pcms-zone-empty`	区块容器	空区块占位，编辑器显示"添加组件"引导

7.2 行内编辑标记

属性	说明
`data-pcms-editable-field`	可编辑字段名，编辑器在此元素上提供行内编辑
`data-pcms-editable-component`	所属组件 ID（缺省取最近祖先组件）
`data-pcms-editable-format`	编辑格式：`text`（默认）或富文本
`data-pcms-editable-mode`	编辑器形态（默认 `minimal`）
`data-pcms-content-item` / `data-pcms-content-version`	关联内容条目与版本，保存时回写对应版本

组件模板中使用 editableText 方法输出的文本会自动携带上述行内编辑标记，无需手写。

7.3 postMessage 协议

桥接脚本通过 postMessage 与编辑器双向通信；在收到带匹配 nonce（页面 URL 的 uveNonce 参数）的 pcms:init 之前保持静默，且只信任编辑器来源：

方向	消息	说明
预览页 → 编辑器	`pcms:ready`	桥接脚本就绪
预览页 → 编辑器	`pcms:bounds`	上报区块 / 组件几何信息（选中框、排序基准）
预览页 → 编辑器	`pcms:component-clicked` / `pcms:component-hovered`	组件点击 / 悬停
预览页 → 编辑器	`pcms:inline-edit-started` / `-save` / `-ended`	行内编辑生命周期与保存内容
编辑器 → 预览页	`pcms:init { nonce }`	初始化握手
编辑器 → 预览页	`pcms:flush-bounds` / `pcms:reload`	要求重新上报几何信息 / 重载页面

7.4 预览通道

POST /api/v1/preview/token：签发预览令牌（需认证）；
GET /api/v1/preview/page / /preview/template / /preview/content / /preview/content-item：按令牌渲染页面、模板或内容预览，未保存草稿也能所见即所得。

MCP Server

面向 AI 客户端，PowerCMS 12 内置标准 MCP Server（端点 /api/mcp），提供 Tools / Resources / Prompts 三类结构化工具面，覆盖内容、站点、工作流、媒体、知识库等域，任何标准 MCP 客户端即插即用；工具面与 REST API 同源，权限模型一致：

content.search      # 内容检索
content.draft       # 内容起草
flow.todo           # 工作流待办

能力分 Tools / Resources / Prompts 三类，双传输并存，协议归一到 MCP 2025-06-18 修订版；
配额与审计：GET /api/v1/mcp/quota 查询配额，/api/v1/sites/{siteId}/mcp-audit 查看调用审计；
工具 Token 权限分 L0 只读 / L1 草稿 / L2 发布三级，只能收窄不能扩大，越级调用返回 403 并落审计。

工具数量与清单随版本演进，建议客户端在初始化时通过标准协议拉取 tools/list，以运行实例的实时清单为准。

MCP 工具面详情见 AI 能力 · MCP 工具清单。

API 与模板开发