v1.2.0

brandfound. API

API for tracking brand mentions in AI assistants (ChatGPT, Gemini, Claude, Perplexity). Manage companies, products, competitors, queries, mentions, and analytics.

Base URL

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

Playground

Click in the request panel to open the interactive Playground. Pick an API key, set parameters, and send the request directly from the docs.

Quick start

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

Successful response

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

Error

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

Rate limits

Per IP address120 / min

Per user60 / min

Error codes

401

UNAUTHORIZEDInvalid authorization

403

FORBIDDENInsufficient permissions

404

NOT_FOUNDResource not found

400

VALIDATION_ERRORValidation error

429

RATE_LIMIT_EXCEEDEDRate limit exceeded

500

INTERNAL_ERRORInternal error

What is new in version 1.2

Public method URLs have not changed, backward compatibility is preserved.

Analytics responds again

Methods of the Analytics, Links and Advertising sections returned a 500 error because of an issue on our side. Fixed, no action needed from you.

Query state is visible

The query list now has answersCount, the actual list of assistants in providers and a summary queue.status. Previously providers was always empty.

Polling queue

queries/queue and queue/summary show what is being polled and what it costs. Polls stopped for lack of FoxCoin are resumed via queue/resume: they do not restart on their own.

Balance and spending

billing/balance returns the balance and prices of all operations, billing/transactions returns the charge history with the related query.

Answer language

The language field now sets the answer language. Works in ChatGPT, Gemini, Perplexity and DeepSeek.

Assistant directory

The sources method returns available assistants and marks the ones used by default.

Monitoring

A query can be put on recurring polling with its own schedule. This used to be available in the web app only.

AI traffic

Site visits coming from AI answers, visitor behaviour, funnel and goals based on Yandex.Metrica data.

Commerce

Product cards in AI answers and the catalogue to match them against.

Company is now required

The links, links/filter-options, analytics/links/top-domains, analytics/competitors/preview and advertising methods require companyId. Without it the response used to merge all companies of the account.

Authentication

All API requests require authorization. Create an API key in Settings → API keyssection. Keys have the prefix gfx_.

Bearer Token

Recommended

Pass the key in the Authorization header of each request.

Session Cookie

The web app automatically uses the session-token cookie. No extra setup is required.

Request example

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

Response example

{
  "success": true,
  "data": [
    {
      "id": "comp_123",
      "name": "My company",
      "slug": "my-company"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

Workspaces

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

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/workspaces/switch

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

Request body

accountIdstringrequired

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

Responses

200

Successful response

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
  }
}

Successful response

Companies

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

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

/api/v1/companies

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

Query parameters

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)

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/companies

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

Request body

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».

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/companies/{id}

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

Query parameters

idstring (uuid)required

ID компании

Responses

200

Successful response

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": "Электроника"
    }
  }
}

Successful response

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

/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) ИГНОРИРУЕТСЯ. Это был флаг снесённого планировщика, который генерировал запросы и тем же движением ставил их в платный опрос.

Query parameters

idstring (uuid)required

ID компании

Request body

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

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/companies/{id}

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

Query parameters

idstring (uuid)required

ID компании

Responses

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

Successfully deleted

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

/api/v1/companies/categories

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

Responses

200

Successful response

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"
    }
  ]
}

Successful response

Products

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

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

/api/v1/products

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

Query parameters

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)

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/products

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

Request body

namestringrequired

companyIdstringrequired

descriptionstring

urlstring

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/products/{id}

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

Query parameters

idstring (uuid)required

ID продукта

Responses

200

Successful response

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"
          }
        ]
      }
    ]
  }
}

Successful response

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

/api/v1/products/{id}

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

Query parameters

idstring (uuid)required

ID продукта

Request body

namestring

descriptionstring

urlstring

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/products/{id}

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

Query parameters

idstring (uuid)required

ID продукта

Responses

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

Successfully deleted

Competitors

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

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

/api/v1/competitors

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

Query parameters

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)

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/competitors

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

Request body

namestringrequired

companyIdstringrequired

productIdstring

urlstring

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/competitors/{id}

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

Query parameters

idstring (uuid)required

ID конкурента

Responses

200

Successful response

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"
      }
    ]
  }
}

Successful response

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

/api/v1/competitors/{id}

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

Query parameters

idstring (uuid)required

