Документация API

PromART API

Аналитика видимости в ИИ‑поиске (GEO), правки с проверкой фактов и, по желанию, доставка через API.

PromART измеряет, как ИИ‑ассистенты говорят о вашем бизнесе (сейчас реальные замеры проводятся в ChatGPT, Gemini и Claude; поддержка других ИИ‑систем в разработке, см. GET /v1/engines), объясняет, почему так происходит, и готовит правки с проверкой фактов. Главный продукт — панель аналитики: видимость, доля голоса, позиция, тональность, цитируемые источники, конкуренты, динамика, полные тексты ответов, рекомендации и отчёты в PDF. Панель работает через те же методы, что описаны здесь.

Руководство

Авторизация

Для каждого вызова /v1 (кроме публичных, отмеченных Без авторизации) нужен Bearer‑токен. Токены бывают двух видов:

Токен Откуда берётся Что позволяет
sess_… сеанс панели POST /v1/sessions с API‑ключом рабочего пространства; сеанс действует 30 дней всё; работает на любом тарифе
sk_live_… API‑ключ показывается один раз при создании рабочего пространства всё, но только на тарифах с доступом к API (optimize, agency, agency_client, enterprise); на остальных тарифах ответ — 403 api_access_required
Authorization: Bearer sk_live_…

Лимиты запросов зависят от тарифа; ответ 429 содержит заголовок Retry-After. В POST‑запросах можно передавать заголовок Idempotency-Key: если ключ уже использовался, сервер повторно вернёт ответ на первый запрос (Idempotent-Replayed: true).

Замеры и аналитика

Методы замеров (/v1/runs, /v1/answers, /v1/visibility, /v1/share-of-voice, /v1/citations) и аналитики (/v1/overview, /v1/trends, /v1/competitors, /v1/sources, /v1/prompt-metrics, /v1/report, /v1/report.pdf) принимают одни и те же фильтры: brand_id, engine, language, from, to (YYYY-MM-DD, включительно). Аналитика сравнивает выбранный период (по умолчанию — последние 28 дней) с предыдущим периодом той же длительности. Недели начинаются с понедельника.

Правки: применение вручную через панель

Каждая подготовленная правка (GET /v1/content/items) содержит placement (URL, место на странице, пронумерованные шаги, текущий текст, который она заменяет, и все части, готовые к копированию) и facts (подтверждённые факты, на основе которых она написана). Порядок работы без дополнения «Доставка через API»:

  1. proposed → POST /v1/content/{id}/approve → approved (готова к применению).
  2. Клиент вставляет правку на сайт и вызывает POST /v1/content/{id}/applied → live; начинается эксперимент (когда ИИ‑системы успеют заметить изменение, проводится повторный замер, затем правку оставляют или откатывают). Для новых страниц вместо этого вызывают POST /v1/pages/{id}/published с фактическим URL.
  3. Если эксперимент не показал прироста (или клиент откатил правку), правка переходит в статус remove_requested, и в ней указан текст, который нужно убрать; POST /v1/content/{id}/removed → rolled_back.

Правки в Google Business Profile на любом тарифе остаются автоматическими: после одобрения gbp_profile / gbp_post PromART сам записывает их в Google (флаг функции google_bp).

Доставка через API (платное дополнение)

С дополнением «Доставка через API» (api_delivery_enabled у рабочего пространства, см. add_ons в GET /v1/usage) одобренная правка сайта сразу получает статус live, а сервер вашего сайта запрашивает её при рендеринге страницы. Без дополнения эти методы возвращают 403 addon_required:

Что Запрос Для чего
Правки для уже созданной страницы GET /v1/content?url=<page URL> метаописание, абзац с ответом, FAQ, структурированные данные JSON-LD и blocks[]
Только замены разделов GET /v1/pages/{url}/blocks (URL экранируется как сегмент пути) или GET /v1/pages/blocks?url= заменить или вставить отдельные разделы
Новые страницы, которые нужно создать GET /v1/pages/new одобренные страницы: предлагаемый URL, заголовок, разделы (с таблицами), структурированные данные, внутренние ссылки
Отметить, что новая страница на сайте POST /v1/pages/{id}/published сообщить PromART фактический URL, чтобы страница попала в замеры

Отдаются только правки, доставляемые через API (delivery: api): правки, которые клиент применил вручную, и так уже есть на странице. Кешируйте ответы не дольше 60 секунд (Cache-Control: private, max-age=60).

Применение блоков

Каждый блок имеет вид {block_id, selector, action, html, fact_ids, status}. Найдите в готовом HTML страницы первый элемент, который соответствует CSS‑селектору selector, и примените к нему действие из action:

action что сделать
replace заменить элемент целиком (outer HTML) на html
append вставить html последним дочерним элементом
prepend вставить html первым дочерним элементом
before вставить html сразу перед элементом
after вставить html сразу после элемента

Если селектор ничего не нашёл, пропустите блок. html уже очищен на стороне PromART: допускаются только p br h2 h3 h4 ul ol li strong em b i table thead tbody tr th td a (ссылки — только на ваши собственные хосты), без скриптов, стилей и любых атрибутов, кроме a[href].

Проверка подписи

Ответы GET /v1/content, GET /v1/pages/{url}/blocks, GET /v1/pages/blocks и GET /v1/pages/new содержат заголовок

X-Sachino-Signature: sha256=<hex HMAC-SHA256(signing_secret, exact response body bytes)>

signing_secret можно получить через GET /v1/me. Проверяйте подпись по сырым байтам тела до разбора JSON и сравнивайте подписи за постоянное время.

Node:

JavaScript
const crypto = require('crypto');
const ok = (raw, header, secret) => {
  const want = 'sha256=' + crypto.createHmac('sha256', secret).update(raw).digest('hex');
  return header && header.length === want.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(want));
};

PHP:

PHP
$want = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($want, $_SERVER['HTTP_X_SACHINO_SIGNATURE'] ?? $header);

Go:

Go
m := hmac.New(sha256.New, []byte(secret))
m.Write(raw)
ok := hmac.Equal([]byte(header), []byte("sha256="+hex.EncodeToString(m.Sum(nil))))

Резервный сценарий (обязательно)

PromART ни при каких условиях не должен ломать ваш сайт. Если запрос к API завершился ошибкой, превысил тайм-аут (рекомендуем 800 мс), вернул статус вне диапазона 2xx (в том числе 403 addon_required) или подпись не совпала, отдавайте исходную страницу без изменений. Не допускайте, чтобы PromART блокировал рендеринг страницы.

IndexNow

GET /v1/indexnow-key возвращает ключ IndexNow вашего рабочего пространства и указывает, какой файл ваш разработчик должен разместить на каждом домене: https://<domain>/<key>.txt — обычный текст, содержащий только ключ; файл должен отдаваться с кодом HTTP 200 без перенаправления. После каждого события content.published (правку опубликовали через API или отметили как применённую либо подтвердили публикацию новой страницы) PromART отправляет изменённые URL в IndexNow; каждая отправка и её результат видны в GET /v1/actions (канал bing). Как только файл станет доступен, проверка сайта indexnow_key получит статус ok.

Вебхуки

Чтобы подписаться, вызовите POST /v1/webhooks. События: run.completed, visibility.changed, content.proposed, content.approved, content.published, content.removal_requested, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request (или * — все события).

Каждое уведомление — это запрос POST с JSON‑телом {id, type, created_at, data} и заголовками X-Sachino-Event: <type> и X-Sachino-Signature: sha256=<hex HMAC-SHA256(webhook secret, body)> (секрет возвращается при создании вебхука). Если ваш сервер ответил кодом вне диапазона 2xx, уведомление отправляется повторно, до 3 раз.

Интеграции с аккаунтами и флаги функций

Google Business Profile (google_bp, область доступа business.manage), Search Console (gsc) и GA4 (ga4, analytics.readonly) подключаются через Google OAuth; токены хранятся в зашифрованном виде. Для Cloudflare (cloudflare) нужно вставить API‑токен с правами на настройки ботов зоны; эта интеграция используется только для того, чтобы открыть доступ ИИ‑краулерам. cloudflare и google_bp включаются флагами функций на сервере: если флаг выключен, связанные методы возвращают 403 с кодом feature_disabled, а GET /v1/integrations возвращает этот тип интеграции с enabled: false.

Ошибки

Все ошибки приходят в едином формате: {"error": {"code": "...", "message": "..."}}. Коды: unauthorized (401), plan_limit (402), api_access_required (403: API‑ключ на тарифе без доступа к API; панель работает через сеансы и доступна на любом тарифе), addon_required (403: дополнение «Доставка через API» не подключено), feature_disabled (403), not_found (404), invalid_request / invalid_json (400), rate_limited (429), internal (500). Обрабатывайте ошибки по code: он задаёт общую категорию и не меняется. На запрос к несуществующему пути в /v1 сервер тоже отвечает 404 с кодом not_found в том же формате, а на запрос с методом, который путь в /v1 не поддерживает, — 405 с кодом invalid_request и заголовком Allow.

