Publish API

RankBloomは、接続したWebサイト向けにSEOブログ記事を作成します。Publish APIは、完成した記事をRankBloomから送り出し、WordPressサイト、CMS、自動化プラットフォーム、あるいは自作のコードなど、届けたい場所へ渡すための仕組みです。

公式WordPressプラグイン、ZapierおよびMake連携の裏側で動いているのも、同じAPIです。

ベースURL

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

認証

すべてのリクエストには 接続トークンが必要です。RankBloomの接続で作成します。サイトとプラットフォームを選び、 接続を作成をクリックします。トークンは一度しか表示されず、ハッシュとしてのみ保存されるため、作成時に必ず控えておいてください。

トークンは1つのサイトに紐づきます。次のいずれかのヘッダーで送信してください：

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

3種類を受け付けているのは、共用サーバーやマネージドホストが 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の順に並ぶため、2件の記事が同じタイムスタンプを持つ場合でもページングは安定します。

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`	いいえ	公開先のURL
`external_id`	いいえ	連携先システム側のID
`error`	いいえ	失敗した場合はその理由

ステータスを報告できるのは、そのトークンが紐づくサイトの記事だけです。

記事のペイロード

正規の形式は1つだけで、バージョン管理に使うフィールドは 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	設定されている場合の正規URL
`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が返る前提で連携を実装してください。

この仕様は 追加のみです。既存フィールドの名称変更・型変更・削除は行いません。稼働中の連携がバージョン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.