v1.2.0

brandfound. API

API для отслеживания упоминаний бренда в AI-ассистентах (ChatGPT, Gemini, Claude, Perplexity). Управление компаниями, продуктами, конкурентами, запросами, упоминаниями и аналитикой.

Базовый URL

https://app.brandfound.ai/api/v1

Playground

Нажмите в панели запроса, чтобы открыть интерактивный Playground. Выберите API ключ, укажите параметры и отправьте запрос прямо из документации.

Быстрый старт

curl -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  https://app.brandfound.ai/api/v1/companies

Успешный ответ

{
  "success": true,
  "data": {
    "...": "..."
  }
}

Ошибка

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Не найдено"
  }
}

Лимиты запросов

По IP-адресу120 / мин

По пользователю60 / мин

Коды ошибок

401

UNAUTHORIZEDНеверная авторизация

403

FORBIDDENНедостаточно прав

404

NOT_FOUNDРесурс не найден

400

VALIDATION_ERRORОшибка валидации

429

RATE_LIMIT_EXCEEDEDПревышен лимит

500

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. Раньше без него ответ объединял все компании аккаунта.

Для AI-ассистентов

Скопируйте инструкцию по API и передайте её AI-ассистенту (ChatGPT, Claude, Gemini и др.) — он сможет формировать запросы к brandfound. API за вас. API ключ не включается в копируемый текст.

Рядом с каждым методом и разделом есть — копирует описание конкретного метода или всей категории.

API ключ не включается — вставьте его отдельно или используйте Playground.

Аутентификация

Все запросы к API требуют авторизации. Создайте API ключ в разделе Настройки → API ключи. Ключи имеют префикс gfx_.

Bearer Token

Рекомендуемый

Передайте ключ в заголовке Authorization каждого запроса.

Session Cookie

Веб-приложение автоматически использует cookie session-token. Дополнительная настройка не требуется.

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

curl -X GET "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

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

{
  "success": true,
  "data": [
    {
      "id": "comp_123",
      "name": "Моя компания",
      "slug": "my-company"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Окружения

Окружения (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

GET/api/v1/workspaces

curl -X GET "https://app.brandfound.ai/api/v1/workspaces" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "workspaces": [
      {
        "accountId": "example_accountId",
        "role": "owner",
        "ownerName": "example_ownerName",
        "ownerEmail": "example_ownerEmail",
        "companiesCount": 0,
        "isCurrent": true,
        "teamRoleName": "example_teamRoleName",
        "teamRoleKey": "example_teamRoleKey"
      }
    ],
    "currentAccountId": "example_currentAccountId",
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId"
  }
}

Успешный ответ

Переключить активное окружение для текущего API key

/api/v1/workspaces/switch

Обновляет ApiKey.activeAccountId. Эффект персистентный — применяется ко ВСЕМ следующим запросам этого ключа (в том числе из других MCP-клиентов). При accountId=null сбрасывает override и возвращает поведение к токеновскому accountId. Побочный эффект: preferredCompanyId сбрасывается в null (привязана к старому окружению). Только для аутентификации через API key.

Тело запроса

accountIdstringrequired

UUID workspace для переключения. null = сбросить активный override и вернуться к accountId, выданному при OAuth.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

403application/json

Необходима авторизация

UNAUTHORIZED

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/workspaces/switch

curl -X POST "https://app.brandfound.ai/api/v1/workspaces/switch" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "7b2f1d4e-8c9a-4e5b-b6c2-3d7a1f8e9c4b"
}'

{
  "success": true,
  "data": {
    "apiKeyId": "example_apiKeyId",
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId",
    "effectiveAccountId": "example_effectiveAccountId",
    "preferredCompanyIdReset": true
  }
}

Успешный ответ

Компании

Управление компаниями

Список компаний

/api/v1/companies

Возвращает список компаний пользователя с продуктами, конкурентами и ключевыми словами.

Параметры запроса

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

sortBystring= createdAt

createdAtupdatedAtnamelastUsedAt

sortOrderstring= desc

Порядок сортировки

ascdesc

searchstring

Поисковый запрос (case-insensitive)

categoryIdstring (uuid)

Фильтр по категории

countrystring

Фильтр по стране

createdAtFromstring (date-time)

Начало диапазона даты создания (ISO 8601)

createdAtTostring (date-time)

Конец диапазона даты создания (ISO 8601)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/companies

curl -X GET "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "clx1abc2d0001abcdef123456",
      "name": "Samsung",
      "description": "Samsung Electronics",
      "url": "https://samsung.com",
      "country": "South Korea",
      "categoryId": "cat-uuid-001",
      "lastUsedAt": "2026-04-06T10:00:00.000Z",
      "createdAt": "2026-01-15T08:00:00.000Z",
      "products": [
        {
          "id": "prod-001",
          "name": "Galaxy S25"
        }
      ],
      "competitors": [
        {
          "id": "comp-001",
          "name": "Apple"
        }
      ],
      "keywords": [],
      "category": {
        "id": "cat-uuid-001",
        "name": "Electronics"
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Создать компанию

/api/v1/companies

Создает новую компанию. Лимит зависит от тарифного плана.

Тело запроса

namestringrequired

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2 («AE»). Legacy-названия («russia») принимаются и нормализуются. Предпочтительнее regionTargets — это поле легаси.

synonymsstring[]

Синонимы/альтернативные названия (макс. 20)

regionTargetsobject[]

Страны и города замера. ПОЛНОЕ состояние: старые таргеты пересоздаются. Primary-таргет задаёт страну и язык автоподбора семантики.

defaultLanguageIdstring

Язык генерируемых запросов (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Язык, на котором должна отвечать нейросеть.

defaultLocalestring

BCP-47, например «ar-AE».

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/companies

curl -X POST "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Samsung",
  "description": "Samsung Electronics — мировой лидер в области электроники",
  "url": "https://samsung.com",
  "country": "South Korea",
  "synonyms": [
    "Samsung Electronics",
    "Самсунг"
  ]
}'

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Samsung",
    "description": "Samsung Electronics — мировой лидер в области электроники",
    "url": "https://samsung.com",
    "categoryId": null,
    "country": "South Korea",
    "synonyms": [
      "Samsung Electronics",
      "Самсунг"
    ],
    "isAutoGenerationEnabled": true,
    "lastUsedAt": null,
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

Успешный ответ

Получить компанию

/api/v1/companies/{id}

Возвращает полную информацию о компании, включая продукты, конкурентов и ключевые слова.

Параметры запроса

idstring (uuid)required

ID компании

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/companies/{id}

curl -X GET "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Samsung",
    "description": "Samsung Electronics — мировой лидер в области электроники",
    "url": "https://samsung.com",
    "categoryId": null,
    "country": "South Korea",
    "synonyms": [
      "Samsung Electronics",
      "Самсунг"
    ],
    "isAutoGenerationEnabled": true,
    "lastUsedAt": "2026-04-06T18:00:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-06T18:00:00.000Z",
    "products": [
      {
        "id": "prod-001",
        "name": "Galaxy S25",
        "description": "Flagship smartphone 2026",
        "url": "https://samsung.com/galaxy-s25",
        "keywords": [
          {
            "id": "kw-001",
            "text": "galaxy s25"
          }
        ],
        "competitors": [
          {
            "id": "comp-001",
            "name": "iPhone 16",
            "keywords": [
              {
                "id": "kw-002",
                "text": "iphone 16"
              }
            ]
          }
        ]
      }
    ],
    "competitors": [
      {
        "id": "comp-002",
        "name": "Apple",
        "url": "https://apple.com",
        "keywords": [
          {
            "id": "kw-003",
            "text": "apple"
          }
        ]
      }
    ],
    "keywords": [
      {
        "id": "kw-004",
        "text": "samsung"
      }
    ],
    "category": {
      "id": "cat-001",
      "name": "Электроника"
    }
  }
}

Успешный ответ

Обновить компанию

/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)required

ID компании

Тело запроса

namestring

descriptionstring

urlstring

categoryIdstring

countrystring

synonymsstring[]

isAutoGenerationEnabledboolean

УСТАРЕЛО и ИГНОРИРУЕТСЯ при значении true. Это флаг снесённого планировщика: он генерировал запросы и тем же движением ставил их в платный опрос. Автоподбор без опроса — POST /api/v1/queries/autogenerate.

regionTargetsobject[]

defaultLanguageIdstring

Язык генерируемых запросов (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Язык, на котором должна отвечать нейросеть.

defaultLocalestring

BCP-47, например «ar-AE».

autogenQueryTypesstring[]

Типы запросов автоподбора. По умолчанию commercial, informational, comparative, reputational. Убрать отсюда comparative — и сравнительный контур («X vs Y») исчезнет из генерируемой семантики.

autogenQueriesPerRuninteger

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PUT/api/v1/companies/{id}

curl -X PUT "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Samsung Electronics",
  "description": "Updated description",
  "synonyms": [
    "Samsung",
    "Самсунг",
    "삼성"
  ]
}'

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Samsung Electronics",
    "description": "Updated description",
    "url": "https://samsung.com",
    "categoryId": null,
    "country": "South Korea",
    "synonyms": [
      "Samsung",
      "Самсунг",
      "삼성"
    ],
    "isAutoGenerationEnabled": true,
    "lastUsedAt": "2026-04-06T18:00:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T14:00:00.000Z"
  }
}

Успешный ответ

Архивировать компанию

/api/v1/companies/{id}

Архивирование компании. Данные сохраняются, но компания не отображается в списках.

Параметры запроса

idstring (uuid)required

ID компании

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/companies/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

// No Content

Успешно удалено

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

/api/v1/companies/categories

Допустимые значения categoryId для создания и обновления компании.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/companies/categories

curl -X GET "https://app.brandfound.ai/api/v1/companies/categories" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "name": "example_name"
    }
  ]
}

Успешный ответ

Продукты

Управление продуктами

Список продуктов

/api/v1/products

Возвращает список продуктов с привязанными компаниями, ключевыми словами и конкурентами.

Параметры запроса

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

Порядок сортировки

ascdesc

companyIdstring (uuid)

Фильтр по компании

searchstring

Поисковый запрос (case-insensitive)

createdAtFromstring (date-time)

Начало диапазона даты создания (ISO 8601)

createdAtTostring (date-time)

Конец диапазона даты создания (ISO 8601)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/products

curl -X GET "https://app.brandfound.ai/api/v1/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "prod-001",
      "name": "Galaxy S25",
      "description": "Flagship smartphone",
      "url": "https://samsung.com/galaxy-s25",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "keywords": [],
      "competitors": [
        {
          "id": "comp-001",
          "name": "iPhone 16"
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Создать продукт

/api/v1/products

Создает новый продукт, привязанный к компании.

Тело запроса

namestringrequired

companyIdstringrequired

descriptionstring

urlstring

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/products

curl -X POST "https://app.brandfound.ai/api/v1/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Galaxy S25",
  "companyId": "clx1abc2d0001abcdef123456",
  "description": "Flagship smartphone 2026",
  "url": "https://samsung.com/galaxy-s25"
}'

{
  "success": true,
  "data": {
    "id": "prod-002",
    "name": "Galaxy S25",
    "description": "Flagship smartphone 2026",
    "url": "https://samsung.com/galaxy-s25",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

Успешный ответ

Получить продукт

/api/v1/products/{id}

Возвращает полную информацию о продукте, включая ключевые слова и конкурентов.

Параметры запроса

idstring (uuid)required

ID продукта

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/products/{id}

curl -X GET "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "id": "prod-001",
    "name": "Galaxy S25",
    "description": "Flagship smartphone 2026",
    "url": "https://samsung.com/galaxy-s25",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-06T18:00:00.000Z",
    "company": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Samsung"
    },
    "keywords": [
      {
        "id": "kw-001",
        "text": "galaxy s25"
      }
    ],
    "competitors": [
      {
        "id": "comp-001",
        "name": "iPhone 16",
        "url": "https://apple.com/iphone-16",
        "keywords": [
          {
            "id": "kw-002",
            "text": "iphone 16"
          }
        ]
      }
    ]
  }
}

Успешный ответ

Обновить продукт

/api/v1/products/{id}

