brandfound. API
API для отслеживания упоминаний бренда в AI-ассистентах (ChatGPT, Gemini, Claude, Perplexity). Управление компаниями, продуктами, конкурентами, запросами, упоминаниями и аналитикой.
Базовый URL
https://app.brandfound.ai/api/v1Playground
Нажмите в панели запроса, чтобы открыть интерактивный Playground. Выберите API ключ, укажите параметры и отправьте запрос прямо из документации.
120 / мин60 / минUNAUTHORIZEDНеверная авторизацияFORBIDDENНедостаточно правNOT_FOUNDРесурс не найденVALIDATION_ERRORОшибка валидацииRATE_LIMIT_EXCEEDEDПревышен лимитINTERNAL_ERRORВнутренняя ошибкаЧто нового в версии 1.2
Публичные адреса методов не менялись, обратная совместимость сохранена.
Аналитика снова отвечает
Методы разделов «Аналитика», «Ссылки» и «Реклама» возвращали ошибку 500 из-за проблемы на нашей стороне. Исправлено, действий с вашей стороны не требуется.
Видно состояние запроса
В списке запросов появились answersCount, фактический список нейросетей в providers и сводный статус queue.status. Раньше providers всегда приходил пустым.
Очередь опросов
Разделы queries/queue и queue/summary показывают, что опрашивается и сколько это стоит. Опросы, остановленные из-за нехватки FoxCoin, возвращаются в работу через queue/resume: сами они не возобновляются.
Баланс и расходы
billing/balance отдаёт остаток и цены всех операций, billing/transactions отдаёт историю списаний с указанием запроса.
Язык ответа
Поле language теперь задаёт язык ответа нейросети. Работает в ChatGPT, Gemini, Perplexity и DeepSeek.
Справочник нейросетей
Метод sources отдаёт список доступных ассистентов и помечает те, что используются по умолчанию.
Мониторинг
Запрос можно поставить на регулярный опрос и задать расписание. Раньше это было доступно только в интерфейсе.
AI-трафик
Переходы на сайт из ответов нейросетей, поведение посетителей, воронка и цели по данным Яндекс.Метрики.
Коммерс
Товарные карточки в ответах нейросетей и номенклатура для сопоставления с ними.
Компания стала обязательной
Методы links, links/filter-options, analytics/links/top-domains, analytics/competitors/preview и advertising требуют companyId. Раньше без него ответ объединял все компании аккаунта.
Аутентификация
Все запросы к API требуют авторизации. Создайте API ключ в разделе Настройки → API ключи. Ключи имеют префикс gfx_.
Передайте ключ в заголовке Authorization каждого запроса.
Веб-приложение автоматически использует cookie session-token. Дополнительная настройка не требуется.
Окружения
Окружения (workspaces / teams). Один OAuth-токен умеет работать со всеми окружениями, к которым у user есть доступ (свой + ACCEPTED TeamMember). Активное окружение хранится в ApiKey.activeAccountId — переключение персистентно и видно всем MCP-клиентам этого ключа на следующем запросе. Доступ проверяется на каждом запросе: при потере членства middleware молча возвращается к accountId, выданному при OAuth, без 401. Побочный эффект переключения: preferredCompanyId сбрасывается, т.к. он привязан к старому окружению.
Список доступных окружений
/api/v1/workspacesВозвращает все workspaces (accountId), к которым у текущего user есть доступ: собственный + ACCEPTED TeamMember. Поле `isCurrent: true` помечает то окружение, на котором сейчас работает API key (с учётом activeAccountId override).
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/workspacesУспешный ответ
Переключить активное окружение для текущего API key
/api/v1/workspaces/switchОбновляет ApiKey.activeAccountId. Эффект персистентный — применяется ко ВСЕМ следующим запросам этого ключа (в том числе из других MCP-клиентов). При accountId=null сбрасывает override и возвращает поведение к токеновскому accountId. Побочный эффект: preferredCompanyId сбрасывается в null (привязана к старому окружению). Только для аутентификации через API key.
Тело запроса
accountIdstringобязательноеUUID workspace для переключения. null = сбросить активный override и вернуться к accountId, выданному при OAuth.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED403application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/workspaces/switchУспешный ответ
Компании
Управление компаниями
Список компаний
/api/v1/companiesВозвращает список компаний пользователя с продуктами, конкурентами и ключевыми словами.
Параметры запроса
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
sortBystring= createdAtcreatedAtupdatedAtnamelastUsedAtsortOrderstring= descПорядок сортировки
ascdescsearchstringПоисковый запрос (case-insensitive)
categoryIdstring (uuid)Фильтр по категории
countrystringФильтр по стране
createdAtFromstring (date-time)Начало диапазона даты создания (ISO 8601)
createdAtTostring (date-time)Конец диапазона даты создания (ISO 8601)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/companiesУспешный ответ
Создать компанию
/api/v1/companiesСоздает новую компанию. Лимит зависит от тарифного плана.
Тело запроса
namestringобязательноеdescriptionstringurlstringcategoryIdstringcountrystringISO 3166-1 alpha-2 («AE»). Legacy-названия («russia») принимаются и нормализуются. Предпочтительнее regionTargets — это поле легаси.
synonymsstring[]Синонимы/альтернативные названия (макс. 20)
regionTargetsobject[]Страны и города замера. ПОЛНОЕ состояние: старые таргеты пересоздаются. Primary-таргет задаёт страну и язык автоподбора семантики.
defaultLanguageIdstringЯзык генерируемых запросов (GET /api/v1/geo/languages).
defaultResponseLanguageIdstringЯзык, на котором должна отвечать нейросеть.
defaultLocalestringBCP-47, например «ar-AE».
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/companiesУспешный ответ
Получить компанию
/api/v1/companies/{id}Возвращает полную информацию о компании, включая продукты, конкурентов и ключевые слова.
Параметры запроса
idstring (uuid)обязательноеID компании
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/companies/{id}Успешный ответ
Обновить компанию
/api/v1/companies/{id}Частичное обновление компании. Передавайте только изменяемые поля. Регионализация: regionTargets задают страны и города замера, primary-таргет определяет страну и язык автоподбора семантики (POST /api/v1/queries/autogenerate). countryId / cityId берутся из GET /api/v1/geo/countries и /api/v1/geo/cities, defaultLanguageId — из /api/v1/geo/languages. regionTargets в теле = ПОЛНОЕ состояние: старые таргеты пересоздаются. Поле isAutoGenerationEnabled устарело: включение (true) ИГНОРИРУЕТСЯ. Это был флаг снесённого планировщика, который генерировал запросы и тем же движением ставил их в платный опрос.
Параметры запроса
idstring (uuid)обязательноеID компании
Тело запроса
namestringdescriptionstringurlstringcategoryIdstringcountrystringISO 3166-1 alpha-2 («AE»). Legacy-названия («russia») принимаются и нормализуются. Предпочтительнее regionTargets — это поле легаси.
synonymsstring[]isAutoGenerationEnabledbooleanУСТАРЕЛО и ИГНОРИРУЕТСЯ при значении true. Это флаг снесённого планировщика: он генерировал запросы и тем же движением ставил их в платный опрос. Автоподбор без опроса — POST /api/v1/queries/autogenerate.
regionTargetsobject[]Страны и города замера. ПОЛНОЕ состояние: старые таргеты пересоздаются. Primary-таргет задаёт страну и язык автоподбора семантики.
defaultLanguageIdstringЯзык генерируемых запросов (GET /api/v1/geo/languages).
defaultResponseLanguageIdstringЯзык, на котором должна отвечать нейросеть.
defaultLocalestringBCP-47, например «ar-AE».
autogenQueryTypesstring[]Типы запросов автоподбора. По умолчанию commercial, informational, comparative, reputational. Убрать отсюда comparative — и сравнительный контур («X vs Y») исчезнет из генерируемой семантики.
autogenQueriesPerRunintegerОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/companies/{id}Успешный ответ
Архивировать компанию
/api/v1/companies/{id}Архивирование компании. Данные сохраняются, но компания не отображается в списках.
Параметры запроса
idstring (uuid)обязательноеID компании
Ответы
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/companies/{id}Успешно удалено
Справочник отраслей
/api/v1/companies/categoriesДопустимые значения categoryId для создания и обновления компании.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/companies/categoriesУспешный ответ
Продукты
Управление продуктами
Список продуктов
/api/v1/productsВозвращает список продуктов с привязанными компаниями, ключевыми словами и конкурентами.
Параметры запроса
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
sortBystring= createdAtcreatedAtupdatedAtnamesortOrderstring= descПорядок сортировки
ascdesccompanyIdstring (uuid)Фильтр по компании
searchstringПоисковый запрос (case-insensitive)
createdAtFromstring (date-time)Начало диапазона даты создания (ISO 8601)
createdAtTostring (date-time)Конец диапазона даты создания (ISO 8601)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/productsУспешный ответ
Создать продукт
/api/v1/productsСоздает новый продукт, привязанный к компании.
Тело запроса
namestringобязательноеcompanyIdstringобязательноеdescriptionstringurlstringОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/productsУспешный ответ
Получить продукт
/api/v1/products/{id}Возвращает полную информацию о продукте, включая ключевые слова и конкурентов.
Параметры запроса
idstring (uuid)обязательноеID продукта
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/products/{id}Успешный ответ
Обновить продукт
/api/v1/products/{id}Частичное обновление продукта.
Параметры запроса
idstring (uuid)обязательноеID продукта
Тело запроса
namestringdescriptionstringurlstringОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/products/{id}Успешный ответ
Архивировать продукт
/api/v1/products/{id}Архивирование продукта. Данные сохраняются, но продукт не отображается в списках.
Параметры запроса
idstring (uuid)обязательноеID продукта
Ответы
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/products/{id}Успешно удалено
Конкуренты
Управление конкурентами
Список конкурентов
/api/v1/competitorsВозвращает список конкурентов с привязанными компаниями, продуктами и ключевыми словами.
Параметры запроса
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
sortBystring= createdAtcreatedAtupdatedAtnamesortOrderstring= descПорядок сортировки
ascdesccompanyIdstring (uuid)Фильтр по компании
productIdstring (uuid)Фильтр по продукту
searchstringПоисковый запрос (case-insensitive)
createdAtFromstring (date-time)Начало диапазона даты создания (ISO 8601)
createdAtTostring (date-time)Конец диапазона даты создания (ISO 8601)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/competitorsУспешный ответ
Создать конкурента
/api/v1/competitorsСоздает нового конкурента. Может быть привязан к компании или к конкретному продукту.
Тело запроса
namestringобязательноеcompanyIdstringобязательноеproductIdstringurlstringОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/competitorsУспешный ответ
Получить конкурента
/api/v1/competitors/{id}Возвращает полную информацию о конкуренте с ключевыми словами.
Параметры запроса
idstring (uuid)обязательноеID конкурента
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/competitors/{id}Успешный ответ
Обновить конкурента
/api/v1/competitors/{id}Обновляет имя и/или URL конкурента.
Параметры запроса
idstring (uuid)обязательноеID конкурента
Тело запроса
namestringurlstringОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/competitors/{id}Успешный ответ
Архивировать конкурента
/api/v1/competitors/{id}Архивирование конкурента. Данные сохраняются, но конкурент не отображается в списках.
Параметры запроса
idstring (uuid)обязательноеID конкурента
Ответы
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/competitors/{id}Успешно удалено
Интенты
Интенты (keywords): создание, переименование, архивирование/удаление, restore, bulk attach/detach к компаниям/продуктам/конкурентам
Список интентов (keywords)
/api/v1/keywordsВозвращает интенты (keywords) текущего workspace. Фильтр по target — companyId | productId | competitorId (только один). state контролирует выборку по архиву: active (по умолчанию) / archived / all.
Параметры запроса
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
sortBystring= createdAtcreatedAtnamesortOrderstring= descПорядок сортировки
ascdescstatestring= activeLifecycle фильтр: active (не архивные, по умолчанию), archived (только архивные), all.
activearchivedallsearchstringCase-insensitive подстрока по name.
companyIdstring (uuid)Только интенты с активной связью с этой компанией.
productIdstring (uuid)Только интенты с активной связью с этим продуктом.
competitorIdstring (uuid)Только интенты с активной связью с этим конкурентом.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/keywordsУспешный ответ
Создать (или переиспользовать) интент
/api/v1/keywordsFind-or-create по (name, userId). Если интент уже существует — он переиспользуется (и разархивируется, если был в архиве). Опциональный attach: { companyId | productId | competitorId } — ровно один — привязывает интент к target в одной транзакции.
Тело запроса
namestringобязательноеattachobjectTarget для привязки/отвязки. Должен содержать РОВНО ОДИН из полей.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/keywordsУспешный ответ
Получить интент
/api/v1/keywords/{id}Возвращает интент с активными связями к компаниям, продуктам, конкурентам.
Параметры запроса
idstring (uuid)обязательноеОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/keywords/{id}Успешный ответ
Переименовать интент
/api/v1/keywords/{id}Единственное редактируемое поле — name. Архивированный интент переименовать нельзя (используйте restore сначала).
Параметры запроса
idstring (uuid)обязательноеТело запроса
namestringобязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/keywords/{id}Успешный ответ
Архивировать или удалить интент
/api/v1/keywords/{id}По умолчанию архивирует (soft-delete) интент вместе со всеми его связями — обратимо через POST /restore. С ?permanent=true физически удаляет интент из БД (требует, чтобы он уже был в архиве или имел архивные связи). С ?dryRun=true возвращает отчёт о том, что будет затронуто, без выполнения операции.
Параметры запроса
idstring (uuid)обязательноеpermanentboolean= falseПри true — необратимое удаление из БД. Требует архивного состояния.
dryRunboolean= falseПри true — отчёт без побочных эффектов.
Ответы
204Успешно удалено
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/keywords/{id}Успешный ответ
Восстановить интент из архива
/api/v1/keywords/{id}/restoreСнимает archivedAt с keyword и со всех его архивных связей, чьи родительские сущности (company / product / competitor) ещё живы. Связи к удалённым target остаются архивными.
Параметры запроса
idstring (uuid)обязательноеОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/keywords/{id}/restoreУспешный ответ
Bulk attach интентов к target
/api/v1/keywords/attachДля каждого name делает find-or-create по (name, userId), затем гарантирует активную связь с target. Архивированные связи разархивирует. Target требует РОВНО ОДИН из companyId / productId / competitorId.
Тело запроса
targetobjectобязательноеTarget для привязки/отвязки. Должен содержать РОВНО ОДИН из полей.
namesstring[]обязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/keywords/attachУспешный ответ
Bulk detach интентов от target
/api/v1/keywords/detachАрхивирует активные связи keyword↔target. Сам интент остаётся жить и может быть привязан к другим target. Target требует РОВНО ОДИН из companyId / productId / competitorId.
Тело запроса
targetobjectобязательноеTarget для привязки/отвязки. Должен содержать РОВНО ОДИН из полей.
keywordIdsstring[]обязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/keywords/detachУспешный ответ
Запросы
Управление запросами к AI-ассистентам
Список запросов
/api/v1/queriesВозвращает список запросов к AI-ассистентам с количеством ответов. Поддерживает расширенную фильтрацию: по тональности, кластерам, регионам, избранному, области поиска и диапазонам метрик тональности. Состояние опроса читайте по queue.status и answersCount. Поле providers показывает нейросети, в которые запрос ушёл фактически. Детали по конкретным ранам — GET /api/v1/queries/queue.
Параметры запроса
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
sortBystring= createdAtcreatedAttextupdatedAtsortOrderstring= descПорядок сортировки
ascdesccompanyIdstring (uuid)Фильтр по компании
productIdstring (uuid)Фильтр по продукту
typestringТип запроса (general, comparative, negative и т.д.). Поддерживает массив: ?type=comparative&type=neutral
originstringИсточник запроса. Поддерживает массив: ?origin=manual&origin=auto
manualautohasAnswersstringНаличие ответов
truefalselanguagestringЯзык запроса (ru, en и т.д.). Поддерживает массив: ?language=ru&language=en
searchTextstringПоиск по тексту запроса
providerstringФильтр по AI-провайдеру ответа
sourceIdstringФильтр по ID источника ответа. Поддерживает массив: ?sourceId=id1&sourceId=id2
labelSlugstringФильтр по slug кластера/лейбла
regionstringРегион запроса. Поддерживает массив: ?region=RU®ion=US
isFavoritestringТолько избранные запросы
truefalsesentimentstringФильтр по тональности упоминаний в ответах
positiveneutralnegativesearchFieldstring= queryОбласть поиска для searchText: в тексте запроса, в ответах или в источниках
queryanswersourceslabelFilterModestring= orЛогика фильтрации по кластерам: any (or) или all (and)
orandlabelstringSlug кластера. Поддерживает массив: ?label=slug1&label=slug2
createdAtFromstring (date-time)Начало диапазона даты создания (ISO 8601)
createdAtTostring (date-time)Конец диапазона даты создания (ISO 8601)
showArchivedstringПоказать архивированные запросы (по умолчанию: false)
truefalseОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/queriesУспешный ответ
Создать запрос
/api/v1/queriesСоздаёт запрос и по умолчанию сразу ставит его в очередь опроса. Платно: каждый полученный ответ каждой нейросети списывает FoxCoin (цены в GET /api/v1/billing/balance). Запрос, опрошенный по 5 сетям, стоит 5 ответов. Передайте dispatch: false, чтобы создать запрос, не тратя FoxCoin. Нейросети выбираются полем providers (слаги — GET /api/v1/sources). Без него запрос уходит в те, что заданы по умолчанию для аккаунта (у аккаунта без настроек это ровно ChatGPT). Для массового создания с кластерами — POST /api/v1/queries/setup. Гео задаётся полями region (ISO 3166-1 alpha-2) и language; без region берётся страна компании. Поля geoOverride и resolvedGeoSnapshot — READ-ONLY снапшоты, их считает сервер для запросов кластера с гео-таргетами; в теле POST они не принимаются (тело строгое: неизвестное поле → 400). Результат постановки в очередь смотрите в поле dispatch ответа: dispatched=false с непустым error означает, что запрос создан, но опрос не стартовал.
Тело запроса
textstringобязательноеcompanyIdstringобязательноеproductIdstringtypestring= neutralЛегаси-значения negative и general принимаются: negative → reputational, general → neutral.
neutralcommercialinformationalcomparativereputationalbrandedlanguagestring= ruISO 639-1 код языка ответа (ru, en, ar, hi, vi, ms, ...). Задаёт язык, на котором нейросеть обязана ответить: в промпт подставляется явное требование с названием языка из справочника. По умолчанию ru.
regionstringСтрана запроса, ISO 3166-1 alpha-2 (AE, SA, RU). Без поля берётся страна компании (primary regionTarget), затем RU. Legacy-названия («russia») принимаются и нормализуются. Гео-таргетинга выдачи не даёт — это разрез для фильтров и аналитики.
providersstring[]Нейросети для опроса. Без поля идут дефолты аккаунта (у аккаунта без настроек это ровно ChatGPT).
dispatchboolean= truefalse — создать запрос, НЕ ставя его в платный опрос.
labelsstring[]Имена кластеров: создаются или переиспользуются по slug.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED402application/jsonНедостаточно FoxCoin
HTTP_402404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queriesУспешный ответ
Query Fan-Out: поисковые подзапросы
/api/v1/queries/fanoutКомпания обязательна: передайте companyId или используйте preferredCompanyId ключа (см. GET /api/v1/context). Доступ проверяется в активном workspace. Поисковые подзапросы из метаданных сохранённых ответов. Чтение бесплатно и не запускает опрос нейросетей. Отсутствие записей не означает, что AI не использовал поиск: доступность метаданных зависит от провайдера. WebSearch и ImageSearch различаются полем kind. Сводка считается по всей отфильтрованной выборке до пагинации. Для подробностей передайте mode=observations, groupKey из сводки и тот же companyId/asOf. Появления — записи в метаданных, а даты относятся к итоговым ответам. Неготовый или выключенный индекс возвращает HTTP 503 SERVICE_UNAVAILABLE; повторите запрос позднее. Неизвестные параметры и неверные значения возвращают HTTP 400.
Параметры запроса
companyIdstring (uuid)Компания обязательна: передайте companyId или используйте preferredCompanyId ключа (см. GET /api/v1/context). Доступ проверяется в активном workspace.
productIdstring (uuid)Фильтр продукта.
queryIdstring[]Исходные запросы, до 100 UUID. Повторяйте параметр.
modestring= summaryСводка по подзапросам или подробные появления в ответах.
summaryobservationsgroupKeystringТочный key из сводки; используется вместе с той же компанией.
searchTextstringТекст поиска.
searchFieldstring= subqueryПоиск по подзапросу, исходному запросу, ответу или точному домену источника.
subqueryqueryanswersourcessourceIdstring[]AI-провайдер: UUID, имя или слаг. Повторяйте параметр для нескольких значений.
providerstring[]Имя исходно запрошенного AI-провайдера. Повторяйте параметр для нескольких значений.
labelstring[]Slug кластера исходного запроса. Повторяйте параметр для нескольких значений.
typestring[]Тип исходного запроса: neutral, commercial, informational, comparative, reputational, branded; legacy general/negative нормализуются. Повторяйте параметр для нескольких значений.
languagestring[]Язык исходного запроса. Повторяйте параметр для нескольких значений.
regionstring[]Регион исходного запроса. Повторяйте параметр для нескольких значений.
labelFilterModestring= orОбъединение кластеров ИЛИ/И.
orandsentimentstringТональность упоминаний в ответе.
positiveneutralnegativecreatedAtFromstring (date-time)Начало периода создания исходных запросов. ISO-8601 с часовым поясом.
createdAtTostring (date-time)Конец периода создания исходных запросов. ISO-8601 с часовым поясом.
answerCreatedAtFromstring (date-time)Начало периода сохранения ответов. ISO-8601 с часовым поясом.
answerCreatedAtTostring (date-time)Конец периода сохранения ответов. ISO-8601 с часовым поясом.
asOfstring (date-time)Общая верхняя граница даты ответа из meta.asOf; повторяйте на всех страницах. ISO-8601 с часовым поясом.
sortBystring= appearancesСортировка сводки. Подробности имеют фиксированный порядок с разнообразием исходных запросов и AI.
textappearancesanswersqueriesproviderCountlatestAtsortOrderstring= descНаправление сортировки сводки.
ascdesclimitinteger= 50Размер страницы.
offsetinteger= 0Смещение страницы.
Ответы
200Успешный ответ
400application/jsonНеверные параметры; компания не выбрана.
HTTP_400401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonКомпания недоступна в активном workspace.
HTTP_404503application/jsonИндекс подзапросов обновляется или отключён.
SERVICE_UNAVAILABLE/api/v1/queries/fanoutУспешный ответ
Получить запрос
/api/v1/queries/{id}Возвращает запрос с ответами от AI-ассистентов и найденными упоминаниями.
Параметры запроса
idstring (uuid)обязательноеID запроса
includeAnswersstring= trueВключить ответы с упоминаниями (по умолчанию true)
truefalseОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/queries/{id}Успешный ответ
Архивировать запрос
/api/v1/queries/{id}Перемещает запрос в архив. Данные сохраняются и могут быть восстановлены.
Параметры запроса
idstring (uuid)обязательноеID запроса
Ответы
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/{id}Успешно удалено
Изменить запрос
/api/v1/queries/{id}Меняет текст, тип, язык, регион, продукт, избранность и кластеры запроса. Изменение текста НЕ переопрашивает нейросети — уже полученные ответы остаются привязаны к запросу. Чтобы опросить заново, создайте новый запрос. Тело строгое: неизвестное поле → 400.
Параметры запроса
idstring (uuid)обязательноеТело запроса
textstringtypestringneutralcommercialinformationalcomparativereputationalbrandedlanguagestringregionstringISO 3166-1 alpha-2.
productIdstringnull — отвязать от продукта.
isFavoritebooleanlabelsstring[]ПОЛНЫЙ список кластеров: связки пересобираются.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/{id}Успешный ответ
Очередь опросов
/api/v1/queries/queueСостояние опроса запросов: по одному рану на каждую пару запрос-нейросеть. Позволяет отличить «ещё опрашивается» от «упало» и от «стоит без денег» — по одному лишь счётчику ответов это неразличимо.
Параметры запроса
statusstring= queued,onHold,failedГруппы статусов через запятую. По умолчанию все три.
companyIdstring (uuid)Сузить до одной компании. Без него — все компании аккаунта.
queryIdstring (uuid)Раны одного запроса
providerstringФильтр по нейросети
chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_modeincludeArchivedboolean= falseНе отсекать раны архивных запросов
limitinteger= 50Размер страницы
offsetinteger= 0Сдвиг
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/queries/queueУспешный ответ
Сводка очереди и прогноз стоимости
/api/v1/queries/queue/summaryСчётчики ранов, стоимость текущей очереди и остаток FoxCoin одним запросом. Пока queuedTotal > 0 — опрос идёт. onHold > 0 означает нехватку средств: такие раны сами не возобновятся даже после пополнения.
Параметры запроса
companyIdstring (uuid)Сузить до одной компании
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/queries/queue/summaryУспешный ответ
Массовое создание запросов с выбором нейросетей
/api/v1/queries/setupСоздаёт кластеры и запросы одной транзакцией и сразу ставит их в очередь опроса. Поле providers позволяет выбрать нейросети явно; без него используются настройки аккаунта. Для создания одного запроса можно использовать POST /api/v1/queries, который также принимает providers. Платно: каждый полученный ответ каждой нейросети списывает FoxCoin (см. GET /api/v1/billing/balance). Лимит 500 запросов на вызов.
Тело запроса
companyIdstringБез него берётся preferredCompanyId ключа (см. GET /api/v1/context)
clusterIdstringСуществующий кластер для гео-наследования; применяется ко всем элементам clusters без своего clusterId
providersstring[]Нейросети для опроса (слаги из GET /api/v1/sources). Без этого поля используются нейросети по умолчанию для аккаунта — у аккаунта без настроек это ChatGPT. Выбор через providers также поддерживается в POST /api/v1/queries.
clustersobject[]обязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED402application/jsonНедостаточно FoxCoin
HTTP_402404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/setupУспешный ответ
Вернуть опросы в очередь
/api/v1/queries/queue/resumeВозобновляет раны, стоящие на паузе. **Зачем.** Когда на балансе не хватает FoxCoin, ран уходит в ON_HOLD_NO_FUNDS. Воркеры такие раны не забирают, и пополнение баланса их НЕ оживляет: очередь стоит, пока планировщик через 45 дней не переведёт раны в CANCELLED. Со стороны это выглядит как «оплатил, а запросы не идут». Возобновление всегда явное, этим методом. **Как в это попасть.** Создать запросы при недостаточном балансе. Гейт срабатывает дважды — при постановке в очередь и при исполнении, поэтому часть ранов может стоять на паузе, даже если запрос частично отработал. Проверять: `GET /api/v1/queries/queue/summary` → `onHold`, либо `queue.status` запроса = `on_hold_no_funds`. **402 — не отказ навсегда:** денег хватает не на всю пачку. Пополните баланс либо повторите с `force: true` — тогда раны, на которые средств хватит, отработают, а остальные снова встанут на паузу.
Тело запроса
runIdsstring[]Точечно по id ранов
scopestringВсе раны на паузе
onHoldcompanyIdstringСузить scope до одной компании
forceboolean= falseВозобновить, даже если баланса не хватает на всю пачку
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED402application/jsonНедостаточно FoxCoin на всю пачку
HTTP_402404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/queue/resumeУспешный ответ
Снять опросы с очереди
/api/v1/queries/queue/cancelОтменяет раны, которые ещё не ушли в работу: ждущие (PENDING, RETRYING) и стоящие на паузе. Раны в статусе RUNNING не трогаются никогда — они уже у воркера, отмена привела бы к гонке. **Когда нужно.** Остановить лишний массовый прогон до того, как он спишет FoxCoin: списание происходит по факту прихода ответа, поэтому отменённый ран не стоит ничего. Либо разобрать зависший хвост, который не планируется оплачивать. Отмена обратима: снятый ран возвращается в очередь через `POST /api/v1/queries/queue/resume` с его `runId`.
Тело запроса
runIdsstring[]queryIdsstring[]Все отменяемые раны этих запросов
scopestringonHold — только паузы; queued — только активная очередь
onHoldqueuedcompanyIdstringСузить scope до одной компании
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/queue/cancelУспешный ответ
Автоподбор семантики
Автоподбор семантики: генерация запросов в черновики и их подтверждение. Генерация (1 FoxCoin за запрос) и платный опрос нейросетей (10 FoxCoin за ответ) — разные шаги.
Автоподбор семантики (без опроса нейросетей)
/api/v1/queries/autogenerateСервис сам подбирает запросы и кладёт их в ЧЕРНОВИКИ. Нейросети при этом НЕ опрашиваются. Это замена флагу isAutoGenerationEnabled: тот запускал генерацию и платный опрос одним движением, разделить их было нельзя. Здесь шаги разведены — опрос стартует только на POST /api/v1/query-drafts/approve. Стоимость: 1 FoxCoin за КАЖДЫЙ сгенерированный запрос (списывается по факту доставленных черновиков). Опрос оплачивается отдельно: 10 FoxCoin за ответ (запрос × нейросеть). Язык и страна: без полей language/region берутся региональные настройки компании (regionTargets, PUT /api/v1/companies/{id}), затем ru/RU. Для замера по нескольким странам передайте targets — по задаче на страну, язык по умолчанию государственный (AE → ar, IN → hi). Типы: без поля types берутся Company.autogenQueryTypes — по умолчанию commercial, informational, comparative, reputational. Сравнительные запросы («X vs Y») появляются, только если comparative есть в списке И у компании заведены конкуренты. По умолчанию отвечает 202 сразу, генерация идёт в фоне: прогресс читается через GET этого же адреса по clientToken. Короткая форма (region/language/city/includeDistricts) и targets взаимоисключающи: вместе они дают 400, потому что снаружи targets задать город отдельной страны нечему.
Тело запроса
companyIdstringБез поля — preferredCompanyId ключа.
productIdstringcountintegerобязательноеСколько запросов сгенерировать НА КАЖДЫЙ таргет. 1 FoxCoin за запрос.
typesstring[]Типы генерируемых запросов; count делится между ними поровну. Без поля берутся Company.autogenQueryTypes (по умолчанию включают comparative).
clustersstring[]Темы, по которым раскладываются запросы.
userWishesstringnamestringИмя задачи — видно в UI и в GET.
languagestringISO 639-1. Без поля — язык компании. Только БЕЗ targets.
regionstringISO 3166-1 alpha-2. Без поля — primary-страна компании (regionTargets), затем RU. Legacy-названия («russia») принимаются. Только БЕЗ targets.
citystringТолько БЕЗ targets.
includeDistrictsbooleanТолько БЕЗ targets.
targetsobject[]Замер по нескольким странам: по задаче на страну. Стоимость — сумма count всех таргетов. ВЗАИМОИСКЛЮЧАЮЩЕ с короткой формой: region / language / city / includeDistricts рядом с targets → 400 (внутри targets у каждой страны свои город и язык).
waitboolean= falsetrue — дождаться конца генерации (только для небольших пачек: 100+ запросов идут минутами).
clientTokenstringСвой маркер задачи; по нему потом читается прогресс.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED402application/jsonНедостаточно FoxCoin: поля required и balance в теле ошибки
HTTP_402404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED503application/jsonАвтоподбор не сконфигурирован на сервере
HTTP_503/api/v1/queries/autogenerateУспешный ответ
Статус задач автоподбора
/api/v1/queries/autogenerateПрогресс задач, запущенных POST /api/v1/queries/autogenerate. Опрашивайте до status = OK, затем читайте черновики через GET /api/v1/query-drafts. Черновики ещё идущей задачи (RUNNING) не подтверждаются намеренно — иначе подтвердится половина пачки.
Параметры запроса
runIdstring (uuid)Конкретная задача.
clientTokenstringЗадача по клиентскому маркеру из ответа POST.
limitinteger= 20Сколько последних задач вернуть.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/autogenerateУспешный ответ
Остановить задачу автоподбора
/api/v1/queries/autogenerate/cancelОтмена настоящая: не начатые пачки не выполняются, платите только за уже доставленные черновики. Ран переходит в CANCELLED, сгенерированные черновики остаются и их можно подтвердить.
Тело запроса
runIdstringобязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/queries/autogenerate/cancelУспешный ответ
Список черновиков запросов
/api/v1/query-draftsЧерновик ничего не стоит хранить и ничего не опрашивает: запросом он становится только через POST /api/v1/query-drafts/approve.
Параметры запроса
statusstringPENDING — ждут решения. По умолчанию все.
PENDINGAPPROVEDREJECTEDEXPIREDcompanyIdstring (uuid)Срез по компании.
typestringСрез по типу запроса.
neutralcommercialinformationalcomparativereputationalbrandedpageinteger= 1Страница, с 1.
limitinteger= 50Размер страницы.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/query-draftsУспешный ответ
Подтвердить черновики и запустить опрос
/api/v1/query-drafts/approveПЛАТНЫЙ ШАГ: подтверждённые черновики становятся запросами и уходят в выбранные нейросети — 10 FoxCoin за каждый ответ (запрос × нейросеть). 50 черновиков × 3 сети = 150 ответов = 1500 FoxCoin. Сначала вызовите с dryRun: true и покажите смету пользователю. Идемпотентно: повторный вызов с теми же draftIds не создаёт запросы дважды и не переопрашивает их. Черновики ещё идущей задачи автогенерации пропускаются (skippedRunning) — дождитесь status = OK.
Тело запроса
draftIdsstring[]обязательноеprovidersstring[]обязательноеНейросети для опроса. Каждая умножает стоимость.
dryRunbooleantrue — только смета, ничего не создаётся и не списывается.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED402application/jsonНедостаточно FoxCoin: поля required и balance в теле ошибки
HTTP_402404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/query-drafts/approveУспешный ответ
Отклонить черновики
/api/v1/query-drafts/rejectМягкое отклонение: черновик остаётся в базе со статусом REJECTED (аудит биллинга). Ничего не опрашивается. Возврата FoxCoin за генерацию нет — запросы уже сгенерированы.
Тело запроса
draftIdsstring[]обязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/query-drafts/rejectУспешный ответ
Ответы нейросетей
Ответы нейросетей пачкой: ссылки, упоминания, тональность.
Ответы нейросетей пачкой
/api/v1/answersЗамена циклу GET /api/v1/queries/{id} по каждому запросу: одна страница до 200 ответов со ссылками, упоминаниями и тональностью. Ссылки (links) — разобранные цитаты ЛЮБОЙ нейросети. Не путайте с сырым полем answer.sources: это payload скрейпера, он заполнен только у «Поиска с Алисой» и списком цитат не является. brandDomainCited — процитирован ли в ответе домен сайта компании. Поля упоминания: position — СМЕЩЕНИЕ СИМВОЛА в тексте ответа; массив отсортирован по нему, поэтому «каким по счёту назван бренд» — это РАНГ упоминания в массиве, а не значение position. sentiment (1 / 0 / -1) и sentimentScore (-1..1) берутся из тональности ВСЕГО ответа, поэтому у всех упоминаний одного ответа они одинаковы; sentimentScore = null, если тональность ещё не считалась. isOurs = false означает конкурента. Массивные параметры повторяются: ?companyId=a&companyId=b.
Параметры запроса
companyIdstring[]Компании (можно несколько).
productIdstring[]Продукты (можно несколько).
queryIdstring[]Только ответы этих запросов.
sourceIdstring[]Нейросети по id (GET /api/v1/sources).
providerstring[]Нейросети по слагу.
typestring[]Тип запроса, к которому относится ответ.
labelstring[]Слаги кластеров.
regionstring[]Регион запроса, ISO 3166-1 alpha-2. Legacy-названия тоже находятся.
languagestring[]Язык запроса.
createdAtFromstring (date-time)Дата создания ОТВЕТА, от (ISO 8601).
createdAtTostring (date-time)Дата создания ОТВЕТА, до (ISO 8601).
hasLinksbooleantrue — только ответы со ссылками, false — только без.
mentionsOursbooleantrue — только ответы, где упомянут бренд компании.
showArchivedboolean= falsetrue — включить ответы архивных запросов.
includestring= content,tonalityЧто добавить, через запятую: content, links, mentions, tonality.
limitinteger= 50Размер страницы.
offsetinteger= 0Смещение.
sortBystring= createdAtПоле сортировки.
createdAtdatesortOrderstring= descНаправление сортировки.
ascdescОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/answersУспешный ответ
География
Справочники стран, регионов, городов и языков.
Справочник стран
/api/v1/geo/countriesid из справочника нужны для regionTargets и defaultLanguageId компании и кластера, iso2 — для поля region запроса и автоподбора.
Параметры запроса
qstringПоиск по названию.
continentstringФильтр по континенту.
EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICAlimitinteger= 250Максимум записей.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/geo/countriesУспешный ответ
Справочник регионов страны
/api/v1/geo/regionsРегионы (области, штаты) конкретной страны. Обязателен один из countryId / countryIso2.
Параметры запроса
countryIso2stringДвухбуквенный код страны.
countryIdstring (uuid)UUID страны.
qstringПоиск по названию.
limitinteger= 100Максимум записей.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/geo/regionsУспешный ответ
Справочник городов страны
/api/v1/geo/citiesГорода конкретной страны. Обязателен один из countryId / countryIso2. cityId отсюда идёт в regionTargets компании и targets кластера.
Параметры запроса
countryIso2stringДвухбуквенный код страны.
countryIdstring (uuid)UUID страны.
regionIdstring (uuid)UUID региона.
qstringПоиск по названию.
limitinteger= 50Максимум записей.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/geo/citiesУспешный ответ
Справочник языков
/api/v1/geo/languagesid из справочника нужны для regionTargets и defaultLanguageId компании и кластера, iso2 — для поля region запроса и автоподбора.
Параметры запроса
qstringПоиск по названию или коду.
limitinteger= 200Максимум записей.
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/geo/languagesУспешный ответ
Кластеры запросов
Метки/кластеры запросов: список (с опциональным срезом по компании), создание с регионализацией
Список кластеров (меток запросов)
/api/v1/query-labelsВозвращает метки/кластеры запросов текущего workspace с количеством запросов в каждом. Параметр companyId делает срез по компании: возвращаются только кластеры, в которых есть запросы этой компании, а queryCount считается по запросам этой компании. lite=true — облегчённый ответ { items: [{ id, name, slug, queryCount }] } без статистики и sampleQueries.
Параметры запроса
companyIdstring (uuid)Срез по компании: только кластеры с запросами этой компании; queryCount — по её запросам.
litestringlite=true — облегчённый ответ { items: [{ id, name, slug, queryCount }] } без статистики.
truefalseoffsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
qstringCase-insensitive подстрока по имени метки.
sortstring= queryCount:descСортировка в формате field:direction.
queryCount:descqueryCount:ascname:ascname:desccreatedAt:desccreatedAt:asclastUsedAt:desclastUsedAt:aschasQueriesstringwith — только кластеры с запросами, without — пустые.
withwithoutminCountintegerМинимальное число запросов в кластере.
maxCountintegerМаксимальное число запросов в кластере.
createdFromstring (date-time)Метки, созданные не раньше указанной даты.
createdTostring (date-time)Метки, созданные не позже указанной даты.
lastUsedFromstring (date-time)Метки с lastUsedAt не раньше указанной даты.
lastUsedTostring (date-time)Метки с lastUsedAt не позже указанной даты.
includestringinclude=targets — догрузить геотаргеты кластера (country/city).
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/query-labelsУспешный ответ
Создать (или обновить) кластер с регионализацией
/api/v1/query-labelsFind-or-create по (slug, userId). Если кластер с таким slug существует — обновляется (имя, гео-настройки), targets пересоздаются. Опциональные companyId/productId принимаются, но на QueryLabel пока не персистятся.
Тело запроса
namestringобязательноеslugstringdescriptionstringcompanyIdstringproductIdstringdefaultLanguageIdstringdefaultLocalestringdefaultResponseLanguageIdstringgeoScopestringGLOBALCOUNTRYREGIONCITYinjectLocationModestringNONEAPPEND_PARENSAPPEND_NATURALPREPENDAI_REWRITEautogenStrategystringSHAREDPER_TARGETPER_TARGET_LOCALIZEDtargetsobject[]Ответы
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED409application/jsonКонфликт — ресурс уже существует
CONFLICT429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/query-labelsОшибка валидации входных данных
Упоминания
Просмотр упоминаний бренда
Список упоминаний
/api/v1/mentionsВозвращает упоминания бренда в ответах AI-ассистентов с полным контекстом.
Параметры запроса
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
sortBystring= createdAtcreatedAtpositionsentimentsortOrderstring= descПорядок сортировки
ascdesctimeRangestringВременной диапазон
24h7d30d90dallcreatedAtFromstring (date-time)Начало диапазона даты создания (ISO 8601)
createdAtTostring (date-time)Конец диапазона даты создания (ISO 8601)
companyIdstring (uuid)Фильтр по компании
productIdstring (uuid)Фильтр по продукту
competitorIdstring (uuid)Фильтр по конкуренту
answerIdstring (uuid)Фильтр по конкретному ответу
typestringТип упоминания
companyproductkeywordcompetitorsentimentstringТональность
positiveneutralnegativesearchstringПоисковый запрос (case-insensitive)
isOursstringТолько наши (true) или только конкурентов (false)
truefalseОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/mentionsУспешный ответ
Аналитика
Аналитика: конкуренты, тональность, ссылки, видимость бренда
Аналитика конкурентов
/api/v1/analytics/competitorsПолный сравнительный анализ вашей компании и конкурентов по упоминаниям в AI-ассистентах. Поддерживает фильтрацию по кластерам (slug), AI-провайдерам и периоду.
Параметры запроса
timeRangestring= 30dВременной диапазон
24h7d30dallfromstring (date-time)Начало кастомного диапазона (ISO 8601)
tostring (date-time)Конец кастомного диапазона (ISO 8601)
companyIdstring (uuid)ID компании
productIdstring (uuid)ID продукта
sourceIdstring[]ID AI-провайдеров
labelIdstring[]ID кластеров/лейблов
labelSlugstringSlug кластера. Массив: ?labelSlug=slug1&labelSlug=slug2
labelFilterModestring= orРежим фильтрации по лейблам
orandincludeDemostringВключить демо-данные
truefalseОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/competitorsУспешный ответ
Предпросмотр упоминаний
/api/v1/analytics/competitors/previewВозвращает конкретные ответы AI-ассистентов с упоминаниями для детального анализа. Поддерживает фильтрацию по кластерам, демо-данные, кастомный период и режим фильтрации лейблов. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).
Параметры запроса
sidestringобязательноеЧья сторона: наша компания или конкурент
ourcompetitorcompetitorNamestringИмя конкурента (если side=competitor)
mentionTypestring= bothТип упоминания
brandlinkbothoffsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
timeRangestring24h7d30dallcompanyIdstring (uuid)productIdstring (uuid)sourceIdstring[]labelIdstring[]includeMentionsstringВключить упоминания в ответ
truefalseincludeDemostringВключить демо-данные
truefalselabelFilterModestring= orЛогика фильтрации по кластерам
orandfromstring (date-time)Начало периода (ISO 8601)
tostring (date-time)Конец периода (ISO 8601)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/competitors/previewУспешный ответ
Аналитика тональности
/api/v1/analytics/tonalityПолный анализ тональности ответов AI-ассистентов: метрики качества, timeline, проблемные и лучшие ответы.
Параметры запроса
timeRangestring= 30d24h7d30d90dcompanyIdstring (uuid)productIdstring (uuid)queryTypestringТип запроса
neutralcomparativenegativesentimentstringФильтр по тональности
positiveneutralnegativesourceIdstring[]AI-провайдеры
labelSlugstring[]Кластеры/лейблы по slug
labelFilterModestring= ororandfromstring (date-time)tostring (date-time)includeDemostringtruefalseОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/tonalityУспешный ответ
Аналитика ссылок
/api/v1/analytics/linksАналитика ссылок из ответов AI-ассистентов: топ-домены, цитирование по провайдерам, timeline. Поддерживает фильтрацию по тональности, кластерам, типу запроса, порогам Impact/Overall Score и кастомный период. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).
Параметры запроса
timeRangestring24h7d30dallcompanyIdstring (uuid)productIdstring (uuid)includeDemostringtruefalselabelSlugstring[]sortDomainsBystringСортировка доменов
sentimentstringФильтр по тональности
positiveneutralnegativeminImpactnumberМинимальный порог Impact Score
minOverallnumberМинимальный порог Overall Score
presetstringПресет фильтрации
queryTypestringТип запроса
neutralnegativecomparativelabelstringSlug кластера
labelFilterModestring= orЛогика фильтрации
orandfromstring (date-time)Начало периода
tostring (date-time)Конец периода
chartOnlystringТолько данные для графика
truefalsecitationModestringРежим цитирования
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/linksУспешный ответ
Топ домены
/api/v1/analytics/links/top-domainsВозвращает наиболее цитируемые домены в ответах AI-ассистентов. Поддерживает фильтрацию по тональности, типу запроса, порогам Impact/Overall Score и демо-данные. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).
Параметры запроса
timeRangestring24h7d30dallcompanyIdstring (uuid)productIdstring (uuid)limitinteger= 10Количество доменов
includeDemostringВключить демо-данные
truefalsesentimentstringФильтр по тональности
positiveneutralnegativeminImpactnumberМинимальный порог Impact Score
minOverallnumberМинимальный порог Overall Score
queryTypestringТип запроса
neutralnegativecomparativeОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/links/top-domainsУспешный ответ
Видимость бренда
/api/v1/analytics/brand-visibilityTimeline видимости бренда в сравнении с конкурентами с настраиваемой гранулярностью. Поддерживает фильтрацию по кластерам (ID и slug), AI-провайдерам и режим логики фильтрации.
Параметры запроса
granularitystring= dayГранулярность временной оси
dayweekmonthtimeRangestring24h7d30dallcompanyIdstring (uuid)productIdstring (uuid)includeDemostringtruefalsefromstring (date-time)tostring (date-time)labelIdstringID кластера. Массив: ?labelId=id1&labelId=id2
labelSlugstringSlug кластера
labelFilterModestring= orЛогика фильтрации
orandsourceIdstringID AI-источника
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/brand-visibilityУспешный ответ
Динамика цитируемости
/api/v1/analytics/links/citation-timelineДоля ответов, где нас цитируют, против конкурентов, по дням. Считается по дневным роллапам, поэтому поддерживается только режим «цитирование в целом»: роллап не различает цитирование по URL и по домену.
Параметры запроса
companyIdstring (uuid)Компания. Без него подставляется preferredCompanyId ключа
productIdstringПродукт
timeRangestring24h | 7d | 30d | 90d | all
granularitystringРазрез динамики
tzstringЧасовой пояс
sourceIdstring[]Источники
labelSlugstring[]Кластеры
labelFilterModestringAND | OR
includeDemobooleanВключить демо-данные
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/analytics/links/citation-timelineУспешный ответ
Компании и продукты для фильтров
/api/v1/analytics/companies-productsКомпании аккаунта вместе с их продуктами — источник для селектора «компания → продукт». companyId здесь НЕ обязателен: без него возвращаются все компании, и это ровно то, зачем метод нужен.
Параметры запроса
companyIdstring (uuid)Сузить до одной компании
includeDemobooleanВключить демо-данные
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/companies-productsУспешный ответ
Ссылки
Домены и ссылки из AI-ответов
Домены и ссылки
/api/v1/linksДвухуровневая таблица доменов и ссылок из ответов AI-ассистентов с сортировкой и фильтрацией. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context). Каждый домен и URL возвращают primaryCategory (код основной категории или null) и categoryTags (все тематические теги и роли площадки). URL наследует классификацию своего домена. Для названий и долей категорий используйте GET /api/v1/links/categories.
Параметры запроса
pageinteger= 1Номер страницы
pageSizeinteger= 50Размер страницы
sortBystring= lastMentionedlastMentionedmentionCountanswerCountourMentionCountcompetitorMentionCountdomaintrustRankdomainLinkssortDirstring= descascdescsearchstringПоисковый запрос (case-insensitive)
searchFieldstringПоле для поиска
domainurltitletimeRangestring= 7d24h7d30d90dallfromstring (date-time)tostring (date-time)companyIdstring (uuid)productIdstring (uuid)sentimentstringpositiveneutralnegativequeryTypestringneutralcommercialinformationalcomparativereputationalbrandednegativegeneralproviderstring[]AI-провайдеры
activestringТолько активные ссылки
truefalsedomainsOnlystringТолько домены (без подссылок)
truefalsedomainstringПодссылки конкретного домена
labelstring[]Кластеры/лейблы
includeDemostringtruefalsedomainCategorystringКод основной категории: medicine, подкатегории medicine.clinics или unclassified. Справочник: GET /api/v1/links/categories?includeEmpty=true. Теги site_role не являются категориями.
labelFilterModestring= orОбъединение кластеров ИЛИ/И.
orandmentionAnswerstringУпоминания в ответах AI.
ourscompetitorsmentionArticlestringУпоминания в тексте источника.
ourscompetitorsparsedstringНаличие содержательного спарсенного текста источника.
truefalseminImpactnumberМинимальное влияние ответа на бренд; 0 также применяется.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/linksУспешный ответ
Категории площадок: доли и справочник
/api/v1/links/categoriesКомпания обязательна: передайте companyId или используйте preferredCompanyId ключа (см. GET /api/v1/context). Доступ проверяется в активном workspace. Категории и подкатегории с названиями, числом цитирований, доменов и долями. Применяются те же фильтры, что в GET /api/v1/links. Доли считаются по всей отфильтрованной выборке; страницы списка на них не влияют. Каждое цитирование учитывается один раз по основной категории домена. Категории без данных скрыты; includeEmpty=true возвращает полный справочник. Нераспределённые домены остаются в unclassified и в знаменателе долей. Роли площадок site_role.* хранятся отдельно в categoryTags и не увеличивают доли. Для перехода к ссылкам передайте value как domainCategory, сохранив остальные фильтры. Неизвестные параметры, неверные даты и значения фильтров возвращают HTTP 400.
Параметры запроса
searchstringПоисковый запрос (case-insensitive)
searchFieldstringПоле для поиска
domainurltitletimeRangestring= 7d24h7d30d90dallfromstringГраница периода: дата YYYY-MM-DD или ISO-8601 с часовым поясом. from переопределяет timeRange.
tostringГраница периода: дата YYYY-MM-DD или ISO-8601 с часовым поясом. from переопределяет timeRange.
companyIdstring (uuid)productIdstring (uuid)sentimentstringpositiveneutralnegativequeryTypestringneutralcommercialinformationalcomparativereputationalbrandednegativegeneralproviderstring[]AI-провайдеры
activestringТолько активные ссылки
truefalsedomainstringПодссылки конкретного домена
labelstring[]Кластеры/лейблы
domainCategorystringКод основной категории: medicine, подкатегории medicine.clinics или unclassified. Справочник: GET /api/v1/links/categories?includeEmpty=true. Теги site_role не являются категориями.
labelFilterModestring= orОбъединение кластеров ИЛИ/И.
orandmentionAnswerstringУпоминания в ответах AI.
ourscompetitorsmentionArticlestringУпоминания в тексте источника.
ourscompetitorsparsedstringНаличие содержательного спарсенного текста источника.
truefalseminImpactnumberМинимальное влияние ответа на бренд; 0 также применяется.
includeEmptyboolean= falseДобавить категории и подкатегории с нулевыми счётчиками: полный тематический справочник.
Ответы
200Успешный ответ
400application/jsonНеверная категория, дата, фильтр или includeEmpty.
HTTP_400401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonКомпания недоступна в активном workspace.
HTTP_404/api/v1/links/categoriesУспешный ответ
Опции фильтров
/api/v1/links/filter-optionsВозвращает доступные значения для фильтров таблицы ссылок: провайдеры и лейблы. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/links/filter-optionsУспешный ответ
Реклама
Рекламные данные из AI-ответов
Рекламные данные
/api/v1/advertisingАналитика рекламных и промо-блоков в ответах AI-ассистентов. Поддерживает пагинацию, поиск по домену/URL, фильтрацию по кластерам, типу промо, периоду и сортировку. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).
Параметры запроса
timeRangestring24h7d30dallcompanyIdstring (uuid)productIdstring (uuid)includeDemostringtruefalsepageinteger= 1Номер страницы
pageSizeinteger= 50Размер страницы
searchstringПоиск по домену или URL
searchFieldstringПоле поиска
domainurltitlelabelstringSlug кластера. Массив: ?label=slug1&label=slug2
promoTypestringТип промо-блока
sortBystringПоле сортировки
sortDirstringНаправление сортировки
ascdescfromstring (date-time)Начало периода (ISO 8601)
tostring (date-time)Конец периода (ISO 8601)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/advertisingУспешный ответ
Предпросмотр рекламных блоков
/api/v1/advertising/previewДетализация к сводке /api/v1/advertising: какие промо показывались и в каких ответах.
Параметры запроса
domainstringобязательноеДомен промо. ОБЯЗАТЕЛЕН, иначе 400
companyIdstring (uuid)Компания. Без него подставляется preferredCompanyId ключа
productIdstringПродукт
promoTypestringours | competitor | other
ourscompetitorothertimeRangestring24h | 7d | 30d | 90d | all
labelstring[]Кластеры
labelFilterModestringAND | OR
limitinteger= 201..50
offsetinteger= 0Сдвиг
includeDemobooleanВключить демо-данные
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/advertising/previewУспешный ответ
Фабрика контента
Контент-фабрика: задачи, теги, обогащение, генерация планов и статей, детекция инсайтов
Список задач
/api/v1/factory/tasksВозвращает список задач контент-фабрики с фильтрацией, пагинацией и сортировкой.
Параметры запроса
companyIdstring (uuid)Фильтр по компании
statusstring[]Фильтр по статусу (можно несколько: ?status=TODO&status=IN_PROGRESS)
typestring[]Фильтр по типу задачи (можно несколько)
prioritystring[]Фильтр по приоритету (можно несколько)
searchstringПоиск по названию и описанию задачи
tagIdstring (uuid)Фильтр по тегу
aiGeneratedbooleanФильтр: только AI-сгенерированные задачи
sortBystring= createdAtcreatedAtupdatedAtprioritystatuspositionsortOrderstring= descПорядок сортировки
ascdescoffsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/factory/tasksУспешный ответ
Создать задачу
/api/v1/factory/tasksСоздаёт новую задачу контент-фабрики.
Тело запроса
titlestringобязательноеНазвание задачи
companyIdstringобязательноеID компании
typestringобязательноеТип задачи
NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDYprioritystring= MEDIUMПриоритет
CRITICALHIGHMEDIUMLOWdescriptionstringОписание задачи
targetKeywordsstring[]Целевые ключевые слова (макс. 20)
targetProvidersstring[]Целевые AI-провайдеры
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasksУспешный ответ
Получить задачу
/api/v1/factory/tasks/{id}Возвращает полную информацию о задаче контент-фабрики.
Параметры запроса
idstring (uuid)обязательноеID задачи
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/factory/tasks/{id}Успешный ответ
Обновить задачу
/api/v1/factory/tasks/{id}Частичное обновление задачи контент-фабрики.
Параметры запроса
idstring (uuid)обязательноеID задачи
Тело запроса
statusstringIDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSEDprioritystringCRITICALHIGHMEDIUMLOWtitlestringdescriptionstringtagIdsstring[]Массив ID тегов для привязки
targetKeywordsstring[]targetProvidersstring[]dueDatestringДедлайн задачи
metadataobjectПроизвольные метаданные задачи
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasks/{id}Успешный ответ
Архивировать задачу
/api/v1/factory/tasks/{id}Архивирование задачи. Данные сохраняются, но задача переходит в статус DISMISSED.
Параметры запроса
idstring (uuid)обязательноеID задачи
Ответы
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasks/{id}Успешно удалено
Обогатить задачу
/api/v1/factory/tasks/{id}/enrichRAG-поиск по базе источников, анализ конкурентов, AI-рекомендации.
Параметры запроса
idstring (uuid)обязательноеID задачи
Тело запроса
topicstringобязательноеТема для обогащения
descriptionstringДополнительное описание
keywordsstring[]Ключевые слова для RAG-поиска
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasks/{id}/enrichУспешный ответ
Сгенерировать план
/api/v1/factory/tasks/{id}/planГенерация плана статьи на основе обогащённых данных: структура, заголовки, ключевые тезисы, tone of voice.
Параметры запроса
idstring (uuid)обязательноеID задачи
Тело запроса
promptstringДополнительные инструкции для генерации плана
topicIdstringID выбранной темы (из suggest topics)
topicTitlestringНазвание темы
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasks/{id}/planУспешный ответ
Сгенерировать статью
/api/v1/factory/tasks/{id}/articleГенерация статьи по плану (SSE-стриминг). Content-Type: text/event-stream.
Параметры запроса
idstring (uuid)обязательноеID задачи
Тело запроса
planIdstringID плана для генерации статьи
articleLengthstring= mediumДлина статьи: short (~1000 слов), medium (~2000), long (~3500)
shortmediumlongОтветы
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasks/{id}/articleНе авторизован — отсутствует или невалидный токен
Версии контента
/api/v1/factory/tasks/{id}/versionsВозвращает список версий контента (планов, статей, брифов) для задачи.
Параметры запроса
idstring (uuid)обязательноеID задачи
typestringФильтр по типу контента
planarticlebriefplanIdstringФильтр по ID плана
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/factory/tasks/{id}/versionsУспешный ответ
Аналитика задачи
/api/v1/factory/tasks/{id}/analyticsВозвращает аналитику по задаче: статистика обогащения, генераций, публикаций.
Параметры запроса
idstring (uuid)обязательноеID задачи
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/factory/tasks/{id}/analyticsУспешный ответ
Предложить темы
/api/v1/factory/tasks/{id}/topicsГенерация 10 тем на основе данных задачи.
Параметры запроса
idstring (uuid)обязательноеID задачи
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/tasks/{id}/topicsУспешный ответ
Список публикаций
/api/v1/factory/publicationsВозвращает список публикаций контент-фабрики с пагинацией.
Параметры запроса
companyIdstring (uuid)Фильтр по компании
offsetinteger= 0Смещение для пагинации
limitinteger= 20Количество записей на страницу
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/factory/publicationsУспешный ответ
Детекция инсайтов
/api/v1/factory/insightsЗапуск детекторов (15 типов): content gaps, competitor wins, white space, reputation risks и др.
Тело запроса
companyIdstringобязательноеID компании
insightTypestringТип инсайта (если не указан — запуск всех детекторов)
CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDINGlimitintegerМаксимальное количество инсайтов
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/insightsУспешный ответ
Настройки фабрики
/api/v1/factory/settingsВозвращает текущие настройки контент-фабрики пользователя.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/factory/settingsУспешный ответ
Обновить настройки
/api/v1/factory/settingsОбновление настроек контент-фабрики (deep merge).
Тело запроса
settingsobjectобязательноеОбъект настроек для deep merge с текущими
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/settingsУспешный ответ
Карта бренда
/api/v1/factory/brand-cardЧтение карты бренда — дерева markdown-документов компании (знания о бренде, учитываются при генерации контента). Три режима: без доп. параметров — вся карта одним markdown (манифест → core-файлы → связанные ссылками → остальные; приватные блоки ```private вырезаны; лимит ~12 000 символов); mode=index — манифест + список файлов с path, id, isCore и исходящими ссылками (граф связей); path=... — один файл: content (ссылки [Имя](brandcard://id) сохранены дословно) + links с резолвом каждой ссылки в путь.
Параметры запроса
companyIdstring (uuid)обязательноеID компании
modestringindex — вернуть манифест и список файлов вместо полной карты
indexpathstringПуть файла как в индексе (например "main / settings.md") — вернуть один файл. Регистр не важен
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/factory/brand-cardУспешный ответ
Создать/обновить файл карты
/api/v1/factory/brand-cardСоздаёт или полностью перезаписывает файл карты бренда по пути; недостающие папки создаются автоматически, без расширения добавляется .md. Чтобы сослаться на другой файл карты, вставьте в markdown ссылку [Имя](brandcard://<id из индекса>) — она живёт по id (переживает переименование и перенос) и поднимает приоритет целевого файла при генерации. Существующие brandcard://-ссылки при редактировании сохраняйте дословно. Личные заметки и опции оборачивайте в блок ```private — они не отправляются в нейросети.
Тело запроса
companyIdstringобязательноеID компании
pathstringобязательноеПуть файла, сегменты через "/", например "products / pricing.md"
contentstringобязательноеПолный markdown файла (перезаписывает текущее содержимое)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/brand-cardУспешный ответ
Удалить файл/папку карты
/api/v1/factory/brand-cardУдаляет файл или папку карты бренда по пути (папка — каскадно со всем содержимым). Служебный каркас (instruction.md, README.md, core-файлы) удалить нельзя — редактируйте его через POST. После удаления файла ссылки на него становятся висячими: в индексе пропадают из links, при чтении файла отдаются с path=null.
Параметры запроса
companyIdstring (uuid)обязательноеID компании
pathstringобязательноеПуть файла или папки (как в индексе)
Ответы
204Успешно удалено
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/factory/brand-cardУспешный ответ
Баланс и расходы
Баланс FoxCoin и история операций
Баланс FoxCoin и прейскурант
/api/v1/billing/balanceОстаток, оборот и цены операций. Кошелёк общий на аккаунт: участники команды тратят из пула владельца. Прейскурант отдаётся здесь, чтобы не зашивать цены в код интеграции.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/billing/balanceУспешный ответ
История списаний и пополнений
/api/v1/billing/transactionsЖурнал операций кошелька. У списаний за ответы поле query показывает, за какой именно запрос списано.
Параметры запроса
typestringФильтр по типу операции
ANSWER_CHARGEQUERY_GENERATIONBRAND_CARD_GENERATIONTASK_ENRICHMENTARTICLE_GENERATIONCONTENT_PLANTOPIC_SUGGESTIONFACT_CHECKTOPUPBONUSREFUNDMANUAL_ADJUSTMENTSUBSCRIPTION_CREDITAPI_CALL_FREEfromstring (date-time)Начало окна, ISO-дата (включительно)
tostring (date-time)Конец окна, ISO-дата (включительно)
limitinteger= 50Размер страницы
offsetinteger= 0Сдвиг
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/billing/transactionsУспешный ответ
Справочники
Справочники и контекст ключа
Справочник нейросетей
/api/v1/sourcesКакие ассистенты доступны для опроса и какие из них подставляются по умолчанию. Значение value — то, что принимает providers в POST /api/v1/queries/setup. Имена вне этого списка молча отбрасываются при постановке в очередь.
Параметры запроса
includeUnpollableboolean= falseДобавить claude (легаси-очередь, в контуре не опрашивается)
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/sourcesУспешный ответ
Контекст ключа
/api/v1/contextС чего стоит начинать интеграцию: какому аккаунту принадлежит ключ, какие у него права, какие компании и продукты доступны и какая компания подставляется по умолчанию.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/contextУспешный ответ
AI-трафик
Переходы на сайт из ответов нейросетей (Яндекс.Метрика)
AI-трафик
/api/v1/analytics/metrika/ai-trafficПереходы на сайт из ответов нейросетей: сколько визитов принесла каждая сеть и как это менялось. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
timeRangestring24h | 7d | 30d | 90d | all
fromstringНачало периода, ISO-дата
tostringКонец периода, ISO-дата
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/ai-trafficУспешный ответ
Посетители из нейросетей
/api/v1/analytics/metrika/visitorsВизиты с AI-источником и поведение на сайте: глубина просмотра, цели, повторные заходы. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
timeRangestring24h | 7d | 30d | 90d | all
fromstringНачало периода, ISO-дата
tostringКонец периода, ISO-дата
hasGoalsbooleanТолько визиты с достигнутыми целями
includeSyntheticbooleanВключить синтетический трафик
pvMinintegerМинимум просмотров страниц
pvMaxintegerМаксимум просмотров страниц
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/visitorsУспешный ответ
Воронка AI-трафика
/api/v1/analytics/metrika/traffic-funnelПуть от перехода из ответа нейросети до целевого действия. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
timeRangestring24h | 7d | 30d | 90d | all
fromstringНачало периода, ISO-дата
tostringКонец периода, ISO-дата
hasGoalsbooleanТолько визиты с достигнутыми целями
includeSyntheticbooleanВключить синтетический трафик
pvMinintegerМинимум просмотров страниц
pvMaxintegerМаксимум просмотров страниц
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/traffic-funnelУспешный ответ
Упоминания против трафика
/api/v1/analytics/metrika/correlationСопоставляет динамику упоминаний бренда с динамикой реальных переходов: даёт ли рост видимости рост трафика. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
companyIdstring (uuid)Компания. Без него подставляется preferredCompanyId ключа
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
timeRangestring24h | 7d | 30d | 90d | all
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/correlationУспешный ответ
Цели Метрики
/api/v1/analytics/metrika/goalsСправочник целей счётчика — что стоит за параметром hasGoals в остальных методах. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
includeInactivebooleanВключить неактивные цели
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/goalsУспешный ответ
Сводка по синтетическому трафику
/api/v1/analytics/metrika/synthetic/summaryДоля ботовых и неорганических визитов, чтобы они не искажали выводы по AI-трафику. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
timeRangestring24h | 7d | 30d | 90d | all
fromstringНачало периода, ISO-дата
tostringКонец периода, ISO-дата
filterstringФильтр классификации
hasGoalsbooleanТолько визиты с достигнутыми целями
pvMinintegerМинимум просмотров страниц
pvMaxintegerМаксимум просмотров страниц
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/synthetic/summaryУспешный ответ
Список синтетических визитов
/api/v1/analytics/metrika/synthetic/listПостраничная детализация к сводке: конкретные визиты с признаками синтетики. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.
Параметры запроса
integrationIdstring (uuid)Счётчик Метрики. Без него — все подключённые счётчики аккаунта
timeRangestring24h | 7d | 30d | 90d | all
fromstringНачало периода, ISO-дата
tostringКонец периода, ISO-дата
filterstringФильтр классификации
qstringПоиск
qScopestringОбласть поиска
hasRevenuebooleanТолько с доходом
returningOnlybooleanТолько вернувшиеся
pageintegerСтраница
pageSizeintegerРазмер страницы
sortBystringПоле сортировки
sortOrderstringasc | desc
hasGoalsbooleanТолько визиты с достигнутыми целями
pvMinintegerМинимум просмотров страниц
pvMaxintegerМаксимум просмотров страниц
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/analytics/metrika/synthetic/listУспешный ответ
Подключённые счётчики
/api/v1/integrations/metrika/listС этого метода начинается работа с AI-трафиком: возвращает integrationId для остальных методов раздела.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/integrations/metrika/listУспешный ответ
Состояние интеграции
/api/v1/integrations/metrika/statusПодключена ли Метрика, когда была синхронизация и не истёк ли доступ. Пустая выдача методов раздела объясняется здесь.
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/integrations/metrika/statusУспешный ответ
Коммерс
Товарные карточки в ответах нейросетей
Коммерс-аналитика
/api/v1/analytics/commerceТоварные карточки, которые нейросети показывают вместе с текстом ответа. view=summary — доля ответов с карточками и динамика по сетям; sellers — топ продавцов и доменов; brands — карточки нашего бренда против конкурентов; cards — постраничный список.
Параметры запроса
viewstring= summarysummary | sellers | brands | cards
summarysellersbrandscardscompanyIdstring (uuid)Компания. Без него подставляется preferredCompanyId ключа
productIdstring[]Можно передать несколько
timeRangestring24h | 7d | 30d | 90d | all
granularitystringРазрез динамики
tzstringЧасовой пояс
labelIdstring[]Кластеры
labelSlugstring[]Кластеры по slug
labelFilterModestringAND | OR
sourceIdstring[]Источники
queryTypestring[]Типы запросов
includeDemobooleanВключить демо-данные
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/analytics/commerceУспешный ответ
Отслеживаемые товары
/api/v1/commerce/productsНоменклатура для сопоставления с карточками в ответах. Без неё раздел «Коммерс» показывает продавцов и домены, но не «наш товар против чужого».
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/commerce/productsУспешный ответ
Добавить товар
/api/v1/commerce/productsОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/commerce/productsУспешный ответ
Мониторинг
Регулярный опрос запросов по расписанию
Запросы на мониторинге
/api/v1/favorite-queriesСписок запросов, поставленных на регулярный опрос.
Параметры запроса
searchstringПоиск по тексту
activebooleanТолько включённые
Ответы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED/api/v1/favorite-queriesУспешный ответ
Поставить запрос на мониторинг
/api/v1/favorite-queriesОбычный POST /api/v1/queries опрашивает нейросети ОДИН раз. Регулярный опрос — это отдельная сущность, и создаётся она здесь. Создание записи опрос ещё не запускает: расписание задаётся вторым шагом, через POST /api/v1/favorite-queries/{id}/assignments. Каждый опрос по расписанию платный: 10 FoxCoin за ответ КАЖДОЙ нейросети. Интервал 60 минут по трём сетям — это 72 ответа в сутки. При нехватке средств опросы уходят на паузу и сами не возобновятся (POST /api/v1/queries/queue/resume).
Тело запроса
textstringобязательноеtypestringобязательноеcompanyIdstringproductIdstringlanguagestring= ruregionstring= RUisActiveboolean= truetagsstring[]Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/favorite-queriesУспешный ответ
Запись мониторинга
/api/v1/favorite-queries/{id}Параметры запроса
idstring (uuid)обязательноеОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/favorite-queries/{id}Успешный ответ
Изменить запись
/api/v1/favorite-queries/{id}Текст, компания, теги, isActive. Снять с опроса без удаления — isActive: false.
Параметры запроса
idstring (uuid)обязательноеОтветы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/favorite-queries/{id}Успешный ответ
Снять с мониторинга
/api/v1/favorite-queries/{id}Удаляет запись вместе с расписанием: следующего опроса не будет. Уже полученные ответы и упоминания остаются — они принадлежат запросу, а не подписке.
Параметры запроса
idstring (uuid)обязательноеОтветы
204Успешно удалено
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/favorite-queries/{id}Успешный ответ
Расписание опроса
/api/v1/favorite-queries/{id}/assignmentsПараметры запроса
idstring (uuid)обязательноеОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND/api/v1/favorite-queries/{id}/assignmentsУспешный ответ
Задать расписание
/api/v1/favorite-queries/{id}/assignmentsИменно здесь запрос начинает опрашиваться регулярно: запись без расписания ничего не делает. Расписание одно на запись, повторный вызов его перезаписывает. Каждый опрос по расписанию платный: 10 FoxCoin за ответ КАЖДОЙ нейросети. Интервал 60 минут по трём сетям — это 72 ответа в сутки. При нехватке средств опросы уходят на паузу и сами не возобновятся (POST /api/v1/queries/queue/resume).
Параметры запроса
idstring (uuid)обязательноеТело запроса
providersstring[]обязательноеСписок: GET /api/v1/sources
frequencyMinutesintegerобязательноеИнтервал между опросами
isEnabledboolean= trueПауза без удаления расписания
timezonestring= Europe/MoscowВ нём считаются daysOfWeek и hoursWindow
daysOfWeekinteger[]1..7, пусто = каждый день
hoursWindowobjectОкно часов, вне которого опрос не идёт
modelobjectКарта «нейросеть → модель»
Ответы
200Успешный ответ
400application/jsonОшибка валидации входных данных
VALIDATION_ERROR401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/favorite-queries/{id}/assignmentsУспешный ответ
Опросить сейчас
/api/v1/favorite-queries/{id}/run-nowВнеочередной опрос, не дожидаясь расписания и не сдвигая его. Платно на общих основаниях.
Параметры запроса
idstring (uuid)обязательноеОтветы
200Успешный ответ
401application/jsonНе авторизован — отсутствует или невалидный токен
UNAUTHORIZED404application/jsonРесурс не найден
NOT_FOUND429application/jsonПревышен лимит запросов (IP: 120 req/min, per-user: 60 req/min)
RATE_LIMIT_EXCEEDED/api/v1/favorite-queries/{id}/run-nowУспешный ответ