使用站点 / CMS API
通过 API v1 认证、编辑和发布平台或独立 CMS 的内容。
使用站点 / CMS API
API v1 用于外部系统接入站点和 CMS 数据。先读取当前部署的接口契约,再创建限定权限的密钥,以版本保护保存草稿。
选择服务和部署方式
将 QOKIT_API_URL 设置为 API 服务来源(本地为 http://localhost:7777)或独立安装来源。QOKIT_PROJECT_ID 使用项目 ID;导出包在 data/seed.json 的 project.id 中保存它。公开读取使用项目 slug。
| 部署方式 | 能力 |
|---|---|
| 平台 | CMS 管理、导出和平台发布 |
cms-managed | 本地 CMS 管理和网站渲染 |
cms-only | 本地 CMS 管理、公开 headless 读取;不提供网站渲染 |
site-only | 静态 HTML 页面与资源;不提供运行时 API |
发现接口契约
每个服务只声明自身支持的操作。不支持的操作返回 404。API 1.0 保留现有无版本路由兼容性。
| 路径 | 用途 |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1:请求体、响应、权限和前置条件 |
GET /v1/capabilities | API 版本、部署类型和支持的操作 |
GET /v1/sdk/client.mjs | 零依赖 JavaScript 客户端 |
GET /v1/sdk/client.d.mts | 配套 TypeScript 类型声明 |
创建 API Key
将完成平台登录后获得的 accessToken 作为 SESSION_TOKEN。账号需要站点设置管理权限;签发密钥前必须完成所需身份验证。
curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'独立 CMS 使用部署管理员邮箱和密码登录,保存会话 Cookie,然后创建密钥:
curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
-H 'Content-Type: application/json' \
-d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'创建时仅返回一次 token。将它保存为服务端环境变量 QOKIT_SITE_API_KEY;请求使用以 qk_site_ 开头的 Bearer token。密钥默认 90 天有效,可设为 1–365 天,每项目最多 50 个有效密钥。使用具备设置管理权限的登录会话,通过 GET /v1/projects/{id}/api-keys 列出密钥,通过 DELETE /v1/projects/{id}/api-keys/{keyId} 撤销密钥。
仅选择集成需要的权限范围。每次请求重新检查创建者的访问权限和角色;到期、撤销与角色变更在后续请求生效。API Key 不能管理其他密钥。
| Scope | 用途 |
|---|---|
content:read / content:write | 读取 / 编辑集合和条目 |
content:publish | 显式发布,以及直接发布条目的写入 |
pages:read / pages:write | 读取 runtime / 编辑页面内容、结构、SEO 和表单 |
media:read / media:write | 读取 / 管理媒体和文件夹 |
settings:read / settings:write | 读取 / 编辑站点设置 |
users:read / users:write | 读取 / 管理 CMS 用户 |
leads:read / leads:write / analytics:read | 读取 / 更新线索、读取 CMS 仪表板 |
marketing:read / marketing:write | 读取 / 生成营销内容 |
deployments:read / deployments:write | 平台导出和发布作业 |
sync:write / updates:read / updates:write | 独立安装同步和签名更新 |
使用 SDK 保存草稿
工作区包为 @qokit/site-api,尚未发布到 npm。外部项目将两个客户端文件下载到 sdk;新导出包已包含这两个文件。
mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mts本例需要 content:read 和 content:write。将 en 替换为项目已启用的语言。示例会创建一个新集合;再次运行时复用已有集合 ID,避免重复创建。
import { createSiteApiClient } from './sdk/client.mjs';
const api = createSiteApiClient({
baseUrl: process.env.QOKIT_API_URL,
projectId: process.env.QOKIT_PROJECT_ID,
token: process.env.QOKIT_SITE_API_KEY
});
const collection = await api.collections.create({
key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);保存草稿会保留已发布条目的上一份公开快照。审阅后,拥有 content:publish 的密钥可以显式发布当前保存版本。平台页面编辑仍是草稿,网站正式上线需要完成站点发布流程。
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });需要恢复时,先读取 api.entries.revisions(id),再调用 api.entries.restore(id, revisionId, { expectedUpdatedAt })。其他已声明的操作使用 api.request(path, options),可传入 idempotencyKey。客户端不会自动重试写入。
管理接口
以下路径加上 /v1/projects/{id} 前缀。OpenAPI 列出所有操作、请求字段及部署差异。DELETE 对集合、条目和媒体执行归档。
| 路径 | 方法 |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, POST |
/cms/media/{assetId}, /cms/media/folders/{folderId} | PUT, DELETE |
/runtime, /content/{locale} | GET; PUT /content/{locale} |
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, PUT |
/cms/users, /cms/users/{memberId} | GET / POST, PUT / DELETE |
/leads, /leads/{leadId} | GET, PUT |
平台媒体支持 URL 注册和上传意图;独立上传使用 fileName、contentType 和 contentBase64,文件最大 10 MB,并校验文件签名。平台用户变更需要 Idempotency-Key;本地用户创建需要 12–1024 字符密码。CSV、批量写入和翻译关联属于平台扩展。
版本、分页和错误
资源更新、归档和修订恢复必须提交 expectedUpdatedAt,取自最近读取的 updatedAt。缺少版本返回 428;版本过期返回 409。
页面结构、SEO 和表单写入先读取 GET /v1/projects/{id}/runtime,将 content.updatedAt 和 siteVersion.updatedAt 分别作为 baseContentUpdatedAt 和 baseSiteVersionUpdatedAt 提交。平台仍检查 Builder 修订和正在使用的编辑租约。
分页列表默认 page=1&pageSize=24,每页最多 100 条。管理列表返回 items,公开列表返回 entries。修订和文件夹返回数组。导出内容时需读取全部分页。
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}响应包含 X-Request-Id 和 X-Qokit-Api-Version。错误包含稳定的错误代码和请求 ID:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}遇到 401 检查密钥有效性;遇到 403 检查 scope 和创建者权限。遇到 409 重新读取并比较变更;遇到 428 补充版本。遇到 429 遵循 Retry-After。限流为每密钥 / 来源每分钟 300 次,平台另有 IP 和写入限制。
独立安装配置
平台浏览器集成使用 CORS_ALLOWED_ORIGINS。独立 API Key 的浏览器调用在 SITE_API_ALLOWED_ORIGINS 中配置精确来源;Cookie 管理会话保持同源。公开 CMS 读取也可配置 CMS_ALLOWED_ORIGINS。CMS-only 媒体 URL 使用 CMS_PUBLIC_URL。
备份完整数据目录和上传文件,包括私有的 data/api-security.json 与 data/api-revisions.json。密码和 API Key 保存为哈希并留在本地。每个数据目录由一个 Node 进程写入。
旧导出包通过签名运行时更新获得 v1。升级后通过 HTTP 下载当前契约和客户端;包内文件仍是导出时的快照。
无需凭证的公开读取见 调用公开内容 API.
最后更新于