ID конкурента

Request body

namestring

urlstring

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/competitors/{id}

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

Query parameters

idstring (uuid)required

ID конкурента

Responses

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

Successfully deleted

Keywords

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

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

/api/v1/keywords

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

Query parameters

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)

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

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/keywords

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

Request body

namestringrequired

attachobject

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

Responses

200

Successful response

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": "..."
  }
}

Successful response

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

/api/v1/keywords/{id}

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

Query parameters

idstring (uuid)required

Responses

200

Successful response

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"
        }
      }
    ]
  }
}

Successful response

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

/api/v1/keywords/{id}

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

Query parameters

idstring (uuid)required

Request body

namestringrequired

Responses

200

Successful response

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"
        }
      }
    ]
  }
}

Successful response

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

/api/v1/keywords/{id}

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

Query parameters

idstring (uuid)required

permanentboolean= false

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

dryRunboolean= false

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

Responses

204

Successfully deleted

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"
          }
        }
      ]
    }
  }
}

Successful response

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

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

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

Query parameters

idstring (uuid)required

Responses

200

Successful response

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
    }
  }
}

Successful response

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

/api/v1/keywords/attach

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

Request body

targetobjectrequired

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

namesstring[]required

Responses

200

Successful response

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"
      }
    ]
  }
}

Successful response

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

/api/v1/keywords/detach

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

Request body

targetobjectrequired

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

keywordIdsstring[]required

Responses

200

Successful response

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"
    ]
  }
}

Successful response

Queries

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

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

/api/v1/queries

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

Query parameters

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

Responses

200

Successful response

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
  }
}

Successful response

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

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

Request body

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.

Responses

200

Successful response

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
    }
  }
}

Successful response

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

/api/v1/queries/{id}

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

Query parameters

idstring (uuid)required

ID запроса

includeAnswersstring= true

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

truefalse

Responses

200

Successful response

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": []
          }
        ]
      }
    ]
  }
}

Successful response

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

/api/v1/queries/{id}

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

Query parameters

idstring (uuid)required

ID запроса

Responses

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

Successfully deleted

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

/api/v1/queries/{id}

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

Query parameters

idstring (uuid)required

Request body

textstring

typestring

neutralcommercialinformationalcomparativereputationalbranded

languagestring

regionstring

ISO 3166-1 alpha-2.

productIdstring

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

isFavoriteboolean

labelsstring[]

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

Responses

200

Successful response

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"
    }
  }
}

Successful response

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

/api/v1/queries/queue

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

Query parameters

statusstring= queued,onHold,failed

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

companyIdstring (uuid)

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

queryIdstring (uuid)

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

providerstring

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

chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_mode

includeArchivedboolean= false

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

limitinteger= 50

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

offsetinteger= 0

Сдвиг

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/queries/queue/summary

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

Query parameters

companyIdstring (uuid)

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

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/queries/setup

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

Request body

companyIdstring

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

clusterIdstring

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

providersstring[]

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

clustersobject[]required

Responses

200

Successful response

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"
        ]
      }
    ]
  }
}

Successful response

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

