Publish API

RankBloom 为你接入的网站撰写 SEO 博客内容。成稿要离开 RankBloom 去到哪里——WordPress 站点、CMS、自动化平台，或者你自己的代码——都由 Publish API 负责。

官方 WordPress 插件以及 Zapier、Make 集成，用的都是这同一套 API。

基础 URL

https://app.getrankbloom.com/api/publish

身份验证

每个请求都必须携带 连接令牌。在 RankBloom 的连接中创建：选好站点和平台，然后点击 创建连接。令牌只显示一次，且只以哈希形式存储，创建时请自己保存一份。

一个令牌只对应一个站点。用下面任意一个请求头发送即可：

Authorization: Bearer rb_live_xxxxxxxx
X-RankBloom-Token: rb_live_xxxxxxxx
X-API-KEY: rb_live_xxxxxxxx

之所以接受三种，是因为共享主机和托管主机经常会删掉请求头 Authorization，而部分自动化平台默认只发送 X-API-KEY 请求头。

切勿把令牌放在查询字符串里。 它会被访问日志和沿途的每一层代理记录下来，而 API 根本不会从那里读取令牌。

撤销连接会立即生效。已撤销的令牌和未知令牌返回完全相同的响应，调用方无法靠差异来试探哪些令牌有效。

接口

GET /v1/ping

验证令牌，并返回它绑定的连接和站点。可以当作连接测试来用。

curl https://app.getrankbloom.com/api/publish/v1/ping \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

{
  "ok": true,
  "contract_version": 1,
  "label": "Example Site",
  "connection": { "id": "…", "name": "Make — Example Site", "platform": "make" },
  "site": { "id": "…", "name": "Example Site", "url": "https://example.com" }
}

label 是这个连接的名称，纯文本、给人看的。自动化平台用它来标注已连接的账号。

GET /v1/posts

已连接站点的最新文章，按时间倒序。只读接口，不会改变任何状态，因此可以放心地定时轮询。

参数	类型	默认值	说明
`limit`	integer	25	最大 100
`offset`	integer	0	跳过前面这么多篇文章
`since`	ISO 8601	—	只返回该时间点及之后创建的文章

curl "https://app.getrankbloom.com/api/publish/v1/posts?limit=100&offset=0" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

{
  "ok": true,
  "contract_version": 1,
  "count": 46,
  "limit": 100,
  "offset": 0,
  "posts": [ … ]
}

分页。 每次把 offset 增加 limit 即可向前翻阅历史文章。接口不返回总数：当某一页少于 limit 条时，说明已经到底了。结果先按创建时间、再按 id 排序，因此即使两篇文章时间戳相同，分页也保持稳定。

POST /v1/status

告诉 RankBloom 这篇文章后来怎么样了。正是这一步把“已交付”变成“已上线”，并且让这篇文章不再被重复下发。

curl -X POST https://app.getrankbloom.com/api/publish/v1/status \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "b86cbffe-…",
    "status": "delivered",
    "external_url": "https://example.com/my-post",
    "external_id": "123"
  }'

字段	是否必填	说明
`post_id`	是	字段 `id` 的来源是 `/v1/posts`
`status`	是	`delivered`, `failed` 或 `skipped`
`external_url`	否	上线后的地址
`external_id`	否	远端系统自己的 id
`error`	否	失败时的原因

令牌只能回传自己所属站点的文章状态。

文章数据结构

唯一的标准结构，版本标识为 contract_version.

字段	类型	说明
`id`	string	稳定不变，可作为幂等键使用
`title`, `slug`, `excerpt`	string	`slug` 是去重之后的最终值
`content_html`, `content_md`	string	正文，两种格式都给
`meta_title`, `meta_description`	string	SEO 元数据
`primary_keyword`, `keywords`, `category`, `tags`	string / array	分类与标签
`canonical_url`	string	已设置时的 canonical 链接
`schema_json_ld`	object	已解析的对象，不是 JSON 字符串
`featured_image_url`	string	已托管的图片，可直接使用
`audio_url`	string	文章有配音时的音频
`audio_duration_seconds`, `audio_voice`	number / string	配音详情
`status`	string	`published` 或 `draft`
`author`, `author_title`, `author_url`	string	署名信息
`created_at`, `published_at`	ISO 8601	时间戳

所有字段始终存在。 不适用的值返回的是 null 而不是省略这个字段。没有配音的文章，拿到的就是 audio_url: null，这是正常情况，不是错误。写集成时请判断值是不是 null，而不要去判断字段存不存在。

这份契约 只增不改。字段不会改名、不会换类型，也不会删除，因为线上那些集成会一直请求 version 1。破坏性变更只会作为新版本发布，与当前版本并行提供。

错误

出错时返回对应的 HTTP 状态码，以及一个带可读错误信息的 JSON 响应体。

{ "ok": false, "error": "Invalid or revoked connection token." }

状态码	含义
`400`	必填字段缺失或格式不正确
`401`	令牌缺失、未知或已撤销
`404`	该文章不属于此连接

现成的集成

你不用自己写代码。同一套 API 已经封装成了现成的集成：

WordPress 提供官方 Get RankBloom 插件，一键连接，无需粘贴令牌。
Make 提供自定义应用，内置 Watch Posts 触发器和 Mark Post as Published 动作。
Zapier 提供 New Post 触发器和 Mark Post as Published 动作。

技术支持

对 API 有疑问，或发现行为和文档不一致，请发邮件到 support@getrankbloom.com.