v1.0.0

Command Palette

Search for a command to run...

v1.0.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
1
2
curl -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  https://app.brandfound.ai/api/v1/companies
Successful response
1
2
3
4
5
6
{
  "success": true,
  "data": {
    "...": "..."
  }
}
Error
1
2
3
4
5
6
7
{
  "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

For AI assistants

Copy the API instructions and pass them to an AI assistant (ChatGPT, Claude, Gemini, etc.) — it will be able to compose requests to the brandfound. API for you. The API key is not included in the copied text.

Next to each method and section there is a button — it copies the description of a specific method or the whole category.

The API key is not included — paste it separately or use the Playground.

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
Response example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/workspaces" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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
POST/api/v1/workspaces/switch
1
2
3
4
5
6
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"
}'
1
2
3
4
5
6
7
8
9
10
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "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
synonymsstring[]

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

Responses

200

Successful response

400application/json

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

VALIDATION_ERROR
401application/json

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

UNAUTHORIZED
403application/json

Превышен лимит компаний

PLAN_LIMIT_EXCEEDED
POST/api/v1/companies
1
2
3
4
5
6
7
8
9
10
11
12
13
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",
    "Самсунг"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "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}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{
  "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}

Частичное обновление компании. Передавайте только изменяемые поля.

Query parameters

idstring (uuid)required

ID компании

Request body

namestring
descriptionstring
urlstring
categoryIdstring
countrystring
synonymsstring[]
isAutoGenerationEnabledboolean

Responses

200

Successful response

400application/json

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

VALIDATION_ERROR
401application/json

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

UNAUTHORIZED
404application/json

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

NOT_FOUND
PUT/api/v1/companies/{id}
1
2
3
4
5
6
7
8
9
10
11
12
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",
    "Самсунг",
    "삼성"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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
DELETE/api/v1/companies/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/companies/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Successfully deleted

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/products" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "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
POST/api/v1/products
1
2
3
4
5
6
7
8
9
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "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
PUT/api/v1/products/{id}
1
2
3
4
5
6
7
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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
DELETE/api/v1/products/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/products/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// 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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "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
POST/api/v1/competitors
1
2
3
4
5
6
7
8
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "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
PUT/api/v1/competitors/{id}
1
2
3
4
5
6
7
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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
DELETE/api/v1/competitors/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/competitors/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// 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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/keywords" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "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
POST/api/v1/keywords
1
2
3
4
5
6
7
8
9
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"
  }
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "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}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "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
PUT/api/v1/keywords/{id}
1
2
3
4
5
6
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "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
DELETE/api/v1/keywords/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/keywords/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "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
POST/api/v1/keywords/{id}/restore
1
2
3
curl -X POST "https://app.brandfound.ai/api/v1/keywords/{id}/restore" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
{
  "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
POST/api/v1/keywords/attach
1
2
3
4
5
6
7
8
9
10
11
12
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"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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
POST/api/v1/keywords/detach
1
2
3
4
5
6
7
8
9
10
11
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"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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-ассистентам с количеством ответов. Поддерживает расширенную фильтрацию: по тональности, кластерам, регионам, избранному, области поиска и диапазонам метрик тональности.

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "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

Создает новый запрос для отправки в AI-ассистенты.

Request body

textstringrequired
companyIdstringrequired
productIdstring
typestring

Тип запроса (general, comparative, negative и т.д.)

languagestring= ru
regionstring= russia

Responses

200

Successful response

400application/json

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

VALIDATION_ERROR
401application/json

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

UNAUTHORIZED
404application/json

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

NOT_FOUND
POST/api/v1/queries
1
2
3
4
5
6
7
8
9
10
11
curl -X POST "https://app.brandfound.ai/api/v1/queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Какой лучший смартфон 2026 года?",
  "companyId": "clx1abc2d0001abcdef123456",
  "productId": "prod-001",
  "type": "comparative",
  "language": "ru",
  "region": "russia"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "success": true,
  "data": {
    "id": "query-001",
    "text": "Какой лучший смартфон 2026 года?",
    "type": "comparative",
    "origin": "manual",
    "language": "ru",
    "region": "russia",
    "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "productId": "prod-001",
    "createdAt": "2026-04-07T12:00:00.000Z",
    "updatedAt": "2026-04-07T12:00:00.000Z"
  }
}

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}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "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
DELETE/api/v1/queries/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/queries/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// No Content

Successfully deleted

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/mentions" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/competitors" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "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-ассистентов с упоминаниями для детального анализа. Поддерживает фильтрацию по кластерам, демо-данные, кастомный период и режим фильтрации лейблов.

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/competitors/preview" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/tonality" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "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 и кастомный период.

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/links" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "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 и демо-данные.

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
1
2
3
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"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/analytics/brand-visibility" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "success": true,
  "data": {
    "timeline": [
      {
        "period": "2026-04-01",
        "periodLabel": "1 апр",
        "our": 15,
        "competitors": {
          "Apple": 18,
          "Google": 12
        }
      }
    ],
    "summary": {
      "trend": "growing"
    }
  }
}

Successful response

Advertising

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

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

/api/v1/advertising

Аналитика рекламных и промо-блоков в ответах AI-ассистентов. Поддерживает пагинацию, поиск по домену/URL, фильтрацию по кластерам, типу промо, периоду и сортировку.

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/advertising" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "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

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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "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
POST/api/v1/factory/tasks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "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}
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "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
PATCH/api/v1/factory/tasks/{id}
1
2
3
4
5
6
7
8
9
10
11
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"
  ]
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "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
DELETE/api/v1/factory/tasks/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// 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
POST/api/v1/factory/tasks/{id}/enrich
1
2
3
4
5
6
7
8
9
10
11
12
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",
    "характеристики"
  ]
}'
1
2
3
4
{
  "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
POST/api/v1/factory/tasks/{id}/plan
1
2
3
4
5
6
7
8
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: полное сравнение"
}'
1
2
3
4
5
6
7
8
9
10
{
  "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
POST/api/v1/factory/tasks/{id}/article
1
2
3
4
5
6
7
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"
}'
1
2
3
4
5
6
7
{
  "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
1
2
3
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"
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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
1
2
3
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"
1
2
3
4
{
  "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
POST/api/v1/factory/tasks/{id}/topics
1
2
3
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"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/tags" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "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
POST/api/v1/factory/tags
1
2
3
4
5
6
7
8
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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
PATCH/api/v1/factory/tags/{id}
1
2
3
4
5
6
7
8
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
}'
1
2
3
4
5
6
7
8
9
10
11
12
{
  "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
DELETE/api/v1/factory/tags/{id}
1
2
3
curl -X DELETE "https://app.brandfound.ai/api/v1/factory/tags/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
// 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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/publications" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "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
POST/api/v1/factory/insights
1
2
3
4
5
6
7
8
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
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "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
1
2
3
curl -X GET "https://app.brandfound.ai/api/v1/factory/settings" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"
1
2
3
4
{
  "success": true,
  "data": {}
}

Successful response

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

/api/v1/factory/settings

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

Request body

settingsobjectrequired

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

Responses

200

Successful response

401application/json

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

UNAUTHORIZED
PATCH/api/v1/factory/settings
1
2
3
4
5
6
7
8
9
10
11
12
13
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"
    ]
  }
}'
1
2
3
4
{
  "success": true,
  "data": {}
}

Successful response