/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` — тогда раны, на которые средств хватит, отработают, а остальные снова встанут на паузу.

Request body

runIdsstring[]

Точечно по id ранов

scopestring

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

onHold

companyIdstring

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

forceboolean= false

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

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/queries/queue/cancel

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

Request body

runIdsstring[]

queryIdsstring[]

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

scopestring

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

onHoldqueued

companyIdstring

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

Responses

200

Successful response

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
  }
}

Successful response

Query autogeneration

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

Request body

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

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

Responses

200

Successful response

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": {}
}

Successful response

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

/api/v1/queries/autogenerate

Прогресс задач, запущенных POST /api/v1/queries/autogenerate. Опрашивайте до status = OK, затем читайте черновики через GET /api/v1/query-drafts. Черновики ещё идущей задачи (RUNNING) не подтверждаются намеренно — иначе подтвердится половина пачки.

Query parameters

runIdstring (uuid)

Конкретная задача.

clientTokenstring

Задача по клиентскому маркеру из ответа POST.

limitinteger= 20

Сколько последних задач вернуть.

Responses

200

Successful response

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"
    }
  ]
}

Successful response

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

/api/v1/queries/autogenerate/cancel

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

Request body

runIdstringrequired

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/query-drafts

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

Query parameters

statusstring

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

PENDINGAPPROVEDREJECTEDEXPIRED

companyIdstring (uuid)

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

typestring

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

neutralcommercialinformationalcomparativereputationalbranded

pageinteger= 1

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

limitinteger= 50

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

Responses

200

Successful response

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": {}
  }
}

Successful response

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

/api/v1/query-drafts/approve

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

Request body

draftIdsstring[]required

providersstring[]required

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

dryRunboolean

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

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/query-drafts/reject

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

Request body

draftIdsstring[]required

Responses

200

Successful response

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
  }
}

Successful response

AI answers

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

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

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

Query parameters

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

Responses

200

Successful response

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"
        }
      ]
    }
  ]
}

Successful response

Geo

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

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

/api/v1/geo/countries

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

Query parameters

qstring

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

continentstring

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

EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICA

limitinteger= 250

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

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/geo/regions

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

Query parameters

countryIso2string

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

countryIdstring (uuid)

UUID страны.

qstring

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

limitinteger= 100

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

Responses

200

Successful response

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": {}
}

Successful response

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

/api/v1/geo/cities

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

Query parameters

countryIso2string

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

countryIdstring (uuid)

UUID страны.

regionIdstring (uuid)

UUID региона.

qstring

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

limitinteger= 50

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

Responses

200

Successful response

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": {}
}

Successful response

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

/api/v1/geo/languages

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

Query parameters

qstring

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

limitinteger= 200

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

Responses

200

Successful response

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
  }
}

Successful response

Query Labels

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

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

/api/v1/query-labels

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

Query parameters

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

Responses

200

Successful response

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": {}
  }
}

Successful response

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

/api/v1/query-labels

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

Request body

namestringrequired

slugstring

descriptionstring

companyIdstring

productIdstring

defaultLanguageIdstring

defaultLocalestring

defaultResponseLanguageIdstring

geoScopestring

GLOBALCOUNTRYREGIONCITY

injectLocationModestring

NONEAPPEND_PARENSAPPEND_NATURALPREPENDAI_REWRITE

autogenStrategystring

SHAREDPER_TARGETPER_TARGET_LOCALIZED

targetsobject[]

Responses

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": "Ошибка валидации"
  }
}

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

Mentions

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

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

/api/v1/mentions

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

Query parameters

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

Responses

200

Successful response

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
  }
}

Successful response

Analytics

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

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

/api/v1/analytics/competitors

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

Query parameters

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

Responses

200

Successful response

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
      }
    ]
  }
}

Successful response

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

/api/v1/analytics/competitors/preview

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

Query parameters

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)

Responses

200

Successful response

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
  }
}

Successful response

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

/api/v1/analytics/tonality

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

Query parameters

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

Responses

200

Successful response

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": []
    }
  }
}

Successful response

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

/api/v1/analytics/links

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

Query parameters

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

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

Responses

200

Successful response

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
      }
    ]
  }
}

Successful response

Топ домены

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

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

Query parameters

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

limitinteger= 10

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

includeDemostring

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

truefalse

sentimentstring

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

positiveneutralnegative

minImpactnumber

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

minOverallnumber

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

queryTypestring

Тип запроса

neutralnegativecomparative

Responses

200

Successful response

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
    }
  ]
}

Successful response

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

/api/v1/analytics/brand-visibility

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

Query parameters

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-источника

Responses

200

Successful response

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"
    }
  }
}

Successful response

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

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

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

Query parameters

companyIdstring (uuid)

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

productIdstring

Продукт

timeRangestring

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

granularitystring

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

tzstring

Часовой пояс

sourceIdstring[]

Источники

labelSlugstring[]

Кластеры

labelFilterModestring

AND | OR

includeDemoboolean

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

Responses

200

Successful response

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
}

Successful response

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

/api/v1/analytics/companies-products

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

Query parameters

companyIdstring (uuid)

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

includeDemoboolean

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

Responses

200

Successful response

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
}

Successful response

Links

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

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

/api/v1/links

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

Query parameters

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

Responses

200

Successful response

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
      }
    ]
  }
}

Successful response

Опции фильтров ссылок

/api/v1/links/filter-options

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

Responses

200

Successful response

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": "Брендовые запросы"
      }
    ]
  }
}

Successful response

Advertising

Рекламные данные из AI-ответов

Рекламные данные

/api/v1/advertising

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

Query parameters

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)

Responses

200

Successful response

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
      }
    ]
  }
}

Successful response

Предпросмотр рекламных блоков

/api/v1/advertising/preview

Детализация к сводке /api/v1/advertising: какие промо показывались и в каких ответах.

Query parameters

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

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

Responses

200

Successful response

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
}

Successful response

Content Factory

Контент-фабрика: задачи, теги, обогащение, генерация планов и статей, детекция инсайтов

Список задач

/api/v1/factory/tasks

Возвращает список задач контент-фабрики с фильтрацией, пагинацией и сортировкой.

Query parameters

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

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

Responses

200

Successful response

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
  }
}

Successful response

Создать задачу

/api/v1/factory/tasks

Создаёт новую задачу контент-фабрики.

Request body

titlestringrequired

Название задачи

companyIdstringrequired

ID компании

typestringrequired

Тип задачи

NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDY

prioritystring= MEDIUM

Приоритет

CRITICALHIGHMEDIUMLOW

descriptionstring

Описание задачи

targetKeywordsstring[]

Целевые ключевые слова (макс. 20)

targetProvidersstring[]

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

Responses

200

Successful response

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"
  }
}

Successful response

Получить задачу

/api/v1/factory/tasks/{id}

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

Query parameters

idstring (uuid)required

ID задачи

Responses

200

Successful response

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"
  }
}

Successful response

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

/api/v1/factory/tasks/{id}

Частичное обновление задачи контент-фабрики.

Query parameters

idstring (uuid)required

ID задачи

Request body

statusstring

IDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSED

prioritystring

CRITICALHIGHMEDIUMLOW

titlestring

descriptionstring

tagIdsstring[]

Массив ID тегов для привязки

targetKeywordsstring[]

targetProvidersstring[]

dueDatestring

Дедлайн задачи

metadataobject

Произвольные метаданные задачи

Responses

200

Successful response

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"
  }
}

Successful response

Архивировать задачу

/api/v1/factory/tasks/{id}

Архивирование задачи. Данные сохраняются, но задача переходит в статус DISMISSED.

Query parameters

idstring (uuid)required

ID задачи

Responses

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

Successfully deleted

Обогатить задачу

/api/v1/factory/tasks/{id}/enrich

RAG-поиск по базе источников, анализ конкурентов, AI-рекомендации.

Query parameters

idstring (uuid)required

ID задачи

Request body

topicstringrequired

Тема для обогащения

descriptionstring

Дополнительное описание

keywordsstring[]

Ключевые слова для RAG-поиска

Responses

200

Successful response

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": {}
}

Successful response

Сгенерировать план

/api/v1/factory/tasks/{id}/plan

Генерация плана статьи на основе обогащённых данных: структура, заголовки, ключевые тезисы, tone of voice.

Query parameters

idstring (uuid)required

ID задачи

Request body

promptstring

Дополнительные инструкции для генерации плана

topicIdstring

ID выбранной темы (из suggest topics)

topicTitlestring

Название темы

Responses

200

Successful response

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
    }
  }
}

Successful response

Сгенерировать статью

/api/v1/factory/tasks/{id}/article

Генерация статьи по плану (SSE-стриминг). Content-Type: text/event-stream.

Query parameters

idstring (uuid)required

ID задачи

Request body

planIdstring

ID плана для генерации статьи

articleLengthstring= medium

Длина статьи: short (~1000 слов), medium (~2000), long (~3500)

shortmediumlong

Responses

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

Возвращает список версий контента (планов, статей, брифов) для задачи.

Query parameters

idstring (uuid)required

ID задачи

typestring

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

planarticlebrief

planIdstring

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

Responses

200

Successful response

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"
    }
  ]
}

Successful response

Аналитика задачи

/api/v1/factory/tasks/{id}/analytics

Возвращает аналитику по задаче: статистика обогащения, генераций, публикаций.

Query parameters

idstring (uuid)required

ID задачи

Responses

200

Successful response

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": {}
}

Successful response

Предложить темы

/api/v1/factory/tasks/{id}/topics

Генерация 10 тем на основе данных задачи.

Query parameters

idstring (uuid)required

ID задачи

Responses

200

Successful response

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
    }
  ]
}

Successful response

Список тегов

/api/v1/factory/tags

Возвращает все теги контент-фабрики с количеством задач.

Responses

200

Successful response

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
    }
  ]
}

Successful response

Создать тег

/api/v1/factory/tags

Создаёт новый тег для задач контент-фабрики.

Request body

namestringrequired

Название тега

colorstring

HEX цвет, напр. #6366f1

iconstring

Иконка тега (опционально)

Responses

200

Successful response

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
  }
}

Successful response

Обновить тег

/api/v1/factory/tags/{id}

Частичное обновление тега контент-фабрики.

Query parameters

idstring (uuid)required

ID тега

Request body

namestring

colorstring

iconstring

positioninteger

Позиция сортировки

Responses

200

Successful response

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
  }
}

Successful response

Удалить тег

/api/v1/factory/tags/{id}

Удаление тега. Системные теги удалить нельзя.

Query parameters

idstring (uuid)required

ID тега

Responses

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

Successfully deleted

Список публикаций

/api/v1/factory/publications

Возвращает список публикаций контент-фабрики с пагинацией.

Query parameters

companyIdstring (uuid)

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

offsetinteger= 0

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

limitinteger= 20

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

Responses

200

Successful response

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
  }
}

Successful response

Детекция инсайтов

/api/v1/factory/insights

Запуск детекторов (15 типов): content gaps, competitor wins, white space, reputation risks и др.

Request body

companyIdstringrequired

ID компании

insightTypestring

Тип инсайта (если не указан — запуск всех детекторов)

CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDING

limitinteger

Максимальное количество инсайтов

Responses

200

Successful response

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
    }
  }
}

Successful response

Настройки фабрики

/api/v1/factory/settings

Возвращает текущие настройки контент-фабрики пользователя.

Responses

200

Successful response

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": {}
}

Successful response

Обновить настройки

/api/v1/factory/settings

Обновление настроек контент-фабрики (deep merge).

Request body

settingsobjectrequired

Объект настроек для deep merge с текущими

Responses

200

Successful response

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": {}
}

Successful response

Карта бренда

/api/v1/factory/brand-card

Чтение карты бренда — дерева markdown-документов компании (знания о бренде, учитываются при генерации контента). Три режима: без доп. параметров — вся карта одним markdown (манифест → core-файлы → связанные ссылками → остальные; приватные блоки ```private вырезаны; лимит ~12 000 символов); mode=index — манифест + список файлов с path, id, isCore и исходящими ссылками (граф связей); path=... — один файл: content (ссылки [Имя](brandcard://id) сохранены дословно) + links с резолвом каждой ссылки в путь.

Query parameters

companyIdstring (uuid)required

ID компании

modestring

index — вернуть манифест и список файлов вместо полной карты

index

pathstring

Путь файла как в индексе (например "main / settings.md") — вернуть один файл. Регистр не важен

Responses

200

Successful response

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": {}
}

Successful response

Создать/обновить файл карты

/api/v1/factory/brand-card

Создаёт или полностью перезаписывает файл карты бренда по пути; недостающие папки создаются автоматически, без расширения добавляется .md. Чтобы сослаться на другой файл карты, вставьте в markdown ссылку [Имя](brandcard://<id из индекса>) — она живёт по id (переживает переименование и перенос) и поднимает приоритет целевого файла при генерации. Существующие brandcard://-ссылки при редактировании сохраняйте дословно. Личные заметки и опции оборачивайте в блок ```private — они не отправляются в нейросети.

Request body

companyIdstringrequired

ID компании

pathstringrequired

Путь файла, сегменты через "/", например "products / pricing.md"

contentstringrequired

Полный markdown файла (перезаписывает текущее содержимое)

Responses

200

Successful response

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
  }
}

