内容同步接口用于把客户站点公开内容写入 GrowthOS。同步后的内容会用于知识检索、AI 客服回答、SEO/GEO 体检、审核发布和云端任务队列。 浏览器端不要直接调用内容同步接口。该接口应由插件、服务端任务或客户站点代理调用。

​
接口总览

能力方法路径调用方
同步内容批次POST/content/sync插件或客户站点服务端

​
通用请求头

Header必填说明
Authorization: Bearer <site_token>是站点服务端 token
Content-Type: application/json是请求体格式
Idempotency-Key建议同一页同步重试时保持一致，长度 8-160

​
POST /content/sync

一次最多提交 200 条内容。大站点建议分页同步，每页使用稳定的 Idempotency-Key。 
POST /api/connector/v1/content/sync
Authorization: Bearer <site_token>
Content-Type: application/json
Idempotency-Key: sync-20260601-page-1

​
Body 参数

字段类型必填说明
itemsarray是内容数组，最多 200 条
items[].externalIdstring是客户站点侧稳定内容 ID
items[].typestring是page、post、product、category、tag、custom
items[].localestring否内容语种，例如 zh-CN、en-US
items[].pathstring是站内路径，用于 SEO/GEO overlay 匹配
items[].urlstring否完整访问 URL
items[].titlestring是标题
items[].excerptstring否摘要
items[].contentstring是可检索正文，建议传清洗后的纯文本或正文 HTML
items[].statusstring否published、draft、private、archived
items[].rawobject否源站扩展数据，例如分类、标签、更新时间
snapshot.completeboolean否本轮全量快照是否完成
snapshot.seenarray否本轮快照扫描到的内容 ID 列表

​
请求示例

curl -X POST "$CONNECTOR_API_BASE/content/sync" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-20260601-page-1" \
  -d '{
    "items": [
      {
        "externalId": "wp-post-31",
        "type": "post",
        "locale": "zh-CN",
        "path": "/archives/31",
        "url": "https://customer.example/archives/31",
        "title": "文章标题",
        "excerpt": "文章摘要",
        "content": "正文纯文本或可检索内容",
        "status": "published",
        "raw": {
          "updatedAt": "2026-06-01T08:00:00.000Z",
          "categories": ["新闻"],
          "tags": ["SEO"]
        }
      }
    ],
    "snapshot": {
      "complete": false
    }
  }'

​
成功响应

{
  "ok": true,
  "data": {
    "synced": 1,
    "archived": 0,
    "reconciled": {
      "retargeted": 0,
      "rejectedStale": 0
    },
    "siteId": "site_id",
    "lastSyncedAt": "2026-06-01T08:00:00.000Z"
  },
  "requestId": "request_id"
}

​
响应字段

字段说明
synced新增或更新的内容数量
archived标记归档的内容数量
reconciled.retargeted被重新关联的内容数量
reconciled.rejectedStale被判定为旧数据并拒绝的数量
lastSyncedAt本次同步完成时间

​
全量快照与增量同步

如果连接器执行全量同步，可以使用 snapshot 声明本轮扫描状态：
场景snapshot.complete说明
中间分页false继续等待后续分页
最后一页trueGrowthOS 可根据 seen 清理缺失的原站内容
增量同步不传只更新本次提交的内容
snapshot.seen 中的条目应包含稳定的 externalId 和可选 locale。不要把手动创建、后台草稿或私密内容作为公开同步内容提交。

​
常见错误

HTTP错误码说明处理建议
400INVALID_REQUEST内容为空、超过 200 条或字段缺失修正请求体后重试
401INVALID_TOKENtoken 无效重新检查站点 token
402INSUFFICIENT_QUOTA当前规则启用扣费且余额不足提醒客户补充额度
409IDEMPOTENCY_CONFLICT同一个幂等键被不同请求体复用使用新的幂等键
429RATE_LIMITED请求过快按 Retry-After 退避重试

​
实现要点

  • 同一源内容要长期保持同一个 externalId。
  • path 要规范化，避免 /a 和 /a/ 被当成两条内容。
  • 大站点必须分页同步，建议每页 50-200 条。
  • 内容同步应传公开可检索内容，不要同步后台草稿、私密页面或敏感字段。
  • 多语言内容建议每个语种单独一条，使用同一 externalId 加不同 locale，或使用客户站点自己的多语言 ID。