Частичное обновление продукта.

Параметры запроса

idstring (uuid)required

ID продукта

Тело запроса

namestring

descriptionstring

urlstring

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PUT/api/v1/products/{id}

curl -X PUT "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Galaxy S25 Ultra",
  "description": "Updated flagship"
}'

{
  "success": true,
  "data": {
    "id": "prod-001",
    "name": "Galaxy S25 Ultra",
    "description": "Updated flagship",
    "url": "https://samsung.com/galaxy-s25",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T14:00:00.000Z"
  }
}

Успешный ответ

Архивировать продукт

/api/v1/products/{id}

Архивирование продукта. Данные сохраняются, но продукт не отображается в списках.

Параметры запроса

idstring (uuid)required

ID продукта

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/products/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

// No Content

Успешно удалено

Конкуренты

Управление конкурентами

Список конкурентов

/api/v1/competitors

Возвращает список конкурентов с привязанными компаниями, продуктами и ключевыми словами.

Параметры запроса

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

Порядок сортировки

ascdesc

companyIdstring (uuid)

Фильтр по компании

productIdstring (uuid)

Фильтр по продукту

searchstring

Поисковый запрос (case-insensitive)

createdAtFromstring (date-time)

Начало диапазона даты создания (ISO 8601)

createdAtTostring (date-time)

Конец диапазона даты создания (ISO 8601)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/competitors

curl -X GET "https://app.brandfound.ai/api/v1/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "comp-001",
      "name": "Apple",
      "url": "https://apple.com",
      "createdAt": "2026-01-20T10:00:00.000Z",
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "product": null,
      "keywords": []
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Создать конкурента

/api/v1/competitors

Создает нового конкурента. Может быть привязан к компании или к конкретному продукту.

Тело запроса

namestringrequired

companyIdstringrequired

productIdstring

urlstring

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/competitors

curl -X POST "https://app.brandfound.ai/api/v1/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Apple",
  "companyId": "clx1abc2d0001abcdef123456",
  "url": "https://apple.com"
}'

{
  "success": true,
  "data": {
    "id": "comp-003",
    "name": "Apple",
    "url": "https://apple.com",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": null,
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

Успешный ответ

Получить конкурента

/api/v1/competitors/{id}

Возвращает полную информацию о конкуренте с ключевыми словами.

Параметры запроса

idstring (uuid)required

ID конкурента

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/competitors/{id}

curl -X GET "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "id": "comp-001",
    "name": "Apple",
    "url": "https://apple.com",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": null,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-06T18:00:00.000Z",
    "company": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Samsung"
    },
    "product": null,
    "keywords": [
      {
        "id": "kw-003",
        "text": "apple"
      },
      {
        "id": "kw-005",
        "text": "apple inc"
      }
    ]
  }
}

Успешный ответ

Обновить конкурента

/api/v1/competitors/{id}

Обновляет имя и/или URL конкурента.

Параметры запроса

idstring (uuid)required

ID конкурента

Тело запроса

namestring

urlstring

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PUT/api/v1/competitors/{id}

curl -X PUT "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Apple Inc.",
  "url": "https://www.apple.com"
}'

{
  "success": true,
  "data": {
    "id": "comp-001",
    "name": "Apple Inc.",
    "url": "https://www.apple.com",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": null,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T14:00:00.000Z"
  }
}

Успешный ответ

Архивировать конкурента

/api/v1/competitors/{id}

Архивирование конкурента. Данные сохраняются, но конкурент не отображается в списках.

Параметры запроса

idstring (uuid)required

ID конкурента

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/competitors/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

// No Content

Успешно удалено

Интенты

Интенты (keywords): создание, переименование, архивирование/удаление, restore, bulk attach/detach к компаниям/продуктам/конкурентам

Список интентов (keywords)

/api/v1/keywords

Возвращает интенты (keywords) текущего workspace. Фильтр по target — companyId | productId | competitorId (только один). state контролирует выборку по архиву: active (по умолчанию) / archived / all.

Параметры запроса

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

sortBystring= createdAt

createdAtname

sortOrderstring= desc

Порядок сортировки

ascdesc

statestring= active

Lifecycle фильтр: active (не архивные, по умолчанию), archived (только архивные), all.

activearchivedall

searchstring

Case-insensitive подстрока по name.

companyIdstring (uuid)

Только интенты с активной связью с этой компанией.

productIdstring (uuid)

Только интенты с активной связью с этим продуктом.

competitorIdstring (uuid)

Только интенты с активной связью с этим конкурентом.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/keywords