Successful response

Удалить файл/папку карты

/api/v1/factory/brand-card

Удаляет файл или папку карты бренда по пути (папка — каскадно со всем содержимым). Служебный каркас (instruction.md, README.md, core-файлы) удалить нельзя — редактируйте его через POST. После удаления файла ссылки на него становятся висячими: в индексе пропадают из links, при чтении файла отдаются с path=null.

Query parameters

companyIdstring (uuid)required

ID компании

pathstringrequired

Путь файла или папки (как в индексе)

Responses

204

Successfully deleted

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"
  }
}

Successful response

Balance and spending

Баланс FoxCoin и история операций

Баланс FoxCoin и прейскурант

/api/v1/billing/balance

Остаток, оборот и цены операций. Кошелёк общий на аккаунт: участники команды тратят из пула владельца. Прейскурант отдаётся здесь, чтобы не зашивать цены в код интеграции.

Responses

200

Successful response

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
    }
  }
}

Successful response

История списаний и пополнений

/api/v1/billing/transactions

Журнал операций кошелька. У списаний за ответы поле query показывает, за какой именно запрос списано.

Query parameters

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

Сдвиг

Responses

200

Successful response

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
  }
}

Successful response

Reference data

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

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

/api/v1/sources

Какие ассистенты доступны для опроса и какие из них подставляются по умолчанию. Значение value — то, что принимает providers в POST /api/v1/queries/setup. Имена вне этого списка молча отбрасываются при постановке в очередь.

