К содержанию
SerpJet Документация Войти
Разделы
  1. Документация
  2. Публичный API доставки

Справочник публичных методов, параметров, схем и примеров

Публичный API доставки: pull новых статей и обновлений, result по доставке, исправление адреса публикации и CSV-фид Tilda. Все методы под /external/ с заголовком X-Api-Key.

Проверено
Содержание
  1. Методы
  2. Поля снимка статьи
  3. Пример ответа pull
  4. Тело result
  5. Исправление адреса

Базовый адрес — https://serpjet.ru/external/. Во всех запросах — заголовок X-Api-Key. Машиночитаемая схема — /external/openapi.json, интерактивная — /external/docs.

Методы

МетодНазначение
GET /external/articles/new/pull?project_id=&limit=Новые статьи, ещё не опубликованные.
POST /external/articles/new/{delivery_id}/resultРезультат по новой статье.
GET /external/articles/improvements/pull?project_id=&limit=Новые версии уже опубликованных статей.
POST /external/articles/improvements/{delivery_id}/resultРезультат по обновлению.
PATCH /external/articles/{article_id}/publication-urlИсправить адрес опубликованной статьи.
GET /external/tilda/feed.csv?project_id=&days=CSV для импорта в Tilda Потоки.

limit — по умолчанию 20, максимум 100.

Поля снимка статьи

ПолеОписание
delivery_idНомер этой версии для доставки. Используется в result.
project_id, article_idПроект и статья в SerpJet.
article_identityПостоянный идентификатор статьи serpjet:{project_id}:{article_id} — ключ записи в CMS.
predecessor_delivery_idПредыдущая версия, которую заменяет эта доставка, или null.
requires_stable_article_identitytrue, если доставку безопасно обрабатывать только по article_identity.
kindnew — новая статья, update — обновление опубликованной.
title, descriptionЗаголовок и описание страницы.
contentHTML статьи с иллюстрациями.
json_ldРазметка для поисковых систем.
coverОбложка {"url", "alt", "width", "height"} или null.
external_urlИзвестный адрес статьи (у обновлений) или пустая строка.
delivery_attempts, created_at, updated_atСлужебные данные доставки.

Пример ответа pull

{
  "ok": true,
  "items": [{
    "delivery_id": 15, "project_id": 7, "article_id": 421,
    "article_identity": "serpjet:7:421",
    "predecessor_delivery_id": null,
    "requires_stable_article_identity": false,
    "kind": "new",
    "title": "Как выбрать бетон для фундамента",
    "description": "Краткое описание статьи",
    "content": "<h2>…</h2><p>…</p>",
    "json_ld": {},
    "cover": {"url": "https://…/cover.webp", "alt": "Бетонный фундамент", "width": 1536, "height": 1024},
    "external_url": "", "delivery_attempts": 1,
    "created_at": "2026-03-08T12:00:00+00:00", "updated_at": "2026-03-08T12:00:00+00:00"
  }],
  "count": 1
}

Тело result

{"status": "accepted", "external_url": "https://site.example.com/blog/slug", "note": "необязательно"}

status — accepted или rejected. Ответ: {"ok": true, "delivery_id": 15, "status": "accepted", "article_status": "publish", "external_url": "…"}.

Исправление адреса

PATCH /external/articles/421/publication-url
{"external_url": "https://site.example.com/blog/new-alias",
 "expected_external_url": "https://site.example.com/node/421"}

Нужен ID статьи, а не доставки. Работает только для статьи с подтверждённой публикацией. Адрес — постоянный HTTP(S) на домене проекта, без логина и пароля, параметров запроса и якоря. expected_external_url защищает от перезаписи более свежего исправления.

Ошибки — Ошибки 401 / 404 / 409 / 429, superseded и пустая очередь.

Не нашли ответ? Напишите в поддержку из панели — укажите проект и что вы видите на экране.