curl -X GET "https://app.brandfound.ai/api/v1/keywords" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "name": "example_name",
      "userId": "example_userId",
      "createdAt": "2026-01-15T12:00:00Z",
      "archivedAt": "2026-01-15T12:00:00Z",
      "companyKeywords": [
        {
          "id": "example_id",
          "companyId": "example_companyId",
          "company": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "productKeywords": [
        {
          "id": "example_id",
          "productId": "example_productId",
          "product": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "competitorKeywords": [
        {
          "id": "example_id",
          "competitorId": "example_competitorId",
          "competitor": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Успешный ответ

Создать (или переиспользовать) интент

/api/v1/keywords

Find-or-create по (name, userId). Если интент уже существует — он переиспользуется (и разархивируется, если был в архиве). Опциональный attach: { companyId | productId | competitorId } — ровно один — привязывает интент к target в одной транзакции.

Тело запроса

namestringrequired

attachobject

Target для привязки/отвязки. Должен содержать РОВНО ОДИН из полей.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords

curl -X POST "https://app.brandfound.ai/api/v1/keywords" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "best AI smartphone 2026",
  "attach": {
    "productId": "0d7e6b3f-1a2c-4f5e-9876-abcdef012345"
  }
}'

{
  "success": true,
  "data": {
    "keyword": {
      "id": "example_id",
      "name": "example_name",
      "userId": "example_userId",
      "createdAt": "2026-01-15T12:00:00Z",
      "archivedAt": "2026-01-15T12:00:00Z",
      "companyKeywords": [
        {
          "id": "example_id",
          "companyId": "example_companyId",
          "company": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "productKeywords": [
        {
          "id": "example_id",
          "productId": "example_productId",
          "product": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "competitorKeywords": [
        {
          "id": "example_id",
          "competitorId": "example_competitorId",
          "competitor": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ]
    },
    "attach": "..."
  }
}

Успешный ответ

Получить интент

/api/v1/keywords/{id}

Возвращает интент с активными связями к компаниям, продуктам, конкурентам.

Параметры запроса

idstring (uuid)required

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/keywords/{id}

curl -X GET "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "userId": "example_userId",
    "createdAt": "2026-01-15T12:00:00Z",
    "archivedAt": "2026-01-15T12:00:00Z",
    "companyKeywords": [
      {
        "id": "example_id",
        "companyId": "example_companyId",
        "company": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "productKeywords": [
      {
        "id": "example_id",
        "productId": "example_productId",
        "product": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "competitorKeywords": [
      {
        "id": "example_id",
        "competitorId": "example_competitorId",
        "competitor": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ]
  }
}

Успешный ответ

Переименовать интент

/api/v1/keywords/{id}

Единственное редактируемое поле — name. Архивированный интент переименовать нельзя (используйте restore сначала).

Параметры запроса

idstring (uuid)required

Тело запроса

namestringrequired

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PUT/api/v1/keywords/{id}

curl -X PUT "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "best AI smartphone 2026"
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "userId": "example_userId",
    "createdAt": "2026-01-15T12:00:00Z",
    "archivedAt": "2026-01-15T12:00:00Z",
    "companyKeywords": [
      {
        "id": "example_id",
        "companyId": "example_companyId",
        "company": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "productKeywords": [
      {
        "id": "example_id",
        "productId": "example_productId",
        "product": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ],
    "competitorKeywords": [
      {
        "id": "example_id",
        "competitorId": "example_competitorId",
        "competitor": {
          "id": "example_id",
          "name": "example_name"
        }
      }
    ]
  }
}

Успешный ответ

Архивировать или удалить интент

/api/v1/keywords/{id}

По умолчанию архивирует (soft-delete) интент вместе со всеми его связями — обратимо через POST /restore. С ?permanent=true физически удаляет интент из БД (требует, чтобы он уже был в архиве или имел архивные связи). С ?dryRun=true возвращает отчёт о том, что будет затронуто, без выполнения операции.

Параметры запроса

idstring (uuid)required

permanentboolean= false

При true — необратимое удаление из БД. Требует архивного состояния.

dryRunboolean= false

При true — отчёт без побочных эффектов.

Ответы

204

Успешно удалено

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/keywords/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "keywordId": "example_keywordId",
    "archivedAt": "2026-01-15T12:00:00Z",
    "archivedLinks": {
      "company": 0,
      "product": 0,
      "competitor": 0
    },
    "mode": "archive",
    "dryRun": true,
    "wouldArchive": {
      "keyword": true,
      "links": {
        "company": 0,
        "product": 0,
        "competitor": 0
      }
    },
    "wouldDelete": {
      "keyword": true,
      "links": {
        "company": 0,
        "product": 0,
        "competitor": 0
      },
      "mentionRefs": 0
    },
    "alreadyArchived": true,
    "keyword": {
      "id": "example_id",
      "name": "example_name",
      "userId": "example_userId",
      "createdAt": "2026-01-15T12:00:00Z",
      "archivedAt": "2026-01-15T12:00:00Z",
      "companyKeywords": [
        {
          "id": "example_id",
          "companyId": "example_companyId",
          "company": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "productKeywords": [
        {
          "id": "example_id",
          "productId": "example_productId",
          "product": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ],
      "competitorKeywords": [
        {
          "id": "example_id",
          "competitorId": "example_competitorId",
          "competitor": {
            "id": "example_id",
            "name": "example_name"
          }
        }
      ]
    }
  }
}

Успешный ответ

Восстановить интент из архива

/api/v1/keywords/{id}/restore

Снимает archivedAt с keyword и со всех его архивных связей, чьи родительские сущности (company / product / competitor) ещё живы. Связи к удалённым target остаются архивными.

Параметры запроса

idstring (uuid)required

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords/{id}/restore

curl -X POST "https://app.brandfound.ai/api/v1/keywords/{id}/restore" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "keywordId": "example_keywordId",
    "restoredLinks": {
      "company": 0,
      "product": 0,
      "competitor": 0
    }
  }
}

Успешный ответ

Bulk attach интентов к target

/api/v1/keywords/attach

Для каждого name делает find-or-create по (name, userId), затем гарантирует активную связь с target. Архивированные связи разархивирует. Target требует РОВНО ОДИН из companyId / productId / competitorId.

Тело запроса

targetobjectrequired

Target для привязки/отвязки. Должен содержать РОВНО ОДИН из полей.

namesstring[]required

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords/attach

curl -X POST "https://app.brandfound.ai/api/v1/keywords/attach" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "productId": "0d7e6b3f-1a2c-4f5e-9876-abcdef012345"
  },
  "names": [
    "best 2026 AI phone",
    "battery life smartphone"
  ]
}'

{
  "success": true,
  "data": {
    "target": {
      "companyId": "example_companyId",
      "productId": "example_productId",
      "competitorId": "example_competitorId"
    },
    "attached": [
      {
        "keywordId": "example_keywordId",
        "name": "example_name"
      }
    ],
    "alreadyAttached": [
      {
        "keywordId": "example_keywordId",
        "name": "example_name"
      }
    ],
    "reactivated": [
      {
        "keywordId": "example_keywordId",
        "name": "example_name"
      }
    ]
  }
}

Успешный ответ

Bulk detach интентов от target

/api/v1/keywords/detach

Архивирует активные связи keyword↔target. Сам интент остаётся жить и может быть привязан к другим target. Target требует РОВНО ОДИН из companyId / productId / competitorId.

Тело запроса

targetobjectrequired

Target для привязки/отвязки. Должен содержать РОВНО ОДИН из полей.

keywordIdsstring[]required

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords/detach

curl -X POST "https://app.brandfound.ai/api/v1/keywords/detach" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "productId": "0d7e6b3f-1a2c-4f5e-9876-abcdef012345"
  },
  "keywordIds": [
    "7b2f1d4e-8c9a-4e5b-b6c2-3d7a1f8e9c4b"
  ]
}'

{
  "success": true,
  "data": {
    "target": {
      "companyId": "example_companyId",
      "productId": "example_productId",
      "competitorId": "example_competitorId"
    },
    "detached": [
      "example"
    ],
    "notAttached": [
      "example"
    ]
  }
}

Успешный ответ

Запросы

Управление запросами к AI-ассистентам

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

/api/v1/queries

Возвращает список запросов к AI-ассистентам с количеством ответов. Поддерживает расширенную фильтрацию: по тональности, кластерам, регионам, избранному, области поиска и диапазонам метрик тональности. Состояние опроса читайте по queue.status и answersCount. Поле providers показывает нейросети, в которые запрос ушёл фактически. Детали по конкретным ранам — GET /api/v1/queries/queue.

Параметры запроса

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

sortBystring= createdAt

createdAttextupdatedAt

sortOrderstring= desc

Порядок сортировки

ascdesc

companyIdstring (uuid)

Фильтр по компании

productIdstring (uuid)

Фильтр по продукту

typestring

Тип запроса (general, comparative, negative и т.д.). Поддерживает массив: ?type=comparative&type=neutral

originstring

Источник запроса. Поддерживает массив: ?origin=manual&origin=auto

manualauto

hasAnswersstring

Наличие ответов

truefalse

languagestring

Язык запроса (ru, en и т.д.). Поддерживает массив: ?language=ru&language=en

searchTextstring

Поиск по тексту запроса

providerstring

Фильтр по AI-провайдеру ответа

sourceIdstring

Фильтр по ID источника ответа. Поддерживает массив: ?sourceId=id1&sourceId=id2

labelSlugstring

Фильтр по slug кластера/лейбла

regionstring

Регион запроса. Поддерживает массив: ?region=RU&region=US

isFavoritestring

Только избранные запросы

truefalse

sentimentstring

Фильтр по тональности упоминаний в ответах

positiveneutralnegative

searchFieldstring= query

Область поиска для searchText: в тексте запроса, в ответах или в источниках

queryanswersources

labelFilterModestring= or

Логика фильтрации по кластерам: any (or) или all (and)

orand

labelstring

Slug кластера. Поддерживает массив: ?label=slug1&label=slug2

createdAtFromstring (date-time)

Начало диапазона даты создания (ISO 8601)

createdAtTostring (date-time)

Конец диапазона даты создания (ISO 8601)

showArchivedstring

Показать архивированные запросы (по умолчанию: false)

truefalse

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/queries

curl -X GET "https://app.brandfound.ai/api/v1/queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "query-001",
      "text": "Какой лучший смартфон 2026 года?",
      "type": "comparative",
      "origin": "manual",
      "language": "ru",
      "region": "russia",
      "createdAt": "2026-04-01T10:00:00.000Z",
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "product": {
        "id": "prod-001",
        "name": "Galaxy S25"
      },
      "_count": {
        "answers": 4
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Создать запрос

/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 означает, что запрос создан, но опрос не стартовал.

Тело запроса

textstringrequired

companyIdstringrequired

productIdstring

typestring= neutral

Легаси-значения negative и general принимаются: negative → reputational, general → neutral.

neutralcommercialinformationalcomparativereputationalbranded

languagestring= ru

ISO 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= true

false — создать запрос, НЕ ставя его в платный опрос.

labelsstring[]

Имена кластеров: создаются или переиспользуются по slug.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

402application/json

Недостаточно FoxCoin

HTTP_402

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/queries

curl -X POST "https://app.brandfound.ai/api/v1/queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "лучшие сервисы threat intelligence для банков",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "type": "comparative",
  "language": "en",
  "region": "AE",
  "providers": [
    "chatgpt",
    "gemini",
    "perplexity"
  ]
}'

{
  "success": true,
  "data": {
    "id": "8a5bd522-975a-4ba5-8974-04ac3785a69a",
    "text": "лучшие сервисы threat intelligence для банков",
    "type": "comparative",
    "origin": "manual",
    "language": "ru",
    "region": "RU",
    "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
    "productId": null,
    "providers": [
      "chatgpt",
      "perplexity",
      "gemini"
    ],
    "createdAt": "2026-08-04T12:00:00.000Z",
    "dispatch": {
      "dispatched": true,
      "providers": [
        "chatgpt",
        "perplexity",
        "gemini"
      ],
      "runStatus": "PENDING",
      "error": null
    }
  }
}

Успешный ответ

Получить запрос

/api/v1/queries/{id}

Возвращает запрос с ответами от AI-ассистентов и найденными упоминаниями.

Параметры запроса

idstring (uuid)required

ID запроса

includeAnswersstring= true

Включить ответы с упоминаниями (по умолчанию true)

truefalse

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/queries/{id}

curl -X GET "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "id": "query-001",
    "text": "Какой лучший смартфон 2026 года?",
    "type": "comparative",
    "origin": "manual",
    "language": "ru",
    "region": "russia",
    "createdAt": "2026-04-01T10:00:00.000Z",
    "company": {
      "id": "comp-uuid",
      "name": "Samsung"
    },
    "product": null,
    "answers": [
      {
        "id": "ans-001",
        "content": "По мнению экспертов, Samsung Galaxy S25 Ultra и Apple iPhone 16 Pro...",
        "createdAt": "2026-04-01T10:01:00.000Z",
        "source": {
          "id": "src-001",
          "name": "ChatGPT",
          "type": "chatgpt"
        },
        "mentions": [
          {
            "id": "mention-001",
            "type": "company",
            "sentiment": 1,
            "position": 1,
            "context": "Samsung Galaxy S25 Ultra",
            "isOurs": true,
            "company": {
              "id": "comp-uuid",
              "name": "Samsung"
            },
            "product": null,
            "keywords": []
          }
        ]
      }
    ]
  }
}

Успешный ответ

Архивировать запрос

/api/v1/queries/{id}

Перемещает запрос в архив. Данные сохраняются и могут быть восстановлены.

Параметры запроса

idstring (uuid)required

ID запроса

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/queries/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

// No Content

Успешно удалено

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

/api/v1/queries/{id}

Меняет текст, тип, язык, регион, продукт, избранность и кластеры запроса. Изменение текста НЕ переопрашивает нейросети — уже полученные ответы остаются привязаны к запросу. Чтобы опросить заново, создайте новый запрос. Тело строгое: неизвестное поле → 400.

Параметры запроса

idstring (uuid)required

Тело запроса

textstring

typestring

neutralcommercialinformationalcomparativereputationalbranded

languagestring

regionstring

ISO 3166-1 alpha-2.

productIdstring

null — отвязать от продукта.

isFavoriteboolean

labelsstring[]

ПОЛНЫЙ список кластеров: связки пересобираются.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PATCH/api/v1/queries/{id}

curl -X PATCH "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "region": "AE",
  "language": "en",
  "labels": [
    "Threat Intelligence"
  ]
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "text": "example_text",
    "type": "neutral",
    "origin": "manual",
    "language": "example_language",
    "region": "example_region",
    "companyId": "example_companyId",
    "productId": "example_productId",
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z",
    "providers": [
      "example"
    ],
    "answersCount": 1,
    "queue": {
      "pending": 1,
      "running": 1,
      "retrying": 1,
      "onHold": 1,
      "failed": 1,
      "cancelled": 1,
      "total": 1,
      "inQueue": 1,
      "status": "in_progress"
    }
  }
}

Успешный ответ

Очередь опросов

/api/v1/queries/queue

Состояние опроса запросов: по одному рану на каждую пару запрос-нейросеть. Позволяет отличить «ещё опрашивается» от «упало» и от «стоит без денег» — по одному лишь счётчику ответов это неразличимо.

Параметры запроса

statusstring= queued,onHold,failed

Группы статусов через запятую. По умолчанию все три.

companyIdstring (uuid)

Сузить до одной компании. Без него — все компании аккаунта.

queryIdstring (uuid)

Раны одного запроса

providerstring

Фильтр по нейросети

chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_mode

includeArchivedboolean= false

Не отсекать раны архивных запросов

limitinteger= 50

Размер страницы

offsetinteger= 0

Сдвиг

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/queries/queue

curl -X GET "https://app.brandfound.ai/api/v1/queries/queue" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "queryId": "example_queryId",
      "queryText": "example_queryText",
      "companyId": "example_companyId",
      "provider": "chatgpt",
      "status": "PENDING",
      "attempts": 1,
      "maxAttempts": 1,
      "scheduledAt": "2026-01-15T12:00:00Z",
      "startedAt": "2026-01-15T12:00:00Z",
      "completedAt": "2026-01-15T12:00:00Z",
      "retryAfter": "2026-01-15T12:00:00Z",
      "answerId": "example_answerId",
      "error": "example_error"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Успешный ответ

Сводка очереди и прогноз стоимости

/api/v1/queries/queue/summary

Счётчики ранов, стоимость текущей очереди и остаток FoxCoin одним запросом. Пока queuedTotal > 0 — опрос идёт. onHold > 0 означает нехватку средств: такие раны сами не возобновятся даже после пополнения.

Параметры запроса

companyIdstring (uuid)

Сузить до одной компании

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/queries/queue/summary

curl -X GET "https://app.brandfound.ai/api/v1/queries/queue/summary" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "pending": 1,
    "running": 1,
    "retrying": 1,
    "onHold": 1,
    "failed": 1,
    "cancelled": 1,
    "queuedTotal": 1,
    "queuedQueries": 1,
    "estimatedCostFc": 1,
    "balanceFc": 1,
    "costPerAnswerFc": 1,
    "billingEnabled": true
  }
}

Успешный ответ

Массовое создание запросов с выбором нейросетей

/api/v1/queries/setup

Создаёт кластеры и запросы одной транзакцией и сразу ставит их в очередь опроса. В отличие от POST /api/v1/queries принимает providers, поэтому это основная точка входа для интеграций, которым важно, в какие ассистенты уйдёт запрос. Платно: каждый полученный ответ каждой нейросети списывает FoxCoin (см. GET /api/v1/billing/balance). Лимит 500 запросов на вызов.

Тело запроса

companyIdstring

Без него берётся preferredCompanyId ключа (см. GET /api/v1/context)

clusterIdstring

Существующий кластер для гео-наследования; применяется ко всем элементам clusters без своего clusterId

providersstring[]

Единственный способ выбрать нейросети явно: POST /api/v1/queries этого не умеет. Без этого поля запрос уходит в нейросети по умолчанию для аккаунта — а у аккаунта без настроек это ровно ChatGPT. Актуальный список: GET /api/v1/sources.

clustersobject[]required

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

402application/json

Недостаточно FoxCoin

HTTP_402

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/setup

curl -X POST "https://app.brandfound.ai/api/v1/queries/setup" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "providers": [
    "chatgpt",
    "perplexity",
    "gemini"
  ],
  "clusters": [
    {
      "name": "Threat Intelligence",
      "queries": [
        {
          "text": "best threat intelligence vendors for banks in UAE. Answer in English.",
          "type": "comparative",
          "language": "en",
          "region": "AE"
        }
      ]
    }
  ]
}'

{
  "success": true,
  "data": {
    "clustersCreated": 1,
    "queriesCreated": 1,
    "providerRunsCreated": 1,
    "dispatchError": "example_dispatchError",
    "clusters": [
      {
        "id": "example_id",
        "name": "example_name",
        "slug": "example_slug",
        "queryIds": [
          "example"
        ]
      }
    ]
  }
}

Успешный ответ

Вернуть опросы в очередь

/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

Все раны на паузе

onHold

companyIdstring

Сузить scope до одной компании

forceboolean= false

Возобновить, даже если баланса не хватает на всю пачку

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

402application/json

Недостаточно FoxCoin на всю пачку

HTTP_402

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/queue/resume

curl -X POST "https://app.brandfound.ai/api/v1/queries/queue/resume" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "onHold"
}'

{
  "success": true,
  "data": {
    "resumed": 1
  }
}

Успешный ответ

Снять опросы с очереди

/api/v1/queries/queue/cancel

Отменяет раны, которые ещё не ушли в работу: ждущие (PENDING, RETRYING) и стоящие на паузе. Раны в статусе RUNNING не трогаются никогда — они уже у воркера, отмена привела бы к гонке. **Когда нужно.** Остановить лишний массовый прогон до того, как он спишет FoxCoin: списание происходит по факту прихода ответа, поэтому отменённый ран не стоит ничего. Либо разобрать зависший хвост, который не планируется оплачивать. Отмена обратима: снятый ран возвращается в очередь через `POST /api/v1/queries/queue/resume` с его `runId`.

Тело запроса

runIdsstring[]

queryIdsstring[]

Все отменяемые раны этих запросов

scopestring

onHold — только паузы; queued — только активная очередь

onHoldqueued

companyIdstring

Сузить scope до одной компании

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/queue/cancel

curl -X POST "https://app.brandfound.ai/api/v1/queries/queue/cancel" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "queued",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427"
}'