Query parameters

includeUnpollableboolean= false

Добавить claude (легаси-очередь, в контуре не опрашивается)

Responses

200

Successful response

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
    }
  ]
}

Successful response

Контекст ключа

/api/v1/context

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

Responses

200

Successful response

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"
      }
    ]
  }
}

Successful response

AI traffic

Переходы на сайт из ответов нейросетей (Яндекс.Метрика)

AI-трафик

/api/v1/analytics/metrika/ai-traffic

Переходы на сайт из ответов нейросетей: сколько визитов принесла каждая сеть и как это менялось. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

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

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

Responses

200

Successful response

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
}

Successful response

Посетители из нейросетей

/api/v1/analytics/metrika/visitors

Визиты с AI-источником и поведение на сайте: глубина просмотра, цели, повторные заходы. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

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

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

hasGoalsboolean

Только визиты с достигнутыми целями

includeSyntheticboolean

Включить синтетический трафик

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Responses

200

Successful response

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
}

Successful response

Воронка AI-трафика

/api/v1/analytics/metrika/traffic-funnel

Путь от перехода из ответа нейросети до целевого действия. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

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

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

hasGoalsboolean

Только визиты с достигнутыми целями

includeSyntheticboolean

Включить синтетический трафик

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Responses

200

Successful response

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
}

