REST API 概览

Profound CMS REST API 由 Rust translation_manager 服务提供。它公开了供渲染器使用的无头读取/流式端点，以及用于内容、翻译和 CSV 导入的写入端点。

所有示例都使用 {CMS_API_URL} 作为 CMS API 主机的基础 URL（例如 https://cms.dev.tryprofound.com）。没有全局路径前缀——路由挂载在根路径，例如 {CMS_API_URL}/routes。

身份验证

API 会根据端点使用两种不同的方案。

API 密钥（无头读取 + 变体更新）

将密钥作为 x-api-key 请求头或 api_key 查询参数发送：

curl '{CMS_API_URL}/dataset/post?websiteId=<uuid>' \
  -H 'x-api-key: <your-api-key>'

密钥会通过 WorkOS 进行验证，并在内存中短暂缓存。对于读取端点，仅当服务器设置了 require_schema_api_key = true 时才需要 API 密钥；否则允许匿名读取。变体更新（PATCH /dataset/{schema_name}）始终需要携带 content_write 权限的有效密钥。

使用 API 密钥身份验证的端点：/routes、/route、/blocks*、/components*、/dataset/*、/schemas/*、/content-changes。

Bearer JWT（WorkOS）

管理端点需要 WorkOS 用户 JWT：

curl '{CMS_API_URL}/usage?orgId=<uuid>' \
  -H 'Authorization: Bearer <workos-jwt>'

使用 Bearer 身份验证的端点：/translation、/translations、/usage、/csv。

解析网站（租户）

API 密钥端点按以下顺序解析目标网站：

1. ?websiteId=<uuid> 查询参数
2. 与已配置网站域名匹配的 Host 请求头
3. CMS_WEBSITE_ID 回退（单租户 / 本地开发）

如果以上都无法解析为有效的 UUID，该端点将返回 400。

错误模型

健康检查

GET {CMS_API_URL}/health 返回 { "status": "ok" }，且不需要身份验证——将其用于存活性探测。