Если у ошибки есть более конкретная причина, в ней также передаются reason (стабильный ключ сообщения, например http.err.brand_id_required или core.err.not_found.brand) и params (значения, подставленные в сообщение; если значений нет, поле не передаётся). Если параметр что-то называет (тариф, статус, ИИ‑систему), в нём передаётся код, как и в английских сообщениях. У таких ошибок message приходит на языке ответа (см. раздел «Язык ответов»); на английском это тот же текст, что и до появления reason.

JSON
{"error": {"code": "api_access_required",
           "message": "plan monitor does not include API access; use the panel, or upgrade to Optimize or higher",
           "reason": "http.err.api_access_required", "params": {"plan": "monitor"}}}

Язык ответов

Тексты, которые пишет PromART (сообщения об ошибках, примечания, рекомендации, шаги по размещению, оповещения, страница приглашения), могут приходить на грузинском, русском или английском. Язык задаётся параметром запроса lang (ka, ru или en, в любом методе) или заголовком Accept-Language (берётся поддерживаемый язык с наибольшим значением q; lang имеет приоритет). Если не передан ни параметр, ни заголовок или в заголовке только неподдерживаемые языки, ответы приходят на английском, как и раньше. Каждый ответ сообщает свой язык в заголовке Content-Language, который могут читать браузеры (Access-Control-Expose-Headers), и содержит Vary: Accept-Language. Исключение — ответы, одинаковые на всех языках: содержимое сайта из GET /v1/content и GET /v1/pages/{url}/blocks, /healthz, шрифты и файлы страницы документации приходят без этих заголовков. /docs тоже открывается на запрошенном языке (грузинском, русском или английском, с Vary: Accept-Language); /openapi.yaml доступен только на английском и отдаётся с Content-Language: en без Vary. Ответ на POST‑запрос, повторённый с тем же Idempotency-Key, приходит на языке первого запроса и с тем же Content-Language. Коды, идентификаторы и ваши собственные данные (названия брендов, факты, промпты, ответы ИИ, сгенерированное содержимое сайта) никогда не переводятся.

Параметры всех методов

Все методы /v1 и страницы приглашений принимают эти два параметра: они задают язык текстов, которые пишет PromART. У каждого метода ниже они показаны одной строкой.

ПараметрТип и описание
langquerystring
Язык текстов, которые PromART добавляет в ответ (сообщения об ошибках, примечания, рекомендации, шаги по размещению, оповещения, страница приглашения): ka — грузинский, ru — русский, en — английский. Имеет приоритет над Accept-Language; любое другое значение игнорируется. Коды, идентификаторы и ваши собственные данные никогда не переводятся. Подробнее — в разделе руководства «Язык ответов».

Допустимые значения: ka, ru, en

Accept-Languageheaderstring
Используется, если lang не передан: выбирается поддерживаемый язык (ka, ru, en) с наибольшим значением q (при равенстве — первый); если такого нет, ответ приходит на английском.

Аналитика

Ключевые показатели и их изменения, динамика по неделям, конкуренты, источники, результаты по промптам, отчёт в PDF.

Ключевые показатели за период и за предыдущий период той же длительности

GET/v1/overview

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Период по умолчанию — последние 28 дней. Видимость, доля голоса, средняя позиция (чем меньше, тем лучше) и тональность клиента.

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Overview

    • from string date
    • to string date
    • prev_from string date
    • prev_to string date
    • current KPI
    • previous KPI

Клиент и все бренды, названные ИИ‑системами, со значениями за предыдущий период

GET/v1/competitors

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json CompetitorRow[]

    • name string
    • is_client boolean
    • mentions integer
    • visibility_pct number
    • sov_pct number
    • avg_position number
    • avg_sentiment number
    • prev_visibility_pct number
    • prev_sov_pct number

Источники, цитируемые ИИ‑системами, по доменам или URL, с разбивкой по системам

GET/v1/sources

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
byquerystring

Допустимые значения: domain, urlПо умолчанию: domain

limitqueryinteger

По умолчанию: 100Не более 1000

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json SourceRow[]

    • url string
      Только при by=url
    • domain string
    • owner string

      Допустимые значения: client, competitor, third_party

    • count integer
      Число ответов, цитирующих источник
    • share_pct number
    • engines map<string, integer>

Видимость и позиция по каждому промпту, в целом и по ИИ‑системам (по возрастанию видимости)

GET/v1/prompt-metrics

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json PromptRow[]

    • prompt_id string
    • text string
    • language string
    • target_url string
    • answers integer
    • visibility_pct number
    • avg_position number
    • top_competitor string
    • engines map<string, EngineCell>

Отчёт в PDF по бренду за период

GET/v1/report.pdf

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Ключевые показатели и их изменения, график видимости по неделям (12 недель), конкуренты, ИИ‑системы, цитируемые источники, правки и эксперименты, рекомендации. Период по умолчанию — последние 28 дней. Подписи, числа и даты — на языке ответа (lang, иначе Accept-Language, иначе английский; см. раздел «Язык ответов»); названия брендов, домены и URL остаются как есть.

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
enginequerystring
languagequerystring
Только ответы на этом языке (фильтр данных, а не язык PDF)
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 PDF (вложение) с именем sachino-<domain>-<to>.pdf

    application/pdf string binary

  • 400 Ошибка

    application/json Error

  • 404 Ошибка

    application/json Error

Доставка через API

Платное дополнение «Доставка через API»: методы, которые сервер сайта клиента вызывает при рендеринге страниц.

Опубликованные правки для одной страницы (с подписью; доставка через API)

GET/v1/content

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Платное дополнение «Доставка через API»; без него ответ — 403 addon_required. Возвращает правки, доставляемые через API (delivery: api). Вызывайте при рендеринге страницы. Проверяйте X-Sachino-Signature и отдавайте исходную страницу при любой ошибке, тайм-ауте (рекомендуем 800 мс), статусе вне диапазона 2xx или несовпадении подписи.

Параметры

ПараметрТип и описание
urlqueryОбязательноstring uri
URL страницы (PromART нормализует его)
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Правки для страницы

    Заголовки

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret из GET /v1/me, точные байты тела ответа))
    • Cache-Control string

    application/json Delivery

    • url string
    • version integer
      Увеличивается с каждой опубликованной правкой для этого URL
    • meta_description string
    • answer_block string
    • faq object[]
      Поля: 3
      • q string
      • a string
      • fact_ids string[]
    • schema object
      Структурированные данные JSON-LD
    • blocks BlockItem[]
    • content_ids string[]
    • signature string
      Устаревшее поле: HMAC тела ответа без этого поля. Вместо него проверяйте заголовок X-Sachino-Signature.
  • 400 Ошибка

    application/json Error

  • 401 Ошибка

    application/json Error

  • 403 addon_required: в этом рабочем пространстве не подключено дополнение «Доставка через API»

    application/json Error

Блоки разделов страницы по параметру url (с подписью; доставка через API)

GET/v1/pages/blocks

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Платное дополнение «Доставка через API»; без него ответ — 403 addon_required. Со статусом live возвращаются только блоки, доставляемые через API.

Параметры

ПараметрТип и описание
urlqueryОбязательноstring uri
statusquerystring
По умолчанию — только блоки со статусом live; all добавляет предложенные и прежние

Допустимые значения: all

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Блоки

    Заголовки

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret из GET /v1/me, точные байты тела ответа))

    application/json BlockItem[]

    • content_id string
    • block_id string
    • selector string
    • action string

      Допустимые значения: replace, append, prepend, before, after

    • html string
    • fact_ids string[]
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

  • 400 Ошибка

    application/json Error

  • 403 addon_required: в этом рабочем пространстве не подключено дополнение «Доставка через API»

    application/json Error

Блоки разделов страницы (с подписью; доставка через API)

GET/v1/pages/{url}/blocks

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Текст для замены отдельных разделов существующей страницы. url — URL страницы, экранированный для использования в пути (encodeURIComponent). Платное дополнение «Доставка через API»; без него ответ — 403 addon_required.

Параметры

ПараметрТип и описание
urlpathОбязательноstring

Пример: https%3A%2F%2Fexample.com%2Fservices

statusquerystring
По умолчанию — только блоки со статусом live; all добавляет предложенные и прежние

Допустимые значения: all

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Блоки

    Заголовки

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret из GET /v1/me, точные байты тела ответа))

    application/json BlockItem[]

    • content_id string
    • block_id string
    • selector string
    • action string

      Допустимые значения: replace, append, prepend, before, after

    • html string
    • fact_ids string[]
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

  • 400 Ошибка

    application/json Error

  • 403 addon_required: в этом рабочем пространстве не подключено дополнение «Доставка через API»

    application/json Error

Новые страницы, которые нужно создать (с подписью; доставка через API)

GET/v1/pages/new

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Одобренные страницы с предлагаемым URL, заголовком, разделами (HTML, в том числе таблицы), структурированными данными JSON-LD и внутренними ссылками. Создайте страницу, затем подтвердите публикацию через POST /v1/pages/{id}/published. Платное дополнение «Доставка через API»; без него ответ — 403 addon_required (в панели новые страницы видны в GET /v1/content/items?kind=page).

Параметры