Successful response

Упоминания против трафика

/api/v1/analytics/metrika/correlation

Сопоставляет динамику упоминаний бренда с динамикой реальных переходов: даёт ли рост видимости рост трафика. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

companyIdstring (uuid)

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

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

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

Responses

200

Successful response

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
}

Successful response

Цели Метрики

/api/v1/analytics/metrika/goals

Справочник целей счётчика — что стоит за параметром hasGoals в остальных методах. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

includeInactiveboolean

Включить неактивные цели

Responses

200

Successful response

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
}

Successful response

Сводка по синтетическому трафику

/api/v1/analytics/metrika/synthetic/summary

Доля ботовых и неорганических визитов, чтобы они не искажали выводы по AI-трафику. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Счётчик Метрики. Без него — все подключённые счётчики аккаунта

timeRangestring

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

fromstring

Начало периода, ISO-дата

tostring

Конец периода, ISO-дата

filterstring

Фильтр классификации

hasGoalsboolean

Только визиты с достигнутыми целями

pvMininteger

Минимум просмотров страниц

pvMaxinteger

Максимум просмотров страниц

Responses

200

Successful response

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
}

Successful response

Список синтетических визитов

/api/v1/analytics/metrika/synthetic/list

Постраничная детализация к сводке: конкретные визиты с признаками синтетики. Скоуп по аккаунту: чужой integrationId игнорируется. Пустая выдача обычно означает, что Метрика не подключена — проверьте /api/v1/integrations/metrika/status.

Query parameters

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

Максимум просмотров страниц

Responses

200

Successful response

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
}

Successful response

Подключённые счётчики

/api/v1/integrations/metrika/list

С этого метода начинается работа с AI-трафиком: возвращает integrationId для остальных методов раздела.

Responses

200

Successful response

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
}

Successful response

Состояние интеграции

/api/v1/integrations/metrika/status

Подключена ли Метрика, когда была синхронизация и не истёк ли доступ. Пустая выдача методов раздела объясняется здесь.

Responses

200

Successful response

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
}

Successful response

Commerce

Товарные карточки в ответах нейросетей

Коммерс-аналитика

/api/v1/analytics/commerce

Товарные карточки, которые нейросети показывают вместе с текстом ответа. view=summary — доля ответов с карточками и динамика по сетям; sellers — топ продавцов и доменов; brands — карточки нашего бренда против конкурентов; cards — постраничный список.

Query parameters

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

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

Responses

200

Successful response

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
}

Successful response

Отслеживаемые товары

/api/v1/commerce/products

Номенклатура для сопоставления с карточками в ответах. Без неё раздел «Коммерс» показывает продавцов и домены, но не «наш товар против чужого».

Responses

200

Successful response

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
}

Successful response

Добавить товар

/api/v1/commerce/products

Responses

200

Successful response

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
}

Successful response

Monitoring

Регулярный опрос запросов по расписанию

Запросы на мониторинге

/api/v1/favorite-queries

Список запросов, поставленных на регулярный опрос.

Query parameters

searchstring

Поиск по тексту

activeboolean

Только включённые

Responses

200

Successful response

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
}

Successful response

Поставить запрос на мониторинг

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

Request body

textstringrequired

typestringrequired

companyIdstring

productIdstring

languagestring= ru

regionstring= RU

isActiveboolean= true

tagsstring[]

Responses

200

Successful response

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
}

Successful response

Запись мониторинга

/api/v1/favorite-queries/{id}

Query parameters

idstring (uuid)required

Responses

200

Successful response

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
}

Successful response

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

/api/v1/favorite-queries/{id}

Текст, компания, теги, isActive. Снять с опроса без удаления — isActive: false.

Query parameters

idstring (uuid)required

Responses

200

Successful response

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
}

Successful response

Снять с мониторинга

/api/v1/favorite-queries/{id}

Удаляет запись вместе с расписанием: следующего опроса не будет. Уже полученные ответы и упоминания остаются — они принадлежат запросу, а не подписке.

Query parameters

idstring (uuid)required

Responses

204

Successfully deleted

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
}

Successful response

Расписание опроса

/api/v1/favorite-queries/{id}/assignments

Query parameters

idstring (uuid)required

Responses

200

Successful response

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
}

Successful response

Задать расписание

/api/v1/favorite-queries/{id}/assignments

Именно здесь запрос начинает опрашиваться регулярно: запись без расписания ничего не делает. Расписание одно на запись, повторный вызов его перезаписывает. Каждый опрос по расписанию платный: 10 FoxCoin за ответ КАЖДОЙ нейросети. Интервал 60 минут по трём сетям — это 720 ответов в сутки. При нехватке средств опросы уходят на паузу и сами не возобновятся (POST /api/v1/queries/queue/resume).

Query parameters

idstring (uuid)required

Request body

providersstring[]required

Список: GET /api/v1/sources

frequencyMinutesintegerrequired

Интервал между опросами

isEnabledboolean= true

Пауза без удаления расписания

timezonestring= Europe/Moscow

В нём считаются daysOfWeek и hoursWindow

daysOfWeekinteger[]

1..7, пусто = каждый день

hoursWindowobject

Окно часов, вне которого опрос не идёт

modelobject

Карта «нейросеть → модель»

Responses

200

Successful response

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
}

Successful response

Опросить сейчас

/api/v1/favorite-queries/{id}/run-now

Внеочередной опрос, не дожидаясь расписания и не сдвигая его. Платно на общих основаниях.

Query parameters

idstring (uuid)required

Responses

200

Successful response

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
}

Successful response

brandfound. API

What is new in version 1.2

For AI assistants

Authentication

Workspaces

Список доступных окружений

Responses

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

Request body

Responses

Companies

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

Query parameters

Responses

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

Request body

Responses

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

Query parameters

Responses

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

Query parameters

Request body

Responses

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

Query parameters

Responses

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

Responses

Products

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

Query parameters

Responses

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

Request body

Responses

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

Query parameters

Responses

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

Query parameters

Request body

Responses

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

Query parameters

Responses

Competitors

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

Query parameters

Responses

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

Request body

Responses

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

Query parameters

Responses

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

Query parameters

Request body

Responses

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

Query parameters

Responses

Keywords

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

Query parameters

Responses

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

Request body

Responses

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

Query parameters

Responses

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

Query parameters

Request body

Responses

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

Query parameters

Responses