API: Мониторинг бренда в ИИ-ответах

API позволяет получить упоминания бренда в ответах ИИ-моделей (ChatGPT, DeepSeek и др.) и в AI-блоках поисковой выдачи Google и Яндекса.

---

Логика работы API

1. Создать задачу — отправляем POST-запрос с ключевыми словами, брендом, доменом, списком ИИ-моделей и параметрами поиска.
2. В ответ получаем ID задачи.
3. Получить результат — отправляем GET-запрос по ID задачи.
4. В ответе возвращаются ответы ИИ-моделей и данные AI-блоков из выдачи.

---

1. Создание задачи

POST:

https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/

---

Параметры запроса (params)

Параметр	Обязательный	Тип	Описание
toolName	✅	string	Название инструмента: всегда "aiSerp"
keywords	✅	string / array	Поисковый запрос или массив запросов
brandNames	✅	string / array	Название бренда (или массив названий) для отслеживания упоминаний
domain	✅	string	Ваш домен (например, example.com)
aiModels	✅	array	Список ИИ-моделей для анализа (см. ниже)
searchOptions	✅	array of object	Список комбинаций «движок + регион + язык + устройство»

---

Поддерживаемые значения aiModels

Значение	Описание
chatgpt	OpenAI ChatGPT
deepseek	DeepSeek

---

Параметры searchOptions (каждый элемент массива)

Параметр	Обязательный	Тип	Описание
engine	✅	string	Поисковая система: "google" или "yandex"
region	✅	string	Код региона. Для Google — GoogleID региона (например, 1011969 — Москва), для Yandex — yandexKey (например, 213 — Москва). См. список регионов
language	✅	string	Язык выдачи (например, "ru")
device	✅	string	Устройство: "desktop" или "mobile"

---

Пример запроса

curl 'https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/' \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'Api-Key: ***' \
  --data-raw '{
    "data": {
      "type": "toolTasks",
      "attributes": {
        "toolName": "aiSerp",
        "params": {
          "keywords": "pr-cy",
          "brandNames": "pr-cy",
          "domain": "pr-cy.ru",
          "aiModels": ["chatgpt", "deepseek"],
          "searchOptions": [
            {"device": "desktop", "region": "1011969", "engine": "google", "language": "ru"},
            {"device": "desktop", "region": "213", "engine": "yandex", "language": "ru"}
          ]
        }
      }
    }
  }'

---

2. Ответ при создании задачи

API вернёт ID задачи:

{
  "data": {
    "type": "toolTasks",
    "id": "de18726b84bf92dc5335ac478766957b",
    "attributes": {
      "cost": 8,
      "started": "2026-05-20T14:03:45+03:00",
      "...": "..."
    }
  }
}

В поле cost — количество лимитов, которое спишется за задачу.

---

3. Получение результатов

GET:

https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/{task_id}?filter[since]=0&include=tests

---

Пример запроса

curl --location --globoff \
'https://apis.pr-cy.ru/api/v2.1.0/tool-tasks/de18726b84bf92dc5335ac478766957b?filter[since]=0&include=tests' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Api-Key: ***'

Где:

• {task_id} — ID задачи, полученный в шаге 1.
• filter[since]=0 — фильтр по времени (0 = с начала).
• include=tests — добавляет к ответу подробные результаты.

---

Структура результата

В блоке included возвращаются два теста:

aiBrandsTool — ответы ИИ-моделей по бренду

Поле results.aiBrands — массив, где каждый элемент содержит:

Поле	Описание
keyword	Ключевое слово, по которому делался запрос
model	ИИ-модель (chatgpt, deepseek и т. д.)
aiAnswer	Текст ответа ИИ-модели
aiSources	Источники, на которые ссылалась модель (если есть)

aiSerpsTool — AI-блоки из поисковой выдачи

Поле results.aiSerps — массив, где каждый элемент содержит:

Поле	Описание
keyword	Ключевое слово
engine	google или yandex
region	Код региона
language	Язык выдачи
device	Устройство
count	Общее количество результатов в выдаче
ai	Массив AI-блоков, каждый содержит: type (например, center), position — позиция в выдаче, aiAnswer — текст AI-ответа, aiSources — список упомянутых источников (url + name)

Поле progress: 1 означает, что обработка завершена. Если меньше 1 — задача ещё формируется, повторите запрос через несколько секунд.