Publish API

RankBloom пишет SEO-статьи для сайтов, которые вы к нему подключаете. Publish API — это способ, которым готовый материал уходит из RankBloom туда, куда нужно вам: на сайт WordPress, в CMS, на платформу автоматизации или в ваш собственный код.

Это тот же API, на котором работают официальный плагин WordPress и интеграции с Zapier и Make.

Базовый 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

Принимаются три варианта: shared- и managed-хостинги регулярно вырезают 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, а не отсутствующие ключи.

Контракт только дополняется. Поля никогда не переименовываются, не меняют тип и не удаляются: работающие интеграции продолжают бесконечно запрашивать версию 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.