{
  "success": true,
  "data": {
    "cancelled": 1
  }
}

Успешный ответ

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

Автоподбор семантики: генерация запросов в черновики и их подтверждение. Генерация (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 ключа.

productIdstring

countintegerrequired

Сколько запросов сгенерировать НА КАЖДЫЙ таргет. 1 FoxCoin за запрос.

typesstring[]

Типы генерируемых запросов; count делится между ними поровну. Без поля берутся Company.autogenQueryTypes (по умолчанию включают comparative).

clustersstring[]

Темы, по которым раскладываются запросы.

userWishesstring

namestring

Имя задачи — видно в UI и в GET.

languagestring

ISO 639-1. Без поля — язык компании. Только БЕЗ targets.

regionstring

ISO 3166-1 alpha-2. Без поля — primary-страна компании (regionTargets), затем RU. Legacy-названия («russia») принимаются. Только БЕЗ targets.

citystring

Только БЕЗ targets.

includeDistrictsboolean

Только БЕЗ targets.

targetsobject[]

Замер по нескольким странам: по задаче на страну. Стоимость — сумма count всех таргетов. ВЗАИМОИСКЛЮЧАЮЩЕ с короткой формой: region / language / city / includeDistricts рядом с targets → 400 (внутри targets у каждой страны свои город и язык).

waitboolean= false

true — дождаться конца генерации (только для небольших пачек: 100+ запросов идут минутами).

clientTokenstring

Свой маркер задачи; по нему потом читается прогресс.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

402application/json

Недостаточно FoxCoin: поля required и balance в теле ошибки

HTTP_402

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

503application/json

Автоподбор не сконфигурирован на сервере

HTTP_503

POST/api/v1/queries/autogenerate

curl -X POST "https://app.brandfound.ai/api/v1/queries/autogenerate" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "count": 50,
  "types": [
    "commercial",
    "informational",
    "comparative"
  ],
  "clusters": [
    "Threat Intelligence",
    "Endpoint Protection"
  ],
  "targets": [
    {
      "region": "AE"
    },
    {
      "region": "IN"
    },
    {
      "region": "RU",
      "language": "ru"
    }
  ]
}'

{
  "success": true,
  "data": {}
}

Успешный ответ

Статус задач автоподбора

/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_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/queries/autogenerate

curl -X GET "https://app.brandfound.ai/api/v1/queries/autogenerate" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "name": "example_name",
      "status": "PENDING",
      "requested": 1,
      "generated": 1,
      "companyId": "example_companyId",
      "productId": "example_productId",
      "clientToken": "example_clientToken",
      "language": "example_language",
      "region": "example_region",
      "city": "example_city",
      "types": [
        "example"
      ],
      "clusters": [
        "example"
      ],
      "createdAt": "2026-01-15T12:00:00Z",
      "completedAt": "2026-01-15T12:00:00Z",
      "error": "example_error"
    }
  ]
}

Успешный ответ

Остановить задачу автоподбора

/api/v1/queries/autogenerate/cancel

Отмена настоящая: не начатые пачки не выполняются, платите только за уже доставленные черновики. Ран переходит в CANCELLED, сгенерированные черновики остаются и их можно подтвердить.

Тело запроса

runIdstringrequired

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/autogenerate/cancel

curl -X POST "https://app.brandfound.ai/api/v1/queries/autogenerate/cancel" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "runId": "8a5bd522-975a-4ba5-8974-04ac3785a69a"
}'

{
  "success": true,
  "data": {
    "cancelled": true
  }
}

Успешный ответ

Список черновиков запросов

/api/v1/query-drafts

Черновик ничего не стоит хранить и ничего не опрашивает: запросом он становится только через POST /api/v1/query-drafts/approve.

Параметры запроса

statusstring

PENDING — ждут решения. По умолчанию все.

PENDINGAPPROVEDREJECTEDEXPIRED

companyIdstring (uuid)

Срез по компании.

typestring

Срез по типу запроса.

neutralcommercialinformationalcomparativereputationalbranded

pageinteger= 1

Страница, с 1.

limitinteger= 50

Размер страницы.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/query-drafts

curl -X GET "https://app.brandfound.ai/api/v1/query-drafts" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "drafts": [
      {
        "id": "example_id",
        "text": "example_text",
        "type": "neutral",
        "language": "example_language",
        "region": "example_region",
        "labels": [
          "example"
        ],
        "companyId": "example_companyId",
        "companyName": "example_companyName",
        "productId": "example_productId",
        "productName": "example_productName",
        "generationRunId": "example_generationRunId",
        "taskName": "example_taskName",
        "status": "PENDING",
        "createdAt": "2026-01-15T12:00:00Z"
      }
    ],
    "total": 1,
    "counts": {}
  }
}

Успешный ответ

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

/api/v1/query-drafts/approve

ПЛАТНЫЙ ШАГ: подтверждённые черновики становятся запросами и уходят в выбранные нейросети — 10 FoxCoin за каждый ответ (запрос × нейросеть). 50 черновиков × 3 сети = 150 ответов = 1500 FoxCoin. Сначала вызовите с dryRun: true и покажите смету пользователю. Идемпотентно: повторный вызов с теми же draftIds не создаёт запросы дважды и не переопрашивает их. Черновики ещё идущей задачи автогенерации пропускаются (skippedRunning) — дождитесь status = OK.

Тело запроса

draftIdsstring[]required

providersstring[]required

Нейросети для опроса. Каждая умножает стоимость.

dryRunboolean

true — только смета, ничего не создаётся и не списывается.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

402application/json

Недостаточно FoxCoin: поля required и balance в теле ошибки

HTTP_402

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/query-drafts/approve

curl -X POST "https://app.brandfound.ai/api/v1/query-drafts/approve" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "draftIds": [
    "8a5bd522-975a-4ba5-8974-04ac3785a69a"
  ],
  "providers": [
    "chatgpt",
    "gemini",
    "perplexity"
  ],
  "dryRun": true
}'

{
  "success": true,
  "data": {
    "dryRun": true,
    "toApprove": 1,
    "estimatedAnswersCostFc": 1,
    "approved": 1,
    "createdQueries": 1,
    "skippedDuplicates": 1,
    "skippedRunning": 1,
    "dispatch": {},
    "balance": 1
  }
}

Успешный ответ

Отклонить черновики

/api/v1/query-drafts/reject

Мягкое отклонение: черновик остаётся в базе со статусом REJECTED (аудит биллинга). Ничего не опрашивается. Возврата FoxCoin за генерацию нет — запросы уже сгенерированы.

Тело запроса

draftIdsstring[]required

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/query-drafts/reject

curl -X POST "https://app.brandfound.ai/api/v1/query-drafts/reject" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "draftIds": [
    "8a5bd522-975a-4ba5-8974-04ac3785a69a"
  ]
}'

{
  "success": true,
  "data": {
    "rejected": 1
  }
}

Успешный ответ

Ответы нейросетей

Ответы нейросетей пачкой: ссылки, упоминания, тональность.

Ответы нейросетей пачкой

/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).

hasLinksboolean

true — только ответы со ссылками, false — только без.

mentionsOursboolean

true — только ответы, где упомянут бренд компании.

showArchivedboolean= false

true — включить ответы архивных запросов.

includestring= content,tonality

Что добавить, через запятую: content, links, mentions, tonality.

limitinteger= 50

Размер страницы.

offsetinteger= 0

Смещение.

sortBystring= createdAt

Поле сортировки.

createdAtdate

sortOrderstring= desc

Направление сортировки.

ascdesc

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/answers

curl -X GET "https://app.brandfound.ai/api/v1/answers" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "createdAt": "2026-01-15T12:00:00Z",
      "date": "2026-01-15T12:00:00Z",
      "query": {
        "id": "example_id",
        "text": "example_text",
        "type": "example_type",
        "language": "example_language",
        "region": "example_region",
        "archived": true,
        "labels": [
          {}
        ]
      },
      "company": {},
      "product": {},
      "source": {
        "id": "example_id",
        "name": "example_name",
        "type": "example_type"
      },
      "mentionsCount": 1,
      "ourMentionsCount": 1,
      "linksCount": 1,
      "brandDomainCited": true,
      "content": "example_content",
      "links": [
        {
          "url": "example_url",
          "title": "example_title",
          "domain": "example_domain",
          "position": 1,
          "inAnswer": true,
          "inSources": true,
          "context": "example_context"
        }
      ],
      "mentions": [
        {
          "id": "example_id",
          "isOurs": true,
          "type": "example_type",
          "position": 1,
          "sentiment": 1,
          "sentimentLabel": "example_sentimentLabel",
          "sentimentScore": 1,
          "context": "example_context",
          "isLink": true,
          "linkUrl": "example_linkUrl",
          "linkDomain": "example_linkDomain"
        }
      ]
    }
  ]
}

Успешный ответ

География

Справочники стран, регионов, городов и языков.

Справочник стран

/api/v1/geo/countries

id из справочника нужны для regionTargets и defaultLanguageId компании и кластера, iso2 — для поля region запроса и автоподбора.

Параметры запроса

qstring

Поиск по названию.

continentstring

Фильтр по континенту.

EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICA

limitinteger= 250

Максимум записей.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/countries

curl -X GET "https://app.brandfound.ai/api/v1/geo/countries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "example_id",
        "iso2": "example_iso2",
        "iso3": "example_iso3",
        "nameRu": "example_nameRu",
        "nameEn": "example_nameEn",
        "flagEmoji": "example_flagEmoji",
        "defaultLanguage": "example_defaultLanguage",
        "defaultTimezone": "example_defaultTimezone",
        "continent": "example_continent"
      }
    ],
    "total": 1
  }
}

Успешный ответ

Справочник регионов страны

/api/v1/geo/regions

Регионы (области, штаты) конкретной страны. Обязателен один из countryId / countryIso2.

Параметры запроса

countryIso2string

Двухбуквенный код страны.

countryIdstring (uuid)

UUID страны.

qstring

Поиск по названию.

limitinteger= 100

Максимум записей.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/regions

curl -X GET "https://app.brandfound.ai/api/v1/geo/regions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {}
}

Успешный ответ

Справочник городов страны

/api/v1/geo/cities

Города конкретной страны. Обязателен один из countryId / countryIso2. cityId отсюда идёт в regionTargets компании и targets кластера.

Параметры запроса

countryIso2string

Двухбуквенный код страны.

countryIdstring (uuid)

UUID страны.

regionIdstring (uuid)

UUID региона.

qstring

Поиск по названию.

limitinteger= 50

Максимум записей.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/cities

curl -X GET "https://app.brandfound.ai/api/v1/geo/cities" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {}
}

Успешный ответ

Справочник языков

/api/v1/geo/languages

id из справочника нужны для regionTargets и defaultLanguageId компании и кластера, iso2 — для поля region запроса и автоподбора.

Параметры запроса

qstring

Поиск по названию или коду.

limitinteger= 200

Максимум записей.

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/languages

curl -X GET "https://app.brandfound.ai/api/v1/geo/languages" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "example_id",
        "iso639_1": "example_iso639_1",
        "nameNative": "example_nameNative",
        "nameEn": "example_nameEn"
      }
    ],
    "total": 1
  }
}

Успешный ответ

Кластеры запросов