ПараметрТип и описание
brand_idquerystring
statusquerystring
По умолчанию — approved и live

Допустимые значения: approved, live, proposed

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Страницы (правки типа page; см. body.page)

    Заголовки

    • X-Sachino-Signature string
      sha256= + hex(HMAC-SHA256(signing_secret из GET /v1/me, точные байты тела ответа))

    application/json Content[]

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 403 addon_required: в этом рабочем пространстве не подключено дополнение «Доставка через API»

    application/json Error

Подтвердить URL опубликованной новой страницы

POST/v1/pages/{id}/published

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Переводит страницу в статус live, делает её целевым URL для подходящих промптов, записывает действие в журнал, отправляет событие content.published, передаёт URL в IndexNow и начинает эксперимент, чтобы замерить эффект.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • url string uri
    Фактический URL на домене бренда; по умолчанию — предложенный URL

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

Страницы

Предложить новые страницы для услуг, которых нет на сайте

POST/v1/pages/generate

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • max integer

    По умолчанию: 3Не более 10

Ответы

  • 201 Предложенные страницы

    application/json Content[]

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка

Проверки сайта

Аудит доступности сайта для ИИ‑систем с инструкциями для разработчика

GET/v1/site-checks

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Индексация (через Search Console, если она подключена), доступ ИИ‑краулеров в robots.txt и на уровне CDN, карта сайта, файл ключа IndexNow, загрузка страницы, noindex, текст, видимый без JavaScript, скорость. Сайт сканируется заново, если результаты старше 1 часа или передан параметр refresh.

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
refreshquerystring

Допустимые значения: 1, true

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json SiteCheck[]

    • id string
    • check string

      Допустимые значения: robots_ai_bots, cdn_ai_bots, sitemap, indexnow_key, fetch, noindex, js_rendering, speed, google_index

    • target string
      Домен или URL
    • status string

      Допустимые значения: ok, warn, fail, unknown

    • detail string
    • instruction string
      Конкретная задача для клиента или разработчика
    • fix string
      Автоисправление, которое может выполнить PromART, например cloudflare:allow_ai_crawlers
    • source string

      Допустимые значения: crawl, gsc, cloudflare

    • checked_at string date-time

Ключ IndexNow рабочего пространства и инструкции по размещению файла

GET/v1/indexnow-key

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json IndexNowInfo

    • key string
    • files object[]
      Поля: 5
      • brand_id string
      • domain string
      • url string
        Адрес файла: https://<domain>/<key>.txt
      • content string
        Точное содержимое файла (сам ключ)
      • status string
        По результатам последней проверки сайта

        Допустимые значения: ok, fail, unknown

    • instructions string[]

Интеграции

Подключения, доступные типы интеграций и тексты для клиента

GET/v1/integrations

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object

    • items Integration[]
      Поля: 12
      • id string
      • brand_id string
      • kind string

        Допустимые значения: google_bp, gsc, ga4, cloudflare

      • status string

        Допустимые значения: invited, pending, connected, needs_selection, error, revoked

      • account string
      • scopes string
      • config map<string, string>
      • invite_email string
      • last_sync_at string date-time
      • last_error string
      • created_at string date-time
      • updated_at string date-time
    • kinds map<string, IntegrationKind>
      Поля: 4
      • scope string
        Область доступа Google OAuth
      • access string
      • does string
      • enabled boolean
        false, если на сервере выключен флаг функции
    • wording map<string, object>
      Тексты для клиента на каждом языке (en, ka, ru)
      Поля: 4
      • connect string
      • invite string
      • button string
      • review string

Начать подключение

POST/v1/integrations/{kind}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Для интеграций Google возвращается auth_url (откройте его в браузере). Для Cloudflare передайте token. Если вместо этого указать invite_email, создаётся одноразовая ссылка для того, кто управляет аккаунтом (её доставляет вебхук integration.invited). cloudflare и google_bp возвращают 403 feature_disabled, если их флаг выключен.

Параметры

ПараметрТип и описание
kindpathОбязательноstring

Допустимые значения: google_bp, gsc, ga4, cloudflare

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • token string
    API‑токен Cloudflare (Zone > Bot Management > Edit)
  • invite_email string email

Ответы

  • 201 Подключение начато

    application/json ConnectResult

    • integration Integration
    • auth_url string
      Экран согласия Google
    • invite_url string
      Одноразовая ссылка для того, кто управляет аккаунтом
    • note string
  • 400 Ошибка

    application/json Error

  • 403 Ошибка

    application/json Error

Выбрать местоположение, сайт или ресурс (статус needs_selection)

PATCH/v1/integrations/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • config map<string, string>

Ответы

  • 200 OK

    application/json Integration

    • id string
    • brand_id string
    • kind string

      Допустимые значения: google_bp, gsc, ga4, cloudflare

    • status string

      Допустимые значения: invited, pending, connected, needs_selection, error, revoked

    • account string
    • scopes string
    • config map<string, string>
    • invite_email string
    • last_sync_at string date-time
    • last_error string
    • created_at string date-time
    • updated_at string date-time

Отключить (с отзывом токенов Google)

DELETE/v1/integrations/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 204 Доступ отозван

Синхронизировать аккаунт сейчас

POST/v1/integrations/{id}/sync

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Integration

    • id string
    • brand_id string
    • kind string

      Допустимые значения: google_bp, gsc, ga4, cloudflare

    • status string

      Допустимые значения: invited, pending, connected, needs_selection, error, revoked

    • account string
    • scopes string
    • config map<string, string>
    • invite_email string
    • last_sync_at string date-time
    • last_error string
    • created_at string date-time
    • updated_at string date-time
  • 403 Ошибка

    application/json Error

Выполнить действие в Cloudflare

POST/v1/integrations/{id}/actions

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Единственное действие — allow_ai_crawlers (выключает Block AI bots; его можно отменить в журнале действий). Требуется флаг cloudflare.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • action string Обязательно

    Допустимые значения: allow_ai_crawlers

Ответы

  • 201 Запись в журнале действий

    application/json Action

    • id string
    • brand_id string
    • channel string

      Допустимые значения: site, gbp, gsc, bing, cloudflare, reviews

    • kind string
    • target string
    • summary string
    • content_id string
    • integration_id string
    • before any
      Прежнее значение (если известно)
    • after any
      Новое значение
    • status string

      Допустимые значения: done, failed, rolled_back

    • error string
    • rollback_url string
      Отправьте сюда POST, чтобы отменить действие (только для обратимых действий)
    • created_at string date-time
    • rolled_back_at string date-time
  • 400 Ошибка

    application/json Error

  • 403 Ошибка

    application/json Error

Подготовить текст для Business Profile по подтверждённым фактам

POST/v1/gbp/profile

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Нужны флаг google_bp и подключённый Business Profile.

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно

Ответы

  • 201 Предложенные правки

    application/json Content[]

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 403 Ошибка

    application/json Error

Переходы из ИИ‑систем (GA4, последние 28 дней)

GET/v1/ai-traffic

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json TrafficRow[]

    • source string
    • sessions integer
    • from string date
    • to string date

Журнал действий

Все изменения, внесённые PromART, во всех каналах и аккаунтах

GET/v1/actions

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
channelquerystring

Допустимые значения: site, gbp, gsc, bing, cloudflare, reviews

limitqueryinteger

По умолчанию: 100Не более 1000

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Action[]

    • id string
    • brand_id string
    • channel string

      Допустимые значения: site, gbp, gsc, bing, cloudflare, reviews

    • kind string
    • target string
    • summary string
    • content_id string
    • integration_id string
    • before any
      Прежнее значение (если известно)
    • after any
      Новое значение
    • status string

      Допустимые значения: done, failed, rolled_back

    • error string
    • rollback_url string
      Отправьте сюда POST, чтобы отменить действие (только для обратимых действий)
    • created_at string date-time
    • rolled_back_at string date-time

Отменить обратимое действие

POST/v1/actions/{id}/rollback

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Action

    • id string
    • brand_id string
    • channel string

      Допустимые значения: site, gbp, gsc, bing, cloudflare, reviews

    • kind string
    • target string
    • summary string
    • content_id string
    • integration_id string
    • before any
      Прежнее значение (если известно)
    • after any
      Новое значение
    • status string

      Допустимые значения: done, failed, rolled_back

    • error string
    • rollback_url string
      Отправьте сюда POST, чтобы отменить действие (только для обратимых действий)
    • created_at string date-time
    • rolled_back_at string date-time
  • 400 Ошибка

    application/json Error

Рабочее пространство

Выйти (удалить текущий сеанс)

DELETE/v1/sessions

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 204 Выход выполнен
  • 401 Ошибка

    application/json Error

Текущее рабочее пространство, тариф и секрет для подписи

GET/v1/me

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object

    • workspace Workspace
      Поля: 8
      • id string
      • name string
      • plan string
      • parent_id string
      • auto_publish_technical boolean
        Автоматически публиковать технические правки (нужно дополнение «Доставка через API»)
      • api_delivery_enabled boolean
        Платное дополнение «Доставка через API»
      • auto_fixes boolean
        Правки готовятся автоматически после каждой диагностики. Выключено — только аналитика, правки по запросу.
      • created_at string date-time
    • plan Plan
      Поля: 16
      • name string
      • price_gel integer
      • prompts integer
      • engines integer
      • brands integer
      • competitors integer
      • languages integer
      • answers_per_month integer
      • interval string
      • daily_prompts integer
      • diagnosis boolean
      • autopilot boolean
      • child_workspaces integer
      • overage string

        Допустимые значения: block, bill

      • rate_limit_rps number
      • api_access boolean
        API‑ключи могут обращаться к API (панель работает на любом тарифе)
    • signing_secret string
      Ключ для проверки заголовка X-Sachino-Signature в ответах методов доставки
  • 401 Ошибка

    application/json Error

Изменить настройки рабочего пространства

PATCH/v1/settings

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • auto_publish_technical boolean
    Публиковать технические правки (структурированные данные, метатеги) и изменения доступа ИИ‑краулеров в Cloudflare без одобрения
  • auto_fixes boolean
    Автоматически готовить правки после каждой диагностики (тарифы с Autopilot). Выключено (по умолчанию) — только аналитика: правки готовятся, когда вы вызываете POST /v1/fixes. Включение без Autopilot возвращает 402 plan_limit.

Ответы

  • 200 Рабочее пространство

    application/json Workspace

    • id string
    • name string
    • plan string
    • parent_id string
    • auto_publish_technical boolean
      Автоматически публиковать технические правки (нужно дополнение «Доставка через API»)
    • api_delivery_enabled boolean
      Платное дополнение «Доставка через API»
    • auto_fixes boolean
      Правки готовятся автоматически после каждой диагностики. Выключено — только аналитика, правки по запросу.
    • created_at string date-time

Рабочие пространства клиентов этого агентства

GET/v1/workspaces

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Workspace[]

    • id string
    • name string
    • plan string
    • parent_id string
    • auto_publish_technical boolean
      Автоматически публиковать технические правки (нужно дополнение «Доставка через API»)
    • api_delivery_enabled boolean
      Платное дополнение «Доставка через API»
    • auto_fixes boolean
      Правки готовятся автоматически после каждой диагностики. Выключено — только аналитика, правки по запросу.
    • created_at string date-time

Создать рабочее пространство клиента (тарифы для агентств)

POST/v1/workspaces

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • name string Обязательно

Ответы

  • 201 Рабочее пространство создано. Сохраните API‑ключ сейчас: он больше не будет показан

    application/json object

    • workspace Workspace
    • api_key string
    • note string
  • 402 Ошибка

    application/json Error

ИИ‑системы и маршруты запросов к ним

GET/v1/engines

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object[]

    • name string
    • phase string

      Допустимые значения: mvp, phase2, phase3

    • routes string[]
      Настроенные маршруты по порядку (первый — основной, остальные — резервные); ответы через mock симулируются
    • live boolean
      Для этой ИИ‑системы есть адаптер реального провайдера (chatgpt через openai, gemini через gemini, claude через anthropic). Реальные ответы приходят, только если в routes этот провайдер стоит первым

Использование лимитов тарифа в этом месяце и дополнения

GET/v1/usage

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Usage

    • plan Plan
    • month string
    • answers integer
    • queued_jobs integer
    • prompts integer
    • brands integer
    • overage_answers integer
    • child_workspaces integer
    • add_ons object[]
      Поля: 4
      • name string
      • title string
      • description string
      • enabled boolean

Каталог

Бренды, факты и промпты.

Список брендов

GET/v1/brands

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Brand[]

    • id string Только для чтения
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Другие варианты написания (например на грузинском или русском)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

      Допустимые значения: api, gbp

    • created_at string date-time Только для чтения

Создать бренд

POST/v1/brands

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json Brand

  • name string
  • domain string
  • industry string
  • city string
  • variants string[]
    Другие варианты написания (например на грузинском или русском)
  • competitors Competitor[]
  • languages string[]
  • markets string[]
  • engines string[]
  • channel string
    api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

    Допустимые значения: api, gbp

Ответы

  • 201 Бренд создан

    application/json Brand

    • id string Только для чтения
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Другие варианты написания (например на грузинском или русском)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

      Допустимые значения: api, gbp

    • created_at string date-time Только для чтения
  • 400 Ошибка

    application/json Error

  • 402 Ошибка

    application/json Error

Получить бренд

GET/v1/brands/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Brand

    • id string Только для чтения
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Другие варианты написания (например на грузинском или русском)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

      Допустимые значения: api, gbp

    • created_at string date-time Только для чтения
  • 404 Ошибка

    application/json Error

Изменить бренд (поля, переданные в теле, перезаписываются)

PATCH/v1/brands/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json Brand

  • name string
  • domain string
  • industry string
  • city string
  • variants string[]
    Другие варианты написания (например на грузинском или русском)
  • competitors Competitor[]
  • languages string[]
  • markets string[]
  • engines string[]
  • channel string
    api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

    Допустимые значения: api, gbp

Ответы

  • 200 OK

    application/json Brand

    • id string Только для чтения
    • name string
    • domain string
    • industry string
    • city string
    • variants string[]
      Другие варианты написания (например на грузинском или русском)
    • competitors Competitor[]
    • languages string[]
    • markets string[]
    • engines string[]
    • channel string
      api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

      Допустимые значения: api, gbp

    • created_at string date-time Только для чтения
  • 400 Ошибка

    application/json Error

Список фактов

GET/v1/facts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
statusquerystring

Допустимые значения: confirmed, unconfirmed

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Fact[]

    • id string Только для чтения
    • brand_id string
    • key string
    • value string
    • lang string
      Код языка или any
    • url string
    • source string

      Допустимые значения: api, form, extracted

    • status string

      Допустимые значения: confirmed, unconfirmed

    • updated_at string date-time Только для чтения

Добавить факты (один объект или массив)

POST/v1/facts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Факты — единственный источник, на котором PromART основывает тексты; каждое сгенерированное предложение ссылается на ID фактов.

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json одно из

  1. Вариант 1 Fact

    • brand_id string
    • key string
    • value string
    • lang string
      Код языка или any
    • url string
    • source string

      Допустимые значения: api, form, extracted

    • status string

      Допустимые значения: confirmed, unconfirmed

  2. Вариант 2 Fact[]

    • brand_id string
    • key string
    • value string
    • lang string
      Код языка или any
    • url string
    • source string

      Допустимые значения: api, form, extracted

    • status string

      Допустимые значения: confirmed, unconfirmed

Ответы

  • 201 Факты добавлены

    application/json Fact[]

    • id string Только для чтения
    • brand_id string
    • key string
    • value string
    • lang string
      Код языка или any
    • url string
    • source string

      Допустимые значения: api, form, extracted

    • status string

      Допустимые значения: confirmed, unconfirmed

    • updated_at string date-time Только для чтения
  • 400 Ошибка

    application/json Error

Изменить или подтвердить факт

PATCH/v1/facts/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Если значение изменилось, все правки, в которых используется этот факт, помечаются как устаревшие и ставятся в очередь на повторную генерацию.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • key string
  • value string
  • lang string
  • url string
  • status string

    Допустимые значения: confirmed

Ответы

  • 200 OK

    application/json Fact

    • id string Только для чтения
    • brand_id string
    • key string
    • value string
    • lang string
      Код языка или any
    • url string
    • source string

      Допустимые значения: api, form, extracted

    • status string

      Допустимые значения: confirmed, unconfirmed

    • updated_at string date-time Только для чтения
  • 404 Ошибка

    application/json Error

Удалить факт

DELETE/v1/facts/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Удалено

    application/json object

    • deleted boolean
  • 404 Ошибка

    application/json Error

Извлечь неподтверждённые факты со страницы

POST/v1/facts/extract

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • url string Обязательно

Ответы

  • 201 Извлечённые факты (статус unconfirmed)

    application/json Fact[]

    • id string Только для чтения
    • brand_id string
    • key string
    • value string
    • lang string
      Код языка или any
    • url string
    • source string

      Допустимые значения: api, form, extracted

    • status string

      Допустимые значения: confirmed, unconfirmed

    • updated_at string date-time Только для чтения

Список промптов

GET/v1/prompts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
activequerystring
Только активные промпты

Допустимые значения: true

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Prompt[]

    • id string Только для чтения
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Только для чтения

Добавить промпты (массив или {"prompts":[...]})

POST/v1/prompts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json одно из

  1. Вариант 1 Prompt[]

    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
  2. Вариант 2 object

    • prompts Prompt[]
      Поля: 6
      • brand_id string
      • text string
      • language string
      • market string
      • target_url string
      • active boolean

Ответы

  • 201 Промпты добавлены

    application/json Prompt[]

    • id string Только для чтения
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Только для чтения
  • 400 Ошибка

    application/json Error

  • 402 Ошибка

    application/json Error

Изменить промпт

PATCH/v1/prompts/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • active boolean
  • target_url string
  • text string

Ответы

  • 200 OK

    application/json Prompt

    • id string Только для чтения
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Только для чтения

Удалить промпт

DELETE/v1/prompts/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Удалено

    application/json object

    • deleted boolean

Предложить промпты для бренда (без сохранения)

POST/v1/prompts/suggest

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • per_language integer

Ответы

  • 200 OK

    application/json Prompt[]

    • id string Только для чтения
    • brand_id string
    • text string
    • language string
    • market string
    • target_url string
    • active boolean
    • created_at string date-time Только для чтения

Замеры

Список замеров

GET/v1/runs

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
limitqueryinteger

По умолчанию: 50Не более 500

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Run[]

    • id string
    • brand_id string
    • kind string

      Допустимые значения: baseline, scheduled, daily, manual, remeasure

    • status string
    • repeats integer
    • engines string[]
    • jobs_total integer
    • jobs_done integer
    • jobs_failed integer
    • created_at string date-time
    • finished_at string date-time

Запустить замер

POST/v1/runs

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Разворачивает сочетания «промпт × ИИ‑система × (язык, регион) × повторы» в задачи и ставит их в очередь.

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • engines string[]
  • repeats integer
  • prompt_ids string[]
    Необязательно: только эти промпты

Ответы

  • 201 Замер создан

    application/json Run

    • id string
    • brand_id string
    • kind string

      Допустимые значения: baseline, scheduled, daily, manual, remeasure

    • status string
    • repeats integer
    • engines string[]
    • jobs_total integer
    • jobs_done integer
    • jobs_failed integer
    • created_at string date-time
    • finished_at string date-time
  • 402 Ошибка

    application/json Error

Получить замер

GET/v1/runs/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Run

    • id string
    • brand_id string
    • kind string

      Допустимые значения: baseline, scheduled, daily, manual, remeasure

    • status string
    • repeats integer
    • engines string[]
    • jobs_total integer
    • jobs_done integer
    • jobs_failed integer
    • created_at string date-time
    • finished_at string date-time
  • 404 Ошибка

    application/json Error

Просмотр ответов (с фильтрами, сначала новые)

GET/v1/answers

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
run_idquerystring
prompt_idquerystring
mentionedquerystring
Только ответы, где клиент назван / не назван

Допустимые значения: yes, no

qquerystring
Поиск по тексту ответа без учёта регистра
limitqueryinteger

По умолчанию: 50Не более 500

offsetqueryinteger

По умолчанию: 0

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object

    • items Answer[]
      Поля: 13
      • id string
      • run_id string
      • prompt_id string
      • prompt string
      • engine string
      • language string
      • location string
      • route string
      • text string
      • citations string[]
      • screenshot_url string
        Зарезервировано: пока ни один адаптер ИИ‑систем не делает скриншоты, поэтому в ответах этого поля нет
      • mentions object[]
        Поля: 5
        • name string
        • is_client boolean
        • position integer
          1 = назван первым
        • sentiment number

          От −1 до 1

        • cited_urls string[]
      • created_at string date-time
    • total integer

Видимость по неделям, ИИ‑системам и языкам

GET/v1/visibility

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object

    • overall VisRow
      Поля: 8
      • week string
      • engine string
      • language string
      • answers integer
      • mentioned integer
      • visibility_pct number
      • avg_position number
      • avg_sentiment number
    • rows VisRow[]
      Поля: 8
      • week string
      • engine string
      • language string
      • answers integer
      • mentioned integer
      • visibility_pct number
      • avg_position number
      • avg_sentiment number

Доля голоса в сравнении с конкурентами

GET/v1/share-of-voice

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json SOVRow[]

    • name string
    • is_client boolean
    • mentions integer
    • share_pct number
    • avg_position number
    • avg_sentiment number

Домены, цитируемые ИИ‑системами

GET/v1/citations

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
enginequerystring
languagequerystring
fromquerystring date
toquerystring date
Включительно
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json CitationRow[]

    • domain string
    • count integer
    • share_pct number
    • owner string

      Допустимые значения: client, competitor, third_party

Последние оповещения

GET/v1/alerts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object[]

    • id string
    • brand_id string
    • engine string
    • message string
    • created_at string date-time

Еженедельный отчёт по бренду

GET/v1/report

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Report

    • brand Brand
    • period string
      from – to в виде текста
    • from string date
      Первый день недели отчёта
    • to string date
      Последний день недели отчёта (сегодня, по UTC)
    • visibility_pct number
    • visibility_prev_pct number
    • delta_pp number
    • by_engine VisRow[]
    • share_of_voice SOVRow[]
    • top_citations CitationRow[]
    • live_changes integer
    • pending_approval integer
    • experiments Experiment[]
    • recommendations Recommendation[]
    • alerts string[]
    • ai_traffic TrafficRow[]
    • recent_actions Action[]
    • failing_site_checks SiteCheck[]
  • 404 Ошибка

    application/json Error

Правки

Диагностика, подготовленные правки, одобрение, эксперименты.

Провести диагностику бренда (проверки сайта, пробелы, рекомендации по страницам и блокам)

POST/v1/diagnose

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно

Ответы

  • 200 OK

    application/json Recommendation[]

    • id string
    • brand_id string
    • kind string
    • auto_fixable boolean
    • priority integer
      1 = наивысший
    • title string
    • detail string
    • url string
    • created_at string date-time
  • 402 Ошибка

    application/json Error

Текущие рекомендации

GET/v1/recommendations

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
auto_fixablequerystring

Допустимые значения: true, false

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Recommendation[]

    • id string
    • brand_id string
    • kind string
    • auto_fixable boolean
    • priority integer
      1 = наивысший
    • title string
    • detail string
    • url string
    • created_at string date-time

Подготовить для страницы правки с проверкой фактов

POST/v1/content/generate

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • url string Обязательно
  • language string
  • kinds string[]
    По умолчанию — все типы; block готовит блоки разделов страницы

    Допустимые значения: answer_block, faq, meta_description, schema, block

Ответы

  • 201 Предложенные правки

    application/json Content[]

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

Список правок с инструкциями по размещению и исходными фактами

GET/v1/content/items

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
statusquerystring
Один статус или несколько через запятую, например approved,live (см. ContentStatus)
urlquerystring
kindquerystring
Тип правки (answer_block, faq, meta_description, schema, page, gbp_profile, gbp_post, block:<id>) или block — все блоки
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Content[]

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка

Получить правку

GET/v1/content/items/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 404 Ошибка

    application/json Error

Одобрить правку (при необходимости с изменениями)

POST/v1/content/{id}/approve

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Без дополнения «Доставка через API» правки сайта переходят в статус approved (готовы к применению вручную, с placement; событие content.approved) и ждут вызова POST /v1/content/{id}/applied. С дополнением они сразу получают статус live (их отдаёт GET /v1/content, отправляется событие content.published, URL уходит в IndexNow, начинается эксперимент). Страницы всегда переходят в статус approved и ждут POST /v1/pages/{id}/published. Правки в Business Profile (gbp_profile, gbp_post) на любом тарифе автоматически записываются в Google (флаг функции google_bp). Отредактированное содержимое повторно проходит очистку.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса

application/json object

  • Структура зависит от типа правки.
    Поля: 8
    • text string
      Для answer_block и meta_description
    • sentences Sentence[]
    • faq object[]
      Поля: 3
      • q string
      • a string
      • fact_ids string[]
    • schema object
      Структурированные данные JSON-LD
    • block Block
    • page Page
    • profile object
      Для gbp_profile
      Поля: 4
      • description string

        До 750 символов

      • phone string
      • website string
      • hours string
        openingHours в формате schema.org, например Mo-Sa 09:00-20:00, Su 10:00-16:00
    • post object
      Для gbp_post
      Поля: 2
      • summary string
      • url string

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

  • 403 Ошибка

    application/json Error

Отклонить предложенную, заблокированную или одобренную (ещё не применённую) правку

POST/v1/content/{id}/reject

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

Откатить опубликованную правку

POST/v1/content/{id}/rollback

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Правки, доставленные через API или в Business Profile, PromART убирает сам (rolled_back). Правки, которые клиент применил вручную, переходят в статус remove_requested (content.removal_requested) и остаются в нём до вызова POST /v1/content/{id}/removed.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

Отметить одобренную правку как применённую вручную

POST/v1/content/{id}/applied

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Клиент вставил правку на сайт. Правка получает статус live (delivery: manual), отправляется событие content.published, URL уходит в IndexNow и начинается эксперимент (повторный замер, затем правку оставляют или откатывают). Для новых страниц вместо этого используется POST /v1/pages/{id}/published.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

  • 404 Ошибка

    application/json Error

Подтвердить, что правка убрана с сайта

POST/v1/content/{id}/removed

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Для правок в статусе remove_requested. Правка получает статус rolled_back, отправляется событие content.rolled_back и URL уходит в IndexNow.

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Content

    • id string
    • brand_id string
    • url string
      URL страницы или gbp://<domain> для правок в Business Profile
    • kind string
      Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
    • fact_ids string[]
    • technical boolean
    • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

      Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

    • delivery string
      Способ доставки опубликованной правки

      Допустимые значения: api, manual, gbp

    • variant integer
    • verifier_notes string
      Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
    • created_at string date-time
    • published_at string date-time
    • updated_at string date-time
    • placement Placement
    • facts FactRef[]
      Подтверждённые факты, на основе которых написана правка
  • 400 Ошибка

    application/json Error

  • 404 Ошибка

    application/json Error

Эксперименты «до и после» для опубликованных правок

GET/v1/experiments

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idquerystring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Experiment[]

    • id string
    • brand_id string
    • content_id string
    • url string
    • prompt_ids string[]
    • baseline number
    • baseline_n integer
    • after number
    • after_n integer
    • lift_pp number
    • status string

      Допустимые значения: waiting, measuring, kept, rolled_back, inconclusive, cancelled

    • run_id string
    • pickup_at string date-time
    • created_at string date-time
    • decided_at string date-time

Запустить повторный замер эксперимента сейчас

POST/v1/experiments/{id}/measure-now

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Повторный замер поставлен в очередь

    application/json object

    • queued boolean

Вебхуки

Список вебхуков

GET/v1/webhooks

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Webhook[]

    • id string
    • url string
    • events EventType[]

      Допустимые значения: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

    • secret string
      Возвращается при создании; им подписываются уведомления
    • created_at string date-time

Подписать URL на события

POST/v1/webhooks

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • url string uri Обязательно
  • events EventType[] Обязательно

    Допустимые значения: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

Ответы

  • 201 Вебхук создан (секрет показывается только в этом ответе)

    application/json Webhook

    • id string
    • url string
    • events EventType[]

      Допустимые значения: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

    • secret string
      Возвращается при создании; им подписываются уведомления
    • created_at string date-time
  • 400 Ошибка

    application/json Error

Удалить вебхук

DELETE/v1/webhooks/{id}

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Удалено

    application/json object

    • deleted boolean

Последние события (тело такое же, как в уведомлениях вебхуков)

GET/v1/events

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
limitqueryinteger

По умолчанию: 100Не более 1000

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json object[]

    • id string
    • Допустимые значения: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

    • payload object
      Тело события: {id, type, created_at, data}
    • created_at string date-time

Отзывы

Список контактов клиентов

GET/v1/contacts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json Contact[]

    • id string Только для чтения
    • brand_id string
    • name string
    • phone string
    • email string
    • language string
    • source string

      Допустимые значения: csv, api, crm

    • opted_out boolean
    • last_requested_at string date-time
    • created_at string date-time

Добавить контакты (клиентов, давших согласие на связь)

POST/v1/contacts

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • consent boolean Обязательно
    Должно быть true
  • contacts Contact[] Обязательно
    Поля: 9
    • brand_id string
    • name string
    • phone string
    • email string
    • language string
    • source string

      Допустимые значения: csv, api, crm

    • opted_out boolean
    • last_requested_at string date-time
    • created_at string date-time

Ответы

  • 201 Контакты добавлены

    application/json object

    • added integer
  • 400 Ошибка

    application/json Error

Импортировать контакты из CSV

POST/v1/contacts/import

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Столбцы Name, Phone, Email, Language (первая строка — заголовки; UTF-8, BOM допускается). Дубликаты пропускаются.

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
consentqueryОбязательноstring

Допустимые значения: true

langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

text/csv string

Ответы

  • 201 Контакты импортированы

    application/json object

    • rows integer
    • added integer
  • 400 Ошибка

    application/json Error

Отписать контакт от запросов отзывов

POST/v1/contacts/{id}/opt-out

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 204 Контакт отписан

Настройки запросов отзывов

GET/v1/reviews/settings

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 OK

    application/json ReviewSettings

    • auto boolean
      Ежедневно отправлять запросы новым контактам
    • review_url string
      По умолчанию — ссылка для отзывов в Business Profile
    • daily_max integer

      По умолчанию: 50

Изменить настройки запросов отзывов

PUT/v1/reviews/settings

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Параметры

ПараметрТип и описание
brand_idqueryОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json ReviewSettings

  • auto boolean
    Ежедневно отправлять запросы новым контактам
  • review_url string
    По умолчанию — ссылка для отзывов в Business Profile
  • daily_max integer

    По умолчанию: 50

Ответы

  • 200 OK

    application/json ReviewSettings

    • auto boolean
      Ежедневно отправлять запросы новым контактам
    • review_url string
      По умолчанию — ссылка для отзывов в Business Profile
    • daily_max integer

      По умолчанию: 50

Запросить отзывы у подходящих клиентов

POST/v1/review-requests

Авторизация: Bearer‑токен (API‑ключ sk_live_… или сеанс панели sess_…)

Подходят клиенты, которые не отписались и которым не отправляли запрос за последние 180 дней. Каждый запрос доставляется вебхуком review.request в вашу систему рассылки сообщений; с dry_run сообщения только возвращаются в ответе.

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • brand_id string Обязательно
  • max integer
  • dry_run boolean

Ответы

  • 200 Запросы

    application/json object[]

    • contact_id string
    • name string
    • phone string
    • email string
    • language string
    • message string
  • 400 Ошибка

    application/json Error

Публичные методы

Без API‑ключа: возврат из OAuth, страницы приглашений и их шрифты, регистрация, вход в панель, документация.

Проверка работоспособности

GET/healthz

Без авторизации

Ответы

  • 200 OK

    application/json object

    • status string

      Допустимые значения: ok

Этот документ OpenAPI

GET/openapi.yaml

Без авторизации

Ответы

  • 200 Документ OpenAPI 3.1 в формате YAML

    application/yaml string

Документация API (эта страница)

GET/docs

Без авторизации

Этот справочник в виде одной HTML‑страницы. Сервер собирает её из этого документа OpenAPI, и всё содержимое доступно без JavaScript: руководство, затем все методы с параметрами, телами запросов и ответов, примерами кода и примерами ответов. Интерфейс и тексты документа выводятся на языке запроса (lang, иначе Accept-Language, иначе английский); текст без перевода показывается на английском.

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 HTML‑страница

    Заголовки

    • Content-Language string
      Язык текстов в этом ответе: параметр lang, иначе наиболее подходящий поддерживаемый язык из Accept-Language, иначе en (для /openapi.yaml всегда en)

    text/html string

  • 304 Страница не изменилась (If-None-Match)

Стили, скрипт и шрифты страницы документации

GET/docs/assets/{file}

Без авторизации

docs.css, docs.js и веб-шрифты страницы: Sachino Sans (подмножества FiraGO, лицензия OFL-FiraGO.txt) в начертаниях 400, 500 и 600 для латиницы, грузинского алфавита и кириллицы, а также Fira Code (OFL-FiraCode.txt). Страница подключает каждый файл с хешем содержимого в параметре ?v=; с актуальным хешем файл кешируется на год (immutable).

Параметры

ПараметрТип и описание
filepathОбязательноstring

Пример: docs.css

vquerystring
Хеш содержимого файла — тот же, что в ссылке на странице

Ответы

  • 200 Файл (text/css, text/javascript, font/woff2 или text/plain для лицензии)

    text/css string

  • 304 Файл не изменился (If-None-Match)
  • 404 Файл не найден

Веб-шрифты страницы приглашения

GET/assets/fonts/{file}

Без авторизации

Sachino Sans (подмножества FiraGO под лицензией SIL Open Font License; текст лицензии — OFL.txt) в начертаниях 400 и 600 для латиницы, грузинского алфавита и кириллицы, например sachino-sans-400-georgian.woff2. Кешируются на год (immutable); страницы подключают их с хешем содержимого в параметре ?v=.

Параметры

ПараметрТип и описание
filepathОбязательноstring

Пример: sachino-sans-400-latin.woff2

Ответы

  • 200 Файл (font/woff2 или text/plain для лицензии)

    font/woff2 string binary

  • 304 Файл не изменился (If-None-Match)
  • 404 Файл не найден

Веб-шрифты страницы приглашения (по пути /connect/)

GET/connect/assets/fonts/{file}

Без авторизации

Sachino Sans (подмножества FiraGO под лицензией SIL Open Font License; текст лицензии — OFL.txt) в начертаниях 400 и 600 для латиницы, грузинского алфавита и кириллицы, например sachino-sans-400-georgian.woff2. Кешируются на год (immutable); страницы подключают их с хешем содержимого в параметре ?v=. Страница приглашения подключает именно эту копию — по пути с префиксом /connect/, запросы к которому прокси передают в API; файлы те же, что и в /assets/fonts/.

Параметры

ПараметрТип и описание
filepathОбязательноstring

Пример: sachino-sans-400-latin.woff2

Ответы

  • 200 Файл (font/woff2 или text/plain для лицензии)

    font/woff2 string binary

  • 304 Файл не изменился (If-None-Match)
  • 404 Файл не найден

Создать рабочее пространство для бесплатного аудита

POST/v1/signup

Без авторизации

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • name string Обязательно

Ответы

  • 201 Рабочее пространство создано. Сохраните API‑ключ сейчас: он больше не будет показан

    application/json object

    • workspace Workspace
    • api_key string
    • note string
  • 400 Ошибка

    application/json Error

Войти в панель (API‑ключ → токен сеанса)

POST/v1/sessions

Без авторизации

Обменивает API‑ключ рабочего пространства на токен сеанса панели sess_…, который действует 30 дней. Сеансы работают на любом тарифе.

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • api_key string Обязательно

Ответы

  • 201 Сеанс создан

    application/json object

    • token string
    • workspace Workspace
      Поля: 8
      • id string
      • name string
      • plan string
      • parent_id string
      • auto_publish_technical boolean
        Автоматически публиковать технические правки (нужно дополнение «Доставка через API»)
      • api_delivery_enabled boolean
        Платное дополнение «Доставка через API»
      • auto_fixes boolean
        Правки готовятся автоматически после каждой диагностики. Выключено — только аналитика, правки по запросу.
      • created_at string date-time
  • 400 Ошибка

    application/json Error

  • 401 Ошибка

    application/json Error

Тарифы и лимиты

GET/v1/plans

Без авторизации

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 Тарифы в виде объекта: ключ — название тарифа

    application/json map<string, Plan>

    • name string
    • price_gel integer
    • prompts integer
    • engines integer
    • brands integer
    • competitors integer
    • languages integer
    • answers_per_month integer
    • interval string
    • daily_prompts integer
    • diagnosis boolean
    • autopilot boolean
    • child_workspaces integer
    • overage string

      Допустимые значения: block, bill

    • rate_limit_rps number
    • api_access boolean
      API‑ключи могут обращаться к API (панель работает на любом тарифе)

URL возврата из Google OAuth

GET/v1/oauth/google/callback

Без авторизации

Сюда Google перенаправляет браузер после того, как пользователь дал согласие. PromART обменивает код на токены, находит подходящее местоположение, сайт или ресурс и перенаправляет браузер в панель (/#/integrations?kind=&status=).

Параметры

ПараметрТип и описание
codequerystring
statequeryОбязательноstring
Подписан HMAC, действует 30 минут
errorquerystring

Ответы

  • 302 Перенаправление в панель

Страница приглашения для того, кто управляет аккаунтом

GET/connect/{token}

Без авторизации

HTML‑страница с кнопкой Google или формой для токена Cloudflare на языке запроса (lang, иначе Accept-Language, иначе английский) и ссылками на эту же страницу на двух других языках. Текст о подключении берётся из wording в ответе GET /v1/integrations.

Параметры

ПараметрТип и описание
tokenpathОбязательноstring
Одноразовый токен приглашения (действует 14 дней)
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 200 HTML‑страница

    text/html string

  • 404 Ссылка неверна, уже использована или устарела (HTML)

Подключить Cloudflare по приглашению

POST/connect/{token}

Без авторизации

Параметры

ПараметрТип и описание
tokenpathОбязательноstring
Одноразовый токен приглашения (действует 14 дней)
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/x-www-form-urlencoded object

  • token string Обязательно
    API‑токен Cloudflare

Ответы

  • 200 Подключено (HTML)
  • 400 Ошибка (HTML): снова форма с указанием причины или страница об устаревшей ссылке

Открыть экран согласия Google по приглашению

GET/connect/{token}/google

Без авторизации

Параметры

ПараметрТип и описание
tokenpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Ответы

  • 302 Перенаправление на экран согласия Google
  • 400 Ошибка (HTML)

Администрирование

Методы для администратора сервера, заголовок X-Admin-Token.

Создать рабочее пространство на любом тарифе

POST/v1/admin/workspaces

Авторизация: токен администратора в заголовке X-Admin-Token

Параметры

ПараметрТип и описание
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • name string Обязательно
  • plan string

    По умолчанию: optimize

  • parent_id string

Ответы

  • 201 Рабочее пространство создано. Сохраните API‑ключ сейчас: он больше не будет показан

    application/json object

    • workspace Workspace
    • api_key string
    • note string
  • 401 Ошибка

    application/json Error

Сменить тариф рабочего пространства или дополнение «Доставка через API»

PATCH/v1/admin/workspaces/{id}

Авторизация: токен администратора в заголовке X-Admin-Token

Параметры

ПараметрТип и описание
idpathОбязательноstring
langqueryAccept-Languageheader
Язык текстов в ответе: ka, ru или en. Подробнее: Язык ответов

Тело запроса Обязательно

application/json object

  • plan string
  • api_delivery_enabled boolean
    Подключить или отключить платное дополнение «Доставка через API»

Ответы

  • 200 Рабочее пространство

    application/json Workspace

    • id string
    • name string
    • plan string
    • parent_id string
    • auto_publish_technical boolean
      Автоматически публиковать технические правки (нужно дополнение «Доставка через API»)
    • api_delivery_enabled boolean
      Платное дополнение «Доставка через API»
    • auto_fixes boolean
      Правки готовятся автоматически после каждой диагностики. Выключено — только аналитика, правки по запросу.
    • created_at string date-time
  • 401 Ошибка

    application/json Error

  • 404 Ошибка

    application/json Error

Схемы

Объекты, которые методы принимают и возвращают; каждый описан здесь один раз. В описании метода показаны поля его запроса и ответа, а остальное — ссылками на этот раздел.

Error object

  • error object
    Поля: 4
    • code string

      Допустимые значения: unauthorized, plan_limit, api_access_required, addon_required, feature_disabled, not_found, invalid_request, invalid_json, rate_limited, internal

    • message string
      Сообщение для человека; на языке ответа, если задан reason, иначе на английском
    • reason string
      Конкретная причина: стабильный ключ сообщения, например http.err.brand_id_required или core.err.not_found.brand (есть не у всех ошибок)
    • params object
      Значения из сообщения без форматирования; тариф, статус или ИИ‑система передаются кодом (только вместе с reason и только если значения есть)

Workspace object

  • id string
  • name string
  • plan string
  • parent_id string
  • auto_publish_technical boolean
    Автоматически публиковать технические правки (нужно дополнение «Доставка через API»)
  • api_delivery_enabled boolean
    Платное дополнение «Доставка через API»
  • auto_fixes boolean
    Правки готовятся автоматически после каждой диагностики. Выключено — только аналитика, правки по запросу.
  • created_at string date-time

Plan object

  • name string
  • price_gel integer
  • prompts integer
  • engines integer
  • brands integer
  • competitors integer
  • languages integer
  • answers_per_month integer
  • interval string
  • daily_prompts integer
  • diagnosis boolean
  • autopilot boolean
  • child_workspaces integer
  • overage string

    Допустимые значения: block, bill

  • rate_limit_rps number
  • api_access boolean
    API‑ключи могут обращаться к API (панель работает на любом тарифе)

Usage object

  • plan Plan
  • month string
  • answers integer
  • queued_jobs integer
  • prompts integer
  • brands integer
  • overage_answers integer
  • child_workspaces integer
  • add_ons object[]
    Поля: 4
    • name string
    • title string
    • description string
    • enabled boolean

Competitor object

  • name string
  • variants string[]
  • domain string

Brand object

  • id string Только для чтения
  • name string
  • domain string
  • industry string
  • city string
  • variants string[]
    Другие варианты написания (например на грузинском или русском)
  • competitors Competitor[]
  • languages string[]
  • markets string[]
  • engines string[]
  • channel string
    api: сервер вашего сайта обращается к API PromART; gbp: только Business Profile

    Допустимые значения: api, gbp

  • created_at string date-time Только для чтения

Fact object

  • id string Только для чтения
  • brand_id string
  • key string
  • value string
  • lang string
    Код языка или any
  • url string
  • source string

    Допустимые значения: api, form, extracted

  • status string

    Допустимые значения: confirmed, unconfirmed

  • updated_at string date-time Только для чтения

Prompt object

  • id string Только для чтения
  • brand_id string
  • text string
  • language string
  • market string
  • target_url string
  • active boolean
  • created_at string date-time Только для чтения

Run object

  • id string
  • brand_id string
  • kind string

    Допустимые значения: baseline, scheduled, daily, manual, remeasure

  • status string
  • repeats integer
  • engines string[]
  • jobs_total integer
  • jobs_done integer
  • jobs_failed integer
  • created_at string date-time
  • finished_at string date-time

Answer object

  • id string
  • run_id string
  • prompt_id string
  • prompt string
  • engine string
  • language string
  • location string
  • route string
  • text string
  • citations string[]
  • screenshot_url string
    Зарезервировано: пока ни один адаптер ИИ‑систем не делает скриншоты, поэтому в ответах этого поля нет
  • mentions object[]
    Поля: 5
    • name string
    • is_client boolean
    • position integer
      1 = назван первым
    • sentiment number

      От −1 до 1

    • cited_urls string[]
  • created_at string date-time

VisRow object

  • week string
  • engine string
  • language string
  • answers integer
  • mentioned integer
  • visibility_pct number
  • avg_position number
  • avg_sentiment number

SOVRow object

  • name string
  • is_client boolean
  • mentions integer
  • share_pct number
  • avg_position number
  • avg_sentiment number

CitationRow object

  • domain string
  • count integer
  • share_pct number
  • owner string

    Допустимые значения: client, competitor, third_party

Recommendation object

  • id string
  • brand_id string
  • kind string
  • auto_fixable boolean
  • priority integer
    1 = наивысший
  • title string
  • detail string
  • url string
  • created_at string date-time

Experiment object

  • id string
  • brand_id string
  • content_id string
  • url string
  • prompt_ids string[]
  • baseline number
  • baseline_n integer
  • after number
  • after_n integer
  • lift_pp number
  • status string

    Допустимые значения: waiting, measuring, kept, rolled_back, inconclusive, cancelled

  • run_id string
  • pickup_at string date-time
  • created_at string date-time
  • decided_at string date-time

TrafficRow object

  • source string
  • sessions integer
  • from string date
  • to string date

Report object

  • brand Brand
  • period string
    from – to в виде текста
  • from string date
    Первый день недели отчёта
  • to string date
    Последний день недели отчёта (сегодня, по UTC)
  • visibility_pct number
  • visibility_prev_pct number
  • delta_pp number
  • by_engine VisRow[]
  • share_of_voice SOVRow[]
  • top_citations CitationRow[]
  • live_changes integer
  • pending_approval integer
  • experiments Experiment[]
  • recommendations Recommendation[]
  • alerts string[]
  • ai_traffic TrafficRow[]
  • recent_actions Action[]
  • failing_site_checks SiteCheck[]

ContentStatus string

approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

Sentence object

  • text string
  • fact_ids string[]

Block object

  • block_id string
  • selector string
    CSS‑селектор; применяется к первому совпадению
  • action string

    Допустимые значения: replace, append, prepend, before, after

  • html string
    Очищенный HTML

Page object

  • url string
    Предлагаемый URL; после POST /v1/pages/{id}/published заменяется фактическим
  • title string
  • language string
  • topic string
  • sections object[]
    Поля: 3
    • heading string
    • html string
      Очищенный HTML (абзацы, списки, таблицы)
    • sentences Sentence[]
  • schema object
    JSON-LD для вставки в тег script type=application/ld+json
  • internal_links object[]
    Поля: 2
    • url string
    • text string

ContentBody object

Структура зависит от типа правки.
  • text string
    Для answer_block и meta_description
  • sentences Sentence[]
  • faq object[]
    Поля: 3
    • q string
    • a string
    • fact_ids string[]
  • schema object
    Структурированные данные JSON-LD
  • block Block
  • page Page
  • profile object
    Для gbp_profile
    Поля: 4
    • description string

      До 750 символов

    • phone string
    • website string
    • hours string
      openingHours в формате schema.org, например Mo-Sa 09:00-20:00, Su 10:00-16:00
  • post object
    Для gbp_post
    Поля: 2
    • summary string
    • url string

Content object

  • id string
  • brand_id string
  • url string
    URL страницы или gbp://<domain> для правок в Business Profile
  • kind string
    Тип правки: answer_block | faq | meta_description | schema | block:<id> | page | gbp_profile | gbp_post
  • fact_ids string[]
  • technical boolean
  • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

    Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

  • delivery string
    Способ доставки опубликованной правки

    Допустимые значения: api, manual, gbp

  • variant integer
  • verifier_notes string
    Причина, по которой проверки заблокировали правку (или отметка о том, что её изменили перед одобрением), на языке ответа (см. раздел «Язык ответов»). На английском: «sanitizer: <reason>», «verifier: <JSON list of reasons>» или «edited by client before approval».
  • created_at string date-time
  • published_at string date-time
  • updated_at string date-time
  • placement Placement
  • facts FactRef[]
    Подтверждённые факты, на основе которых написана правка

Placement object

Где и как применить правку вручную. where, steps и подписи частей приходят на языке ответа (см. раздел «Язык ответов»); значения частей — это само содержимое сайта, и они никогда не переводятся.
  • url string
  • where string
  • steps string[]
  • current string
    Заменяемый текст в том виде, в каком PromART прочитал его в последний раз (для блоков с replace)
  • parts CopyPart[]

CopyPart object

  • label string
  • format string

    Допустимые значения: text, html, json-ld, head-html

  • value string

FactRef object

  • id string
  • key string
  • value string
  • lang string

KPI object

  • answers integer
  • mentioned integer
  • visibility_pct number
  • sov_pct number
  • avg_position number
    Чем меньше, тем лучше
  • avg_sentiment number

    От −1 до 1

Overview object

  • from string date
  • to string date
  • prev_from string date
  • prev_to string date
  • current KPI
  • previous KPI

TrendRow object

  • week string date
    Понедельник недели
  • key string
    ИИ‑система, язык, название бренда или all
  • is_client boolean
  • answers integer
  • mentioned integer
  • visibility_pct number
  • sov_pct number
  • avg_position number
  • avg_sentiment number

CompetitorRow object

  • name string
  • is_client boolean
  • mentions integer
  • visibility_pct number
  • sov_pct number
  • avg_position number
  • avg_sentiment number
  • prev_visibility_pct number
  • prev_sov_pct number

SourceRow object

  • url string
    Только при by=url
  • domain string
  • owner string

    Допустимые значения: client, competitor, third_party

  • count integer
    Число ответов, цитирующих источник
  • share_pct number
  • engines map<string, integer>

EngineCell object

  • answers integer
  • visibility_pct number
  • avg_position number

PromptRow object

  • prompt_id string
  • text string
  • language string
  • target_url string
  • answers integer
  • visibility_pct number
  • avg_position number
  • top_competitor string
  • engines map<string, EngineCell>

BlockItem object

  • content_id string
  • block_id string
  • selector string
  • action string

    Допустимые значения: replace, append, prepend, before, after

  • html string
  • fact_ids string[]
  • approved = готова к применению вручную; remove_requested = откачена и ждёт, когда клиент уберёт её с сайта

    Допустимые значения: proposed, approved, live, remove_requested, rolled_back, rejected, superseded, stale, blocked

Delivery object

  • url string
  • version integer
    Увеличивается с каждой опубликованной правкой для этого URL
  • meta_description string
  • answer_block string
  • faq object[]
    Поля: 3
    • q string
    • a string
    • fact_ids string[]
  • schema object
    Структурированные данные JSON-LD
  • blocks BlockItem[]
  • content_ids string[]
  • signature string
    Устаревшее поле: HMAC тела ответа без этого поля. Вместо него проверяйте заголовок X-Sachino-Signature.

SiteCheck object

  • id string
  • check string

    Допустимые значения: robots_ai_bots, cdn_ai_bots, sitemap, indexnow_key, fetch, noindex, js_rendering, speed, google_index

  • target string
    Домен или URL
  • status string

    Допустимые значения: ok, warn, fail, unknown

  • detail string
  • instruction string
    Конкретная задача для клиента или разработчика
  • fix string
    Автоисправление, которое может выполнить PromART, например cloudflare:allow_ai_crawlers
  • source string

    Допустимые значения: crawl, gsc, cloudflare

  • checked_at string date-time

IndexNowInfo object

  • key string
  • files object[]
    Поля: 5
    • brand_id string
    • domain string
    • url string
      Адрес файла: https://<domain>/<key>.txt
    • content string
      Точное содержимое файла (сам ключ)
    • status string
      По результатам последней проверки сайта

      Допустимые значения: ok, fail, unknown

  • instructions string[]

Integration object

  • id string
  • brand_id string
  • kind string

    Допустимые значения: google_bp, gsc, ga4, cloudflare

  • status string

    Допустимые значения: invited, pending, connected, needs_selection, error, revoked

  • account string
  • scopes string
  • config map<string, string>
  • invite_email string
  • last_sync_at string date-time
  • last_error string
  • created_at string date-time
  • updated_at string date-time

IntegrationKind object

  • scope string
    Область доступа Google OAuth
  • access string
  • does string
  • enabled boolean
    false, если на сервере выключен флаг функции

ConnectResult object

  • integration Integration
  • auth_url string
    Экран согласия Google
  • invite_url string
    Одноразовая ссылка для того, кто управляет аккаунтом
  • note string

Action object

  • id string
  • brand_id string
  • channel string

    Допустимые значения: site, gbp, gsc, bing, cloudflare, reviews

  • kind string
  • target string
  • summary string
  • content_id string
  • integration_id string
  • before any
    Прежнее значение (если известно)
  • after any
    Новое значение
  • status string

    Допустимые значения: done, failed, rolled_back

  • error string
  • rollback_url string
    Отправьте сюда POST, чтобы отменить действие (только для обратимых действий)
  • created_at string date-time
  • rolled_back_at string date-time

Contact object

  • id string Только для чтения
  • brand_id string
  • name string
  • phone string
  • email string
  • language string
  • source string

    Допустимые значения: csv, api, crm

  • opted_out boolean
  • last_requested_at string date-time
  • created_at string date-time

ReviewSettings object

  • auto boolean
    Ежедневно отправлять запросы новым контактам
  • review_url string
    По умолчанию — ссылка для отзывов в Business Profile
  • daily_max integer

    По умолчанию: 50

EventType string

Допустимые значения: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

Webhook object

  • id string
  • url string
  • events EventType[]

    Допустимые значения: *, run.completed, visibility.changed, content.proposed, content.published, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request, content.approved, content.removal_requested

  • secret string
    Возвращается при создании; им подписываются уведомления
  • created_at string date-time