Content API

如果定制网站已经有自己的页面、内容库或渲染方式，请选择 Content API。网站会主动 向 Surpasso 查询已经发布的文章，而不是由 Surpasso 把文章推入网站。

开始前需要准备

需要一位能够修改网站服务端代码和部署环境的开发者。API Key 绝对不能放在浏览器 代码中。

创建连接

1. 打开 Workspace → Integrations，选择 Content API。
2. 给连接填写一个容易识别的名称。
3. 点击 创建 API Key。
4. 立即复制密钥，完整内容只会显示一次。
5. 把密钥保存在网站的服务端环境变量中。

读取文章

GET /api/content/v1/articles
GET /api/content/v1/articles?limit=50
GET /api/content/v1/articles?updated_since=2026-10-13T00:00:00.000Z
GET /api/content/v1/articles/<article-id-or-slug>
Authorization: Bearer sp_content_...

API 只返回已经发布的文章，Surpasso 草稿会继续保持私有。每次最多读取 50 篇；已有 内容库只想读取最近变化的文章时，可以使用 updated_since。

成功响应会包含 ETag；有内容时也会包含 Last-Modified。后续请求可发送 If-None-Match 或 If-Modified-Since，内容没有变化时会返回不带正文的 304。 每个密钥每分钟最多调用 120 次；429 响应会附带 Retry-After。

安全与更新

• 把密钥保存在服务端环境变量中，不要放进浏览器文件。
• 根据网站发布需求设置缓存。
• 使用条件请求，避免重复下载没有变化的文章正文。
• 如果密钥出现在 Git、浏览器文件或截图中，立即更换。
• 如果网站使用 Next.js 并希望直接使用现成 Blog Starter，请改看 Next.js 教程。