Метки/кластеры запросов: список (с опциональным срезом по компании), создание с регионализацией

Список кластеров (меток запросов)

/api/v1/query-labels

Возвращает метки/кластеры запросов текущего workspace с количеством запросов в каждом. Параметр companyId делает срез по компании: возвращаются только кластеры, в которых есть запросы этой компании, а queryCount считается по запросам этой компании. lite=true — облегчённый ответ { items: [{ id, name, slug, queryCount }] } без статистики и sampleQueries.

Параметры запроса

companyIdstring (uuid)

Срез по компании: только кластеры с запросами этой компании; queryCount — по её запросам.

litestring

lite=true — облегчённый ответ { items: [{ id, name, slug, queryCount }] } без статистики.

truefalse

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

qstring

Case-insensitive подстрока по имени метки.

sortstring= queryCount:desc

Сортировка в формате field:direction.

queryCount:descqueryCount:ascname:ascname:desccreatedAt:desccreatedAt:asclastUsedAt:desclastUsedAt:asc

hasQueriesstring

with — только кластеры с запросами, without — пустые.

withwithout

minCountinteger

Минимальное число запросов в кластере.

maxCountinteger

Максимальное число запросов в кластере.

createdFromstring (date-time)

Метки, созданные не раньше указанной даты.

createdTostring (date-time)

Метки, созданные не позже указанной даты.

lastUsedFromstring (date-time)

Метки с lastUsedAt не раньше указанной даты.

lastUsedTostring (date-time)

Метки с lastUsedAt не позже указанной даты.

includestring

include=targets — догрузить геотаргеты кластера (country/city).

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/query-labels

curl -X GET "https://app.brandfound.ai/api/v1/query-labels" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "example_id",
        "name": "example_name",
        "slug": "example_slug",
        "createdAt": "2026-01-15T12:00:00Z",
        "lastUsedAt": "2026-01-15T12:00:00Z",
        "queryCount": 1,
        "lastQueryAt": "2026-01-15T12:00:00Z"
      }
    ],
    "totalCount": 1,
    "pageInfo": {
      "limit": 1,
      "offset": 1,
      "hasMore": true
    },
    "stats": {},
    "filters": {}
  }
}

Успешный ответ

Создать (или обновить) кластер с регионализацией

/api/v1/query-labels

Find-or-create по (slug, userId). Если кластер с таким slug существует — обновляется (имя, гео-настройки), targets пересоздаются. Опциональные companyId/productId принимаются, но на QueryLabel пока не персистятся.

Тело запроса

namestringrequired

slugstring

descriptionstring

companyIdstring

productIdstring

defaultLanguageIdstring

defaultLocalestring

defaultResponseLanguageIdstring

geoScopestring

GLOBALCOUNTRYREGIONCITY

injectLocationModestring

NONEAPPEND_PARENSAPPEND_NATURALPREPENDAI_REWRITE

autogenStrategystring

SHAREDPER_TARGETPER_TARGET_LOCALIZED

targetsobject[]

Ответы

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

409application/json

Ресурс с таким именем уже существует

CONFLICT

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/query-labels

curl -X POST "https://app.brandfound.ai/api/v1/query-labels" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example",
  "slug": "",
  "description": "",
  "companyId": "",
  "productId": "",
  "defaultLanguageId": "",
  "defaultLocale": "",
  "defaultResponseLanguageId": "",
  "geoScope": "GLOBAL",
  "injectLocationMode": "NONE",
  "autogenStrategy": "SHARED",
  "targets": null
}'

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ошибка валидации"
  }
}

Ошибка валидации

Упоминания

Просмотр упоминаний бренда

Список упоминаний

/api/v1/mentions

Возвращает упоминания бренда в ответах AI-ассистентов с полным контекстом.

Параметры запроса

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

sortBystring= createdAt

createdAtpositionsentiment

sortOrderstring= desc

Порядок сортировки

ascdesc

timeRangestring

Временной диапазон

24h7d30d90dall

createdAtFromstring (date-time)

Начало диапазона даты создания (ISO 8601)

createdAtTostring (date-time)

Конец диапазона даты создания (ISO 8601)

companyIdstring (uuid)

Фильтр по компании

productIdstring (uuid)

Фильтр по продукту

competitorIdstring (uuid)

Фильтр по конкуренту

answerIdstring (uuid)

Фильтр по конкретному ответу

typestring

Тип упоминания

companyproductkeywordcompetitor

sentimentstring

Тональность

positiveneutralnegative

searchstring

Поисковый запрос (case-insensitive)

isOursstring

Только наши (true) или только конкурентов (false)

truefalse

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/mentions

curl -X GET "https://app.brandfound.ai/api/v1/mentions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "mention-001",
      "type": "company",
      "sentiment": 1,
      "position": 1,
      "context": "Samsung Galaxy S25 Ultra является одним из лучших смартфонов...",
      "isOurs": true,
      "createdAt": "2026-04-01T10:01:00.000Z",
      "answer": {
        "id": "ans-001",
        "content": "По мнению экспертов...",
        "createdAt": "2026-04-01T10:01:00.000Z",
        "source": {
          "id": "src-001",
          "name": "ChatGPT",
          "type": "chatgpt"
        },
        "query": {
          "id": "query-001",
          "text": "Какой лучший смартфон?",
          "type": "comparative"
        }
      },
      "company": {
        "id": "comp-uuid",
        "name": "Samsung"
      },
      "product": null,
      "competitor": null,
      "keywords": []
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Аналитика

Аналитика: конкуренты, тональность, ссылки, видимость бренда

Аналитика конкурентов

/api/v1/analytics/competitors

Полный сравнительный анализ вашей компании и конкурентов по упоминаниям в AI-ассистентах. Поддерживает фильтрацию по кластерам (slug), AI-провайдерам и периоду.

Параметры запроса

timeRangestring= 30d

Временной диапазон

24h7d30dall

fromstring (date-time)

Начало кастомного диапазона (ISO 8601)

tostring (date-time)

Конец кастомного диапазона (ISO 8601)

companyIdstring (uuid)

ID компании

productIdstring (uuid)

ID продукта

sourceIdstring[]

ID AI-провайдеров

labelIdstring[]

ID кластеров/лейблов

labelSlugstring

Slug кластера. Массив: ?labelSlug=slug1&labelSlug=slug2

labelFilterModestring= or

Режим фильтрации по лейблам

orand

includeDemostring

Включить демо-данные

truefalse

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/competitors

curl -X GET "https://app.brandfound.ai/api/v1/analytics/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "ourCompany": {
      "name": "Samsung",
      "mentions": 150,
      "mentionsBrand": 120,
      "mentionsLink": 30,
      "sentiment": 0.72,
      "brandMentionRate": 0.8
    },
    "competitors": [
      {
        "name": "Apple",
        "mentions": 180,
        "mentionsBrand": 160,
        "mentionsLink": 20,
        "sentiment": 0.65,
        "categories": [],
        "brandMentionRate": 0.89
      }
    ],
    "overall": {
      "ourMentions": 150,
      "competitorMentions": 180,
      "leader": "Apple"
    },
    "productBreakdown": [],
    "sourceBreakdown": [
      {
        "name": "ChatGPT",
        "ourAnswers": 50,
        "ourMentions": 80,
        "competitorBreakdown": [],
        "totalAnswers": 120
      }
    ],
    "shareOfVoice": {
      "ourCompany": 0.45,
      "competitors": [
        {
          "name": "Apple",
          "share": 0.55
        }
      ],
      "totalAnswers": 200
    },
    "exclusiveBreakdown": {
      "onlyUs": 60,
      "shared": 40,
      "onlyCompetitors": 50,
      "total": 150,
      "byCompetitor": []
    },
    "timeline": [
      {
        "date": "2026-04-01",
        "ourMentions": 10,
        "competitorMentions": 12,
        "totalAnswers": 30
      }
    ]
  }
}

Успешный ответ

Предпросмотр упоминаний конкурентов

/api/v1/analytics/competitors/preview

Возвращает конкретные ответы AI-ассистентов с упоминаниями для детального анализа. Поддерживает фильтрацию по кластерам, демо-данные, кастомный период и режим фильтрации лейблов. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).

Параметры запроса

sidestringrequired

Чья сторона: наша компания или конкурент

ourcompetitor

competitorNamestring

Имя конкурента (если side=competitor)

mentionTypestring= both

Тип упоминания

brandlinkboth

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

sourceIdstring[]

labelIdstring[]

includeMentionsstring

Включить упоминания в ответ

truefalse

includeDemostring

Включить демо-данные

truefalse

labelFilterModestring= or

Логика фильтрации по кластерам

orand

fromstring (date-time)

Начало периода (ISO 8601)

tostring (date-time)

Конец периода (ISO 8601)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/competitors/preview

curl -X GET "https://app.brandfound.ai/api/v1/analytics/competitors/preview" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "mention-001",
        "isOurs": true,
        "type": "company",
        "sentiment": 1,
        "position": 1,
        "context": "Samsung Galaxy S25 Ultra",
        "company": {
          "id": "c1",
          "name": "Samsung"
        },
        "product": null,
        "competitor": null,
        "answer": {
          "id": "ans-001",
          "content": "По мнению экспертов...",
          "source": {
            "name": "ChatGPT",
            "type": "chatgpt"
          }
        }
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": 20,
    "hasMore": false
  }
}

Успешный ответ

Аналитика тональности

/api/v1/analytics/tonality

Полный анализ тональности ответов AI-ассистентов: метрики качества, timeline, проблемные и лучшие ответы.

Параметры запроса

timeRangestring= 30d

24h7d30d90d

companyIdstring (uuid)

productIdstring (uuid)

queryTypestring

Тип запроса

neutralcomparativenegative

sentimentstring

Фильтр по тональности

positiveneutralnegative

sourceIdstring[]

AI-провайдеры

labelSlugstring[]

Кластеры/лейблы по slug

labelFilterModestring= or

orand

fromstring (date-time)

tostring (date-time)

includeDemostring

truefalse

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/tonality

curl -X GET "https://app.brandfound.ai/api/v1/analytics/tonality" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "summary": {
      "totalAnswers": 200,
      "avgOverallScore": 7.5,
      "sentimentDistribution": {
        "positive": 120,
        "neutral": 50,
        "negative": 30
      }
    },
    "metrics": {
      "relevanceToBrand": 8.2,
      "factualityConfidence": 7.8,
      "helpfulness": 7.5,
      "preferenceForBrand": 6.9,
      "recommendationStrength": 7.1,
      "fairness": 8,
      "evidenceSupport": 7.3,
      "informativeness": 7.6,
      "completeness": 7.4,
      "impactOnBrand": 7
    },
    "timeline": [
      {
        "date": "2026-04-01",
        "positive": 10,
        "neutral": 5,
        "negative": 2,
        "avgScore": 7.8,
        "count": 17
      }
    ],
    "topSources": [
      {
        "sourceName": "ChatGPT",
        "count": 80,
        "avgScore": 7.9
      }
    ],
    "queryTypes": [
      {
        "type": "neutral",
        "count": 100,
        "avgScore": 7.8,
        "positive": 70,
        "neutral": 20,
        "negative": 10
      }
    ],
    "problematicAnswers": [],
    "bestAnswers": [],
    "brandAnalytics": {
      "monthlyTrend": [],
      "correlations": [],
      "insights": []
    }
  }
}

Успешный ответ

Аналитика ссылок

/api/v1/analytics/links

Аналитика ссылок из ответов AI-ассистентов: топ-домены, цитирование по провайдерам, timeline. Поддерживает фильтрацию по тональности, кластерам, типу запроса, порогам Impact/Overall Score и кастомный период. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).

Параметры запроса

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

labelSlugstring[]

sortDomainsBystring

Сортировка доменов

sentimentstring

Фильтр по тональности

positiveneutralnegative

minImpactnumber

Минимальный порог Impact Score

minOverallnumber

Минимальный порог Overall Score

presetstring

Пресет фильтрации

queryTypestring

Тип запроса

neutralnegativecomparative

labelstring

Slug кластера

labelFilterModestring= or

Логика фильтрации

orand

fromstring (date-time)

Начало периода

tostring (date-time)

Конец периода

chartOnlystring

Только данные для графика

truefalse

citationModestring

Режим цитирования

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/links

curl -X GET "https://app.brandfound.ai/api/v1/analytics/links" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "topDomains": [
      {
        "domain": "samsung.com",
        "name": "Samsung",
        "trustRank": 95,
        "linkCount": 45,
        "mentionCount": 120,
        "sentiment": 0.8
      }
    ],
    "citationsByProvider": [
      {
        "provider": "chatgpt",
        "entityName": "Samsung",
        "isOurs": true,
        "citations": 30
      }
    ],
    "timeline": [
      {
        "date": "2026-04-01",
        "linkCount": 15
      }
    ]
  }
}

Успешный ответ

Топ домены

/api/v1/analytics/links/top-domains

Возвращает наиболее цитируемые домены в ответах AI-ассистентов. Поддерживает фильтрацию по тональности, типу запроса, порогам Impact/Overall Score и демо-данные. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).

Параметры запроса

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

limitinteger= 10

Количество доменов

includeDemostring

Включить демо-данные

truefalse

sentimentstring

Фильтр по тональности

positiveneutralnegative

minImpactnumber

Минимальный порог Impact Score

minOverallnumber

Минимальный порог Overall Score

queryTypestring

Тип запроса

neutralnegativecomparative

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/links/top-domains

curl -X GET "https://app.brandfound.ai/api/v1/analytics/links/top-domains" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "domain": "samsung.com",
      "name": "Samsung",
      "trustRank": 95,
      "linkCount": 45,
      "mentionCount": 120,
      "sentiment": 0.8
    },
    {
      "domain": "apple.com",
      "name": "Apple",
      "trustRank": 97,
      "linkCount": 52,
      "mentionCount": 140,
      "sentiment": 0.75
    }
  ]
}

Успешный ответ

Видимость бренда

/api/v1/analytics/brand-visibility

Timeline видимости бренда в сравнении с конкурентами с настраиваемой гранулярностью. Поддерживает фильтрацию по кластерам (ID и slug), AI-провайдерам и режим логики фильтрации.

Параметры запроса

granularitystring= day

Гранулярность временной оси

dayweekmonth

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

fromstring (date-time)

tostring (date-time)

labelIdstring

ID кластера. Массив: ?labelId=id1&labelId=id2

labelSlugstring

Slug кластера

labelFilterModestring= or

Логика фильтрации

orand

sourceIdstring

ID AI-источника

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/brand-visibility

curl -X GET "https://app.brandfound.ai/api/v1/analytics/brand-visibility" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "timeline": [
      {
        "period": "2026-04-01",
        "periodLabel": "1 апр",
        "our": 15,
        "competitors": {
          "Apple": 18,
          "Google": 12
        }
      }
    ],
    "summary": {
      "trend": "growing"
    }
  }
}

Успешный ответ

Динамика цитируемости

/api/v1/analytics/links/citation-timeline

Доля ответов, где нас цитируют, против конкурентов, по дням. Считается по дневным роллапам, поэтому поддерживается только режим «цитирование в целом»: роллап не различает цитирование по URL и по домену.

Параметры запроса

companyIdstring (uuid)

Компания. Без него подставляется preferredCompanyId ключа

productIdstring

Продукт

timeRangestring

24h | 7d | 30d | 90d | all

granularitystring

Разрез динамики

tzstring

Часовой пояс

sourceIdstring[]

Источники

labelSlugstring[]

Кластеры

labelFilterModestring

AND | OR

includeDemoboolean

Включить демо-данные

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/analytics/links/citation-timeline

curl -X GET "https://app.brandfound.ai/api/v1/analytics/links/citation-timeline" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Компании и продукты для фильтров

/api/v1/analytics/companies-products

Компании аккаунта вместе с их продуктами — источник для селектора «компания → продукт». companyId здесь НЕ обязателен: без него возвращаются все компании, и это ровно то, зачем метод нужен.

Параметры запроса

companyIdstring (uuid)

Сузить до одной компании

includeDemoboolean

Включить демо-данные

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/companies-products

curl -X GET "https://app.brandfound.ai/api/v1/analytics/companies-products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Ссылки

Домены и ссылки из AI-ответов

Домены и ссылки

/api/v1/links

Двухуровневая таблица доменов и ссылок из ответов AI-ассистентов с сортировкой и фильтрацией. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).

Параметры запроса

pageinteger= 1

Номер страницы

pageSizeinteger= 50

Размер страницы

sortBystring= lastMentioned

lastMentionedmentionCountanswerCountourMentionCountcompetitorMentionCountdomaintrustRankdomainLinks

sortDirstring= desc

ascdesc

searchstring

Поисковый запрос (case-insensitive)

searchFieldstring

Поле для поиска

domainurltitle

timeRangestring

24h7d30d

fromstring (date-time)

tostring (date-time)

companyIdstring (uuid)

productIdstring (uuid)

sentimentstring

positiveneutralnegative

queryTypestring

neutralnegativecomparative

providerstring[]

AI-провайдеры

activestring

Только активные ссылки

truefalse

domainsOnlystring

Только домены (без подссылок)

truefalse

domainstring

Подссылки конкретного домена

labelstring[]

Кластеры/лейблы

includeDemostring

truefalse

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/links

curl -X GET "https://app.brandfound.ai/api/v1/links" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 120,
    "hasMore": true,
    "rows": [
      {
        "domain": "samsung.com",
        "trustRank": 95,
        "mentionCount": 45,
        "answerCount": 30,
        "ourMentionCount": 40,
        "competitorMentionCount": 5,
        "lastMentioned": "2026-04-05T12:00:00.000Z",
        "domainLinks": 8
      }
    ]
  }
}

Успешный ответ

Опции фильтров ссылок

/api/v1/links/filter-options

Возвращает доступные значения для фильтров таблицы ссылок: провайдеры и лейблы. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/links/filter-options

curl -X GET "https://app.brandfound.ai/api/v1/links/filter-options" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "providers": [
      {
        "value": "chatgpt",
        "label": "ChatGPT"
      },
      {
        "value": "gemini",
        "label": "Gemini"
      },
      {
        "value": "claude",
        "label": "Claude"
      },
      {
        "value": "perplexity",
        "label": "Perplexity"
      }
    ],
    "labels": [
      {
        "value": "brand-queries",
        "label": "Брендовые запросы"
      }
    ]
  }
}

Успешный ответ

Аналитика рекламных и промо-блоков в ответах AI-ассистентов. Поддерживает пагинацию, поиск по домену/URL, фильтрацию по кластерам, типу промо, периоду и сортировку. companyId обязателен: без него ответ склеил бы все компании аккаунта в одни цифры. Если не передан — подставляется preferredCompanyId ключа (см. GET /api/v1/context).

Параметры запроса

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

pageinteger= 1

Номер страницы

pageSizeinteger= 50

Размер страницы

searchstring

Поиск по домену или URL

searchFieldstring

Поле поиска

domainurltitle

labelstring

Slug кластера. Массив: ?label=slug1&label=slug2

promoTypestring

Тип промо-блока

sortBystring

Поле сортировки

sortDirstring

Направление сортировки

ascdesc

fromstring (date-time)

Начало периода (ISO 8601)

tostring (date-time)

Конец периода (ISO 8601)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/advertising

curl -X GET "https://app.brandfound.ai/api/v1/advertising" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "summary": {
      "promoCount": 25,
      "ourPromos": 8,
      "competitorPromos": 17,
      "uniqueDomains": 12
    },
    "topDomains": [
      {
        "domain": "samsung.com",
        "count": 5,
        "isOurs": true
      },
      {
        "domain": "apple.com",
        "count": 8,
        "isOurs": false
      }
    ],
    "timeseries": [
      {
        "date": "2026-04-01",
        "count": 3
      }
    ]
  }
}

Успешный ответ

Предпросмотр рекламных блоков

/api/v1/advertising/preview

Детализация к сводке /api/v1/advertising: какие промо показывались и в каких ответах.

Параметры запроса

domainstringrequired

Домен промо. ОБЯЗАТЕЛЕН, иначе 400

companyIdstring (uuid)

Компания. Без него подставляется preferredCompanyId ключа

productIdstring

Продукт

promoTypestring

ours | competitor | other

ourscompetitorother

timeRangestring

24h | 7d | 30d | 90d | all

labelstring[]

Кластеры

labelFilterModestring

AND | OR

limitinteger= 20

1..50

offsetinteger= 0

Сдвиг

includeDemoboolean

Включить демо-данные

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/advertising/preview

curl -X GET "https://app.brandfound.ai/api/v1/advertising/preview" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Фабрика контента

Контент-фабрика: задачи, теги, обогащение, генерация планов и статей, детекция инсайтов

Список задач

/api/v1/factory/tasks

Возвращает список задач контент-фабрики с фильтрацией, пагинацией и сортировкой.

Параметры запроса

companyIdstring (uuid)

Фильтр по компании

statusstring[]

Фильтр по статусу (можно несколько: ?status=TODO&status=IN_PROGRESS)

typestring[]

Фильтр по типу задачи (можно несколько)

prioritystring[]

Фильтр по приоритету (можно несколько)

searchstring

Поиск по названию и описанию задачи

tagIdstring (uuid)

Фильтр по тегу

aiGeneratedboolean

Фильтр: только AI-сгенерированные задачи

sortBystring= createdAt

createdAtupdatedAtprioritystatusposition

sortOrderstring= desc

Порядок сортировки

ascdesc

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/factory/tasks

curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "title": "Написать FAQ по Galaxy S25",
      "status": "TODO",
      "type": "CREATE_FAQ",
      "priority": "HIGH",
      "position": 1,
      "aiGenerated": true,
      "aiReasoning": "Обнаружен content gap по FAQ-запросам",
      "aiConfidence": 0.87,
      "description": "Создать FAQ на основе частых вопросов пользователей",
      "targetKeywords": [
        "galaxy s25 faq",
        "samsung s25 характеристики"
      ],
      "targetProviders": [
        "chatgpt",
        "gemini"
      ],
      "companyId": "clx1abc2d0001abcdef123456",
      "companyName": "Samsung",
      "companyFavicon": "https://samsung.com/favicon.ico",
      "dueDate": "2026-04-20T00:00:00.000Z",
      "tags": [
        {
          "id": "tag-001",
          "name": "FAQ",
          "color": "#6366f1",
          "icon": null,
          "isSystem": false,
          "position": 0
        }
      ],
      "metadata": {},
      "createdAt": "2026-04-07T12:00:00.000Z",
      "updatedAt": "2026-04-07T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Создать задачу

/api/v1/factory/tasks

Создаёт новую задачу контент-фабрики.

Тело запроса

titlestringrequired

Название задачи

companyIdstringrequired

ID компании

typestringrequired

Тип задачи

NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDY

prioritystring= MEDIUM

Приоритет

CRITICALHIGHMEDIUMLOW

descriptionstring

Описание задачи

targetKeywordsstring[]

Целевые ключевые слова (макс. 20)

targetProvidersstring[]

Целевые AI-провайдеры

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tasks

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Написать FAQ по Galaxy S25",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "CREATE_FAQ",
  "priority": "HIGH",
  "description": "Создать FAQ на основе частых вопросов пользователей",
  "targetKeywords": [
    "galaxy s25 faq",
    "samsung s25 характеристики"
  ],
  "targetProviders": [
    "chatgpt",
    "gemini"
  ]
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Успешный ответ

Получить задачу

/api/v1/factory/tasks/{id}

Возвращает полную информацию о задаче контент-фабрики.

Параметры запроса

idstring (uuid)required

ID задачи

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/factory/tasks/{id}

curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Успешный ответ

Обновить задачу

/api/v1/factory/tasks/{id}

Частичное обновление задачи контент-фабрики.

Параметры запроса

idstring (uuid)required

ID задачи

Тело запроса

statusstring

IDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSED

prioritystring

CRITICALHIGHMEDIUMLOW

titlestring

descriptionstring

tagIdsstring[]

Массив ID тегов для привязки

targetKeywordsstring[]

targetProvidersstring[]

dueDatestring

Дедлайн задачи

metadataobject

Произвольные метаданные задачи

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PATCH/api/v1/factory/tasks/{id}

curl -X PATCH "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "tagIds": [
    "tag-001",
    "tag-002"
  ]
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

Успешный ответ

Архивировать задачу

/api/v1/factory/tasks/{id}

Архивирование задачи. Данные сохраняются, но задача переходит в статус DISMISSED.

Параметры запроса

idstring (uuid)required

ID задачи

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/factory/tasks/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

// No Content

Успешно удалено

Обогатить задачу

/api/v1/factory/tasks/{id}/enrich

RAG-поиск по базе источников, анализ конкурентов, AI-рекомендации.

Параметры запроса

idstring (uuid)required

ID задачи

Тело запроса

topicstringrequired

Тема для обогащения

descriptionstring

Дополнительное описание

keywordsstring[]

Ключевые слова для RAG-поиска

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tasks/{id}/enrich

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/enrich" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Samsung Galaxy S25 FAQ",
  "description": "Часто задаваемые вопросы о Galaxy S25",
  "keywords": [
    "galaxy s25",
    "samsung",
    "характеристики"
  ]
}'

{
  "success": true,
  "data": {}
}

Успешный ответ

Сгенерировать план

/api/v1/factory/tasks/{id}/plan

Генерация плана статьи на основе обогащённых данных: структура, заголовки, ключевые тезисы, tone of voice.

Параметры запроса

idstring (uuid)required

ID задачи

Тело запроса

promptstring

Дополнительные инструкции для генерации плана

topicIdstring

ID выбранной темы (из suggest topics)

topicTitlestring

Название темы

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tasks/{id}/plan

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/plan" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Сфокусируйся на сравнении с iPhone 16",
  "topicId": "topic-001",
  "topicTitle": "Samsung Galaxy S25 vs iPhone 16: полное сравнение"
}'

{
  "success": true,
  "data": {
    "plan": {},
    "usage": {
      "inputTokens": 1,
      "outputTokens": 1
    }
  }
}

Успешный ответ

Сгенерировать статью

/api/v1/factory/tasks/{id}/article

Генерация статьи по плану (SSE-стриминг). Content-Type: text/event-stream.

Параметры запроса

idstring (uuid)required

ID задачи

Тело запроса

planIdstring

ID плана для генерации статьи

articleLengthstring= medium

Длина статьи: short (~1000 слов), medium (~2000), long (~3500)

shortmediumlong

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tasks/{id}/article

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/article" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan-001",
  "articleLength": "medium"
}'

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Необходима авторизация"
  }
}

Необходима авторизация

Версии контента

/api/v1/factory/tasks/{id}/versions

Возвращает список версий контента (планов, статей, брифов) для задачи.

Параметры запроса

idstring (uuid)required

ID задачи

typestring

Фильтр по типу контента

planarticlebrief

planIdstring

Фильтр по ID плана

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/factory/tasks/{id}/versions

curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}/versions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "type": "plan",
      "version": 1,
      "content": {},
      "createdAt": "2026-01-15T12:00:00Z"
    }
  ]
}

Успешный ответ

Аналитика задачи

/api/v1/factory/tasks/{id}/analytics

Возвращает аналитику по задаче: статистика обогащения, генераций, публикаций.

Параметры запроса

idstring (uuid)required

ID задачи

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/factory/tasks/{id}/analytics

curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}/analytics" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {}
}

Успешный ответ

Предложить темы

/api/v1/factory/tasks/{id}/topics

Генерация 10 тем на основе данных задачи.

Параметры запроса

idstring (uuid)required

ID задачи

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tasks/{id}/topics

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/topics" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "title": "example_title",
      "description": "example_description",
      "keywords": [
        "example"
      ],
      "score": 1
    }
  ]
}

Успешный ответ

Список тегов

/api/v1/factory/tags

Возвращает все теги контент-фабрики с количеством задач.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/factory/tags

curl -X GET "https://app.brandfound.ai/api/v1/factory/tags" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "tag-001",
      "name": "FAQ",
      "color": "#6366f1",
      "icon": null,
      "isSystem": false,
      "position": 0,
      "taskCount": 5
    },
    {
      "id": "tag-002",
      "name": "SEO",
      "color": "#10b981",
      "icon": "search",
      "isSystem": true,
      "position": 1,
      "taskCount": 12
    }
  ]
}

Успешный ответ

Создать тег

/api/v1/factory/tags

Создаёт новый тег для задач контент-фабрики.

Тело запроса

namestringrequired

Название тега

colorstring

HEX цвет, напр. #6366f1

iconstring

Иконка тега (опционально)

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

409application/json

Ресурс с таким именем уже существует

CONFLICT

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tags

curl -X POST "https://app.brandfound.ai/api/v1/factory/tags" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ",
  "color": "#6366f1",
  "icon": "help-circle"
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "color": "example_color",
    "icon": "example_icon",
    "isSystem": true,
    "position": 1,
    "taskCount": 1
  }
}

Успешный ответ

Обновить тег

/api/v1/factory/tags/{id}

Частичное обновление тега контент-фабрики.

Параметры запроса

idstring (uuid)required

ID тега

Тело запроса

namestring

colorstring

iconstring

positioninteger

Позиция сортировки

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

409application/json

Ресурс с таким именем уже существует

CONFLICT

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PATCH/api/v1/factory/tags/{id}

curl -X PATCH "https://app.brandfound.ai/api/v1/factory/tags/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ Updated",
  "color": "#8b5cf6",
  "position": 2
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "color": "example_color",
    "icon": "example_icon",
    "isSystem": true,
    "position": 1,
    "taskCount": 1
  }
}

Успешный ответ

Удалить тег

/api/v1/factory/tags/{id}

Удаление тега. Системные теги удалить нельзя.

Параметры запроса

idstring (uuid)required

ID тега

Ответы

401application/json

Необходима авторизация

UNAUTHORIZED

403application/json

Недостаточно прав

FORBIDDEN

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/factory/tags/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/factory/tags/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

// No Content

Успешно удалено

Список публикаций

/api/v1/factory/publications

Возвращает список публикаций контент-фабрики с пагинацией.

Параметры запроса

companyIdstring (uuid)

Фильтр по компании

offsetinteger= 0

Смещение для пагинации

limitinteger= 20

Количество записей на страницу

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/factory/publications

curl -X GET "https://app.brandfound.ai/api/v1/factory/publications" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "pub-001",
      "url": "https://samsung.com/blog/galaxy-s25-faq",
      "platform": "blog",
      "publishedAt": "2026-04-10T12:00:00.000Z",
      "planId": "plan-001",
      "planTitle": "FAQ по Galaxy S25",
      "notes": null,
      "taskId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "taskTitle": "Написать FAQ по Galaxy S25",
      "companyId": "clx1abc2d0001abcdef123456"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Успешный ответ

Детекция инсайтов

/api/v1/factory/insights

Запуск детекторов (15 типов): content gaps, competitor wins, white space, reputation risks и др.

Тело запроса

companyIdstringrequired

ID компании

insightTypestring

Тип инсайта (если не указан — запуск всех детекторов)

CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDING

limitinteger

Максимальное количество инсайтов

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/insights

curl -X POST "https://app.brandfound.ai/api/v1/factory/insights" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "insightType": "CONTENT_GAP",
  "limit": 10
}'

{
  "success": true,
  "data": {
    "company": "Samsung",
    "insightsFound": 5,
    "tasksCreated": 3,
    "savedTaskIds": [
      "task-001",
      "task-002",
      "task-003"
    ],
    "byType": {
      "CONTENT_GAP": 2,
      "COMPETITOR_WIN": 1,
      "WHITE_SPACE": 2
    }
  }
}

Успешный ответ

Настройки фабрики

/api/v1/factory/settings

Возвращает текущие настройки контент-фабрики пользователя.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/factory/settings

curl -X GET "https://app.brandfound.ai/api/v1/factory/settings" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {}
}

Успешный ответ

Обновить настройки

/api/v1/factory/settings

Обновление настроек контент-фабрики (deep merge).

Тело запроса

settingsobjectrequired

Объект настроек для deep merge с текущими

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PATCH/api/v1/factory/settings

curl -X PATCH "https://app.brandfound.ai/api/v1/factory/settings" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "defaultPriority": "MEDIUM",
    "autoEnrich": true,
    "preferredProviders": [
      "chatgpt",
      "gemini"
    ]
  }
}'

{
  "success": true,
  "data": {}
}

Успешный ответ

Карта бренда

/api/v1/factory/brand-card

Чтение карты бренда — дерева markdown-документов компании (знания о бренде, учитываются при генерации контента). Три режима: без доп. параметров — вся карта одним markdown (манифест → core-файлы → связанные ссылками → остальные; приватные блоки ```private вырезаны; лимит ~12 000 символов); mode=index — манифест + список файлов с path, id, isCore и исходящими ссылками (граф связей); path=... — один файл: content (ссылки [Имя](brandcard://id) сохранены дословно) + links с резолвом каждой ссылки в путь.

Параметры запроса

companyIdstring (uuid)required

ID компании

modestring

index — вернуть манифест и список файлов вместо полной карты

index

pathstring

Путь файла как в индексе (например "main / settings.md") — вернуть один файл. Регистр не важен

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/factory/brand-card

curl -X GET "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {}
}

Успешный ответ

Создать/обновить файл карты

/api/v1/factory/brand-card

Создаёт или полностью перезаписывает файл карты бренда по пути; недостающие папки создаются автоматически, без расширения добавляется .md. Чтобы сослаться на другой файл карты, вставьте в markdown ссылку [Имя](brandcard://<id из индекса>) — она живёт по id (переживает переименование и перенос) и поднимает приоритет целевого файла при генерации. Существующие brandcard://-ссылки при редактировании сохраняйте дословно. Личные заметки и опции оборачивайте в блок ```private — они не отправляются в нейросети.

Тело запроса

companyIdstringrequired

ID компании

pathstringrequired

Путь файла, сегменты через "/", например "products / pricing.md"

contentstringrequired

Полный markdown файла (перезаписывает текущее содержимое)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/brand-card

curl -X POST "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "9f1c0e2a-…",
  "path": "products / pricing.md",
  "content": "# Прайс\n\nТариф Лайт — 1900 ₽/мес.\n\nСм. также: [Настройки](brandcard://b7e2…)"
}'

{
  "success": true,
  "data": {
    "path": "example_path",
    "created": true
  }
}

Успешный ответ

Удалить файл/папку карты

/api/v1/factory/brand-card

Удаляет файл или папку карты бренда по пути (папка — каскадно со всем содержимым). Служебный каркас (instruction.md, README.md, core-файлы) удалить нельзя — редактируйте его через POST. После удаления файла ссылки на него становятся висячими: в индексе пропадают из links, при чтении файла отдаются с path=null.

Параметры запроса

companyIdstring (uuid)required

ID компании

pathstringrequired

Путь файла или папки (как в индексе)

Ответы

204

Успешно удалено

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/factory/brand-card

curl -X DELETE "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "deleted": true,
    "path": "example_path"
  }
}

Успешный ответ

Баланс и расходы

Баланс FoxCoin и история операций

Баланс FoxCoin и прейскурант

/api/v1/billing/balance

Остаток, оборот и цены операций. Кошелёк общий на аккаунт: участники команды тратят из пула владельца. Прейскурант отдаётся здесь, чтобы не зашивать цены в код интеграции.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/billing/balance

curl -X GET "https://app.brandfound.ai/api/v1/billing/balance" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "balance": 1,
    "totalEarned": 1,
    "totalSpent": 1,
    "billingEnabled": true,
    "pricing": {
      "coinToRub": 1,
      "minTopUpRub": 1,
      "answer": 1,
      "generatedQuery": 1,
      "brandCardGeneration": 1,
      "taskEnrichment": 1,
      "contentPlan": 1,
      "articleGeneration": 1,
      "topicSuggestion": 1,
      "factCheck": 1
    }
  }
}

Успешный ответ

История списаний и пополнений

/api/v1/billing/transactions

Журнал операций кошелька. У списаний за ответы поле query показывает, за какой именно запрос списано.

Параметры запроса

typestring

Фильтр по типу операции

ANSWER_CHARGEQUERY_GENERATIONBRAND_CARD_GENERATIONTASK_ENRICHMENTARTICLE_GENERATIONCONTENT_PLANTOPIC_SUGGESTIONFACT_CHECKTOPUPBONUSREFUNDMANUAL_ADJUSTMENTSUBSCRIPTION_CREDITAPI_CALL_FREE

fromstring (date-time)

Начало окна, ISO-дата (включительно)

tostring (date-time)

Конец окна, ISO-дата (включительно)

limitinteger= 50

Размер страницы

offsetinteger= 0

Сдвиг

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/billing/transactions

curl -X GET "https://app.brandfound.ai/api/v1/billing/transactions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "amount": 1,
      "type": "ANSWER_CHARGE",
      "description": "example_description",
      "referenceId": "example_referenceId",
      "referenceType": "example_referenceType",
      "balanceAfter": 1,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00Z",
      "query": {
        "text": "example_text",
        "origin": "example_origin",
        "companyName": "example_companyName"
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Успешный ответ

Справочники

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

Справочник нейросетей

/api/v1/sources

Какие ассистенты доступны для опроса и какие из них подставляются по умолчанию. Значение value — то, что принимает providers в POST /api/v1/queries/setup. Имена вне этого списка молча отбрасываются при постановке в очередь.

Параметры запроса

includeUnpollableboolean= false

Добавить claude (легаси-очередь, в контуре не опрашивается)

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/sources

curl -X GET "https://app.brandfound.ai/api/v1/sources" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": [
    {
      "value": "chatgpt",
      "label": "example_label",
      "pollable": true,
      "defaultForAccount": true
    }
  ]
}

Успешный ответ

Контекст ключа

/api/v1/context

С чего стоит начинать интеграцию: какому аккаунту принадлежит ключ, какие у него права, какие компании и продукты доступны и какая компания подставляется по умолчанию.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/context

curl -X GET "https://app.brandfound.ai/api/v1/context" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "accountId": "example_accountId",
    "userId": "example_userId",
    "defaultCompanyId": "example_defaultCompanyId",
    "companies": [
      {
        "id": "example_id",
        "name": "example_name",
        "isDefault": true,
        "products": [
          {
            "id": "example_id",
            "name": "example_name"
          }
        ]
      }
    ],
    "apiKey": {
      "name": "example_name",
      "scopes": [
        "example"
      ],
      "expiresAt": "2026-01-15T12:00:00Z",
      "source": "example_source"
    },
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId",
    "availableWorkspaces": [
      {
        "accountId": "example_accountId",
        "role": "owner",
        "ownerName": "example_ownerName",
        "ownerEmail": "example_ownerEmail",
        "companiesCount": 0,
        "isCurrent": true,
        "teamRoleName": "example_teamRoleName",
        "teamRoleKey": "example_teamRoleKey"
      }
    ]
  }
}

Успешный ответ

AI-трафик

Переходы на сайт из ответов нейросетей (Яндекс.Метрика)

AI-трафик

/api/v1/analytics/metrika/ai-traffic

Переходы на сайт из ответов нейросетей: сколько визитов принесла каждая сеть и как это менялось. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/ai-traffic

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/ai-traffic" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Посетители из нейросетей

/api/v1/analytics/metrika/visitors

Визиты с AI-источником и поведение на сайте: глубина просмотра, цели, повторные заходы. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

hasGoalsboolean

Только визиты с достигнутыми целями

includeSyntheticboolean

Включить синтетический трафик

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/visitors

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/visitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Воронка AI-трафика

/api/v1/analytics/metrika/traffic-funnel

Путь от перехода из ответа нейросети до целевого действия. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

hasGoalsboolean

Только визиты с достигнутыми целями

includeSyntheticboolean

Включить синтетический трафик

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/traffic-funnel

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/traffic-funnel" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Упоминания против трафика

/api/v1/analytics/metrika/correlation

Сопоставляет динамику упоминаний бренда с динамикой реальных переходов: даёт ли рост видимости рост трафика. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

companyIdstring (uuid)

Компания. Без него подставляется preferredCompanyId ключа

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

24h | 7d | 30d | 90d | all

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/correlation

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/correlation" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Цели Метрики

/api/v1/analytics/metrika/goals

Справочник целей счётчика — что стоит за параметром hasGoals в остальных методах. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

includeInactiveboolean

Включить неактивные цели

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/goals

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/goals" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Сводка по синтетическому трафику

/api/v1/analytics/metrika/synthetic/summary

Доля ботовых и неорганических визитов, чтобы они не искажали выводы по AI-трафику. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

filterstring

Фильтр классификации

hasGoalsboolean

Только визиты с достигнутыми целями

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/synthetic/summary

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/synthetic/summary" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Список синтетических визитов

/api/v1/analytics/metrika/synthetic/list

Постраничная детализация к сводке: конкретные визиты с признаками синтетики. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Параметры запроса

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

24h | 7d | 30d | 90d | all

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

filterstring

Фильтр классификации

qstring

Поиск

qScopestring

Область поиска

hasRevenueboolean

Только с доходом

returningOnlyboolean

Только вернувшиеся

pageinteger

Страница

pageSizeinteger

Размер страницы

sortBystring

Поле сортировки

sortOrderstring

asc | desc

hasGoalsboolean

Только визиты с достигнутыми целями

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/analytics/metrika/synthetic/list

curl -X GET "https://app.brandfound.ai/api/v1/analytics/metrika/synthetic/list" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Подключённые счётчики

/api/v1/integrations/metrika/list

С этого метода начинается работа с AI-трафиком: возвращает integrationId для остальных методов раздела.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/integrations/metrika/list

curl -X GET "https://app.brandfound.ai/api/v1/integrations/metrika/list" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Состояние интеграции

/api/v1/integrations/metrika/status

Подключена ли Метрика, когда была синхронизация и не истёк ли доступ. Пустая выдача методов раздела объясняется здесь.

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/integrations/metrika/status

curl -X GET "https://app.brandfound.ai/api/v1/integrations/metrika/status" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Коммерс

Товарные карточки в ответах нейросетей

Коммерс-аналитика

/api/v1/analytics/commerce

Товарные карточки, которые нейросети показывают вместе с текстом ответа. view=summary — доля ответов с карточками и динамика по сетям; sellers — топ продавцов и доменов; brands — карточки нашего бренда против конкурентов; cards — постраничный список.

Параметры запроса

viewstring= summary

summary | sellers | brands | cards

summarysellersbrandscards

companyIdstring (uuid)

Компания. Без него подставляется preferredCompanyId ключа

productIdstring[]

Можно передать несколько

timeRangestring

24h | 7d | 30d | 90d | all

granularitystring

Разрез динамики

tzstring

Часовой пояс

labelIdstring[]

Кластеры

labelSlugstring[]

Кластеры по slug

labelFilterModestring

AND | OR

sourceIdstring[]

Источники

queryTypestring[]

Типы запросов

includeDemoboolean

Включить демо-данные

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/analytics/commerce

curl -X GET "https://app.brandfound.ai/api/v1/analytics/commerce" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Отслеживаемые товары

/api/v1/commerce/products

Номенклатура для сопоставления с карточками в ответах. Без неё раздел «Коммерс» показывает продавцов и домены, но не «наш товар против чужого».

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/commerce/products

curl -X GET "https://app.brandfound.ai/api/v1/commerce/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Добавить товар

/api/v1/commerce/products

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/commerce/products

curl -X POST "https://app.brandfound.ai/api/v1/commerce/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Мониторинг

Регулярный опрос запросов по расписанию

Запросы на мониторинге

/api/v1/favorite-queries

Список запросов, поставленных на регулярный опрос.

Параметры запроса

searchstring

Поиск по тексту

activeboolean

Только включённые

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

GET/api/v1/favorite-queries

curl -X GET "https://app.brandfound.ai/api/v1/favorite-queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Поставить запрос на мониторинг

/api/v1/favorite-queries

Обычный POST /api/v1/queries опрашивает нейросети ОДИН раз. Регулярный опрос — это отдельная сущность, и создаётся она здесь. Создание записи опрос ещё не запускает: расписание задаётся вторым шагом, через POST /api/v1/favorite-queries/{id}/assignments. Каждый опрос по расписанию платный: 10 FoxCoin за ответ КАЖДОЙ нейросети. Интервал 60 минут по трём сетям — это 720 ответов в сутки. При нехватке средств опросы уходят на паузу и сами не возобновятся (POST /api/v1/queries/queue/resume).

Тело запроса

textstringrequired

typestringrequired

companyIdstring

productIdstring

languagestring= ru

regionstring= RU

isActiveboolean= true

tagsstring[]

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/favorite-queries

curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "best threat intelligence vendors for banks in UAE",
  "type": "comparative",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "language": "en",
  "region": "AE"
}'

{
  "success": true
}

Успешный ответ

Запись мониторинга

/api/v1/favorite-queries/{id}

Параметры запроса

idstring (uuid)required

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/favorite-queries/{id}

curl -X GET "https://app.brandfound.ai/api/v1/favorite-queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Изменить запись

/api/v1/favorite-queries/{id}

Текст, компания, теги, isActive. Снять с опроса без удаления — isActive: false.

Параметры запроса

idstring (uuid)required

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

PATCH/api/v1/favorite-queries/{id}

curl -X PATCH "https://app.brandfound.ai/api/v1/favorite-queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Снять с мониторинга

/api/v1/favorite-queries/{id}

Удаляет запись вместе с расписанием: следующего опроса не будет. Уже полученные ответы и упоминания остаются — они принадлежат запросу, а не подписке.

Параметры запроса

idstring (uuid)required

Ответы

204

Успешно удалено

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

DELETE/api/v1/favorite-queries/{id}

curl -X DELETE "https://app.brandfound.ai/api/v1/favorite-queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Расписание опроса

/api/v1/favorite-queries/{id}/assignments

Параметры запроса

idstring (uuid)required

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

GET/api/v1/favorite-queries/{id}/assignments

curl -X GET "https://app.brandfound.ai/api/v1/favorite-queries/{id}/assignments" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ

Задать расписание

/api/v1/favorite-queries/{id}/assignments

Именно здесь запрос начинает опрашиваться регулярно: запись без расписания ничего не делает. Расписание одно на запись, повторный вызов его перезаписывает. Каждый опрос по расписанию платный: 10 FoxCoin за ответ КАЖДОЙ нейросети. Интервал 60 минут по трём сетям — это 720 ответов в сутки. При нехватке средств опросы уходят на паузу и сами не возобновятся (POST /api/v1/queries/queue/resume).

Параметры запроса

idstring (uuid)required

Тело запроса

providersstring[]required

Список: GET /api/v1/sources

frequencyMinutesintegerrequired

Интервал между опросами

isEnabledboolean= true

Пауза без удаления расписания

timezonestring= Europe/Moscow

В нём считаются daysOfWeek и hoursWindow

daysOfWeekinteger[]

1..7, пусто = каждый день

hoursWindowobject

Окно часов, вне которого опрос не идёт

modelobject

Карта «нейросеть → модель»

Ответы

200

Успешный ответ

400application/json

Ошибка валидации

VALIDATION_ERROR

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/favorite-queries/{id}/assignments

curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries/{id}/assignments" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "providers": [
    "chatgpt",
    "perplexity",
    "gemini"
  ],
  "frequencyMinutes": 1440,
  "timezone": "Europe/Moscow"
}'

{
  "success": true
}

Успешный ответ

Опросить сейчас

/api/v1/favorite-queries/{id}/run-now

Внеочередной опрос, не дожидаясь расписания и не сдвигая его. Платно на общих основаниях.

Параметры запроса

idstring (uuid)required

Ответы

200

Успешный ответ

401application/json

Необходима авторизация

UNAUTHORIZED

404application/json

Ресурс не найден

NOT_FOUND

429application/json

Превышен лимит запросов. Повторите через 60 секунд.

RATE_LIMIT_EXCEEDED

POST/api/v1/favorite-queries/{id}/run-now

curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries/{id}/run-now" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true
}

Успешный ответ