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). One OAuth token can access every workspace available to the user: their own plus ACCEPTED TeamMember memberships. The active workspace is stored in ApiKey.activeAccountId. Switching persists and affects all MCP clients using this key on their next request. Access is checked on every request. If membership is lost, middleware silently falls back to the accountId issued at OAuth without returning 401. Switching also resets preferredCompanyId because it belongs to the previous workspace.

List accessible workspaces

/api/v1/workspaces

Returns every workspace (accountId) accessible to the current user: their own plus ACCEPTED TeamMember memberships. isCurrent: true marks the workspace currently used by the API key, including the activeAccountId override.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Switch the API key’s active workspace

/api/v1/workspaces/switch

Updates ApiKey.activeAccountId. The change persists and applies to ALL subsequent requests using this key, including other MCP clients. accountId=null clears the override and restores the token’s accountId. Also resets preferredCompanyId to null because it belongs to the previous workspace. API key authentication only.

Request body

accountIdstringrequired

Workspace UUID to switch to. null clears the active override and restores the accountId issued at OAuth.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

403application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Manage companies

List companies

/api/v1/companies

Returns the user’s companies with products, competitors, and keywords.

Query parameters

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

sortBystring= createdAt

createdAtupdatedAtnamelastUsedAt

sortOrderstring= desc

Sort order

ascdesc

searchstring

Search query (case-insensitive)

categoryIdstring (uuid)

Filter by category

countrystring

Filter by country

createdAtFromstring (date-time)

Creation date range start (ISO 8601)

createdAtTostring (date-time)

Creation date range end (ISO 8601)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create company

/api/v1/companies

Creates a company. The limit depends on the subscription plan.

Request body

namestringrequired

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2 (‘AE’). Legacy names (‘russia’) are accepted and normalized. Prefer regionTargets; this field is legacy.

synonymsstring[]

Synonyms/alternative names (maximum 20)

regionTargetsobject[]

Measurement countries and cities. COMPLETE state: old targets are recreated. The primary target sets the country and language for query generation.

defaultLanguageIdstring

Generated query language (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Language in which the AI model should respond.

defaultLocalestring

BCP-47, e.g. ‘ar-AE’.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get company

/api/v1/companies/{id}

Returns full company details, including products, competitors, and keywords.

Query parameters

idstring (uuid)required

Company ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Update company

/api/v1/companies/{id}

Partially updates a company. Send only the fields to change. Regional targeting: regionTargets define measurement countries and cities. The primary target determines the country and language for query generation (POST /api/v1/queries/autogenerate). Get countryId / cityId from GET /api/v1/geo/countries and /api/v1/geo/cities, and defaultLanguageId from /api/v1/geo/languages. regionTargets in the body represents the COMPLETE state: existing targets are recreated. isAutoGenerationEnabled is deprecated: enabling it (true) is IGNORED. This flag belonged to the removed scheduler that generated queries and immediately queued paid polling.

Query parameters

idstring (uuid)required

Company ID

Request body

namestring

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2 (‘AE’). Legacy names (‘russia’) are accepted and normalized. Prefer regionTargets; this field is legacy.

synonymsstring[]

isAutoGenerationEnabledboolean

DEPRECATED and IGNORED when true. This flag belonged to the removed scheduler that combined query generation and paid polling. To generate without polling, use POST /api/v1/queries/autogenerate.

regionTargetsobject[]

Measurement countries and cities. COMPLETE state: old targets are recreated. The primary target sets the country and language for query generation.

defaultLanguageIdstring

Generated query language (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Language in which the AI model should respond.

defaultLocalestring

BCP-47, e.g. ‘ar-AE’.

autogenQueryTypesstring[]

Query types for generation. Defaults to commercial, informational, comparative, reputational. Removing comparative excludes comparative queries (‘X vs Y’) from generated suggestions.

autogenQueriesPerRuninteger

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Archive company

/api/v1/companies/{id}

Archives a company. Data is retained, but the company is hidden from lists.

Query parameters

idstring (uuid)required

Company ID

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List industries

/api/v1/companies/categories

Valid categoryId values for company creation and updates.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Manage products

List products

/api/v1/products

Returns products with their associated companies, keywords, and competitors.

Query parameters

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

Sort order

ascdesc

companyIdstring (uuid)

Filter by company

searchstring

Search query (case-insensitive)

createdAtFromstring (date-time)

Creation date range start (ISO 8601)

createdAtTostring (date-time)

Creation date range end (ISO 8601)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create product

/api/v1/products

Creates a product associated with a company.

Request body

namestringrequired

companyIdstringrequired

descriptionstring

urlstring

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get product

/api/v1/products/{id}

Returns full product details, including keywords and competitors.

Query parameters

idstring (uuid)required

Product ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Update product

/api/v1/products/{id}

Partially updates a product.

Query parameters

idstring (uuid)required

Product ID

Request body

namestring

descriptionstring

urlstring

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Archive product

/api/v1/products/{id}

Archives a product. Data is retained, but the product is hidden from lists.

Query parameters

idstring (uuid)required

Product ID

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Manage competitors

List competitors

/api/v1/competitors

Returns competitors with their associated companies, products, and keywords.

Query parameters

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

Sort order

ascdesc

companyIdstring (uuid)

Filter by company

productIdstring (uuid)

Filter by product

searchstring

Search query (case-insensitive)

createdAtFromstring (date-time)

Creation date range start (ISO 8601)

createdAtTostring (date-time)

Creation date range end (ISO 8601)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create competitor

/api/v1/competitors

Creates a competitor associated with a company or a specific product.

Request body

namestringrequired

companyIdstringrequired

productIdstring

urlstring

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get competitor

/api/v1/competitors/{id}

Returns full competitor details with keywords.

Query parameters

idstring (uuid)required

Competitor ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Update competitor

/api/v1/competitors/{id}

Updates a competitor’s name and/or URL.

Query parameters

idstring (uuid)required

Competitor ID

Request body

namestring

urlstring

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Archive competitor

/api/v1/competitors/{id}

Archives a competitor. Data is retained, but the competitor is hidden from lists.

Query parameters

idstring (uuid)required

Competitor ID

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Intents (keywords): create, rename, archive/delete, restore, and bulk attach/detach to companies, products, or competitors

List intents

/api/v1/keywords

Returns intents (keywords) in the current workspace. Filter by one target: companyId | productId | competitorId. state controls archive filtering: active (default), archived, or all.

Query parameters

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

sortBystring= createdAt

createdAtname

sortOrderstring= desc

Sort order

ascdesc

statestring= active

Lifecycle filter: active (not archived, default), archived (archived only), or all.

activearchivedall

searchstring

Case-insensitive substring search on name.

companyIdstring (uuid)

Only intents actively associated with this company.

productIdstring (uuid)

Only intents actively associated with this product.

competitorIdstring (uuid)

Only intents actively associated with this competitor.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create or reuse an intent

/api/v1/keywords

Find-or-create by (name, userId). Existing intents are reused and restored if archived. Optional attach: { companyId | productId | competitorId }, exactly one, associates the intent with a target in the same transaction.

Request body

namestringrequired

attachobject

Target for attach/detach. Must contain EXACTLY ONE of the fields.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get an intent

/api/v1/keywords/{id}

Returns an intent with active associations to companies, products, and competitors.

Query parameters

idstring (uuid)required

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Rename an intent

/api/v1/keywords/{id}

Only name can be edited. Archived intents cannot be renamed; restore them first.

Query parameters

idstring (uuid)required

Request body

namestringrequired

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Archive or delete an intent

/api/v1/keywords/{id}

By default, archives (soft-deletes) the intent and all its associations; reversible through POST /restore. ?permanent=true deletes the intent from the database and requires it to be archived or have archived associations. ?dryRun=true returns an impact report without performing the operation.

Query parameters

idstring (uuid)required

permanentboolean= false

If true, permanently deletes from the database. Requires an archived state.

dryRunboolean= false

If true, returns a report without side effects.

Responses

204

Successfully deleted

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Restore an archived intent

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

Clears archivedAt on the keyword and its archived associations whose parent entities (company / product / competitor) still exist. Associations to deleted targets remain archived.

Query parameters

idstring (uuid)required

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Attach intents in bulk

/api/v1/keywords/attach

For each name, finds or creates by (name, userId), then ensures an active association with the target. Restores archived associations. Target requires EXACTLY ONE of companyId / productId / competitorId.

Request body

targetobjectrequired

Target for attach/detach. Must contain EXACTLY ONE of the fields.

namesstring[]required

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Detach intents in bulk

/api/v1/keywords/detach

Archives active keyword↔target associations. The intent itself remains and can be associated with other targets. Target requires EXACTLY ONE of companyId / productId / competitorId.

Request body

targetobjectrequired

Target for attach/detach. Must contain EXACTLY ONE of the fields.

keywordIdsstring[]required

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Manage queries to AI assistants

List queries

/api/v1/queries

Returns queries to AI assistants with response counts. Supports advanced filters for sentiment, clusters, regions, favorites, search scope, and sentiment metric ranges. Read polling status from queue.status and answersCount. providers contains the AI models actually queried. For individual run details, use GET /api/v1/queries/queue.

Query parameters

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

sortBystring= createdAt

createdAttextupdatedAt

sortOrderstring= desc

Sort order

ascdesc

companyIdstring (uuid)

Filter by company

productIdstring (uuid)

Filter by product

typestring

Query type (general, comparative, negative, etc.). Supports arrays: ?type=comparative&type=neutral

originstring

Query origin. Supports arrays: ?origin=manual&origin=auto

manualauto

hasAnswersstring

Whether responses exist

truefalse

languagestring

Query language (ru, en, etc.). Supports arrays: ?language=ru&language=en

searchTextstring

Search query text

providerstring

Filter by the response’s AI provider

sourceIdstring

Filter by response source ID. Supports arrays: ?sourceId=id1&sourceId=id2

labelSlugstring

Filter by cluster/label slug

regionstring

Query region. Supports arrays: ?region=RU&region=US

isFavoritestring

Favorite queries only

truefalse

sentimentstring

Filter by mention sentiment in responses

positiveneutralnegative

searchFieldstring= query

searchText scope: query text, responses, or sources

queryanswersources

labelFilterModestring= or

Cluster filter logic: any (or) or all (and)

orand

labelstring

Cluster slug. Supports arrays: ?label=slug1&label=slug2

createdAtFromstring (date-time)

Creation date range start (ISO 8601)

createdAtTostring (date-time)

Creation date range end (ISO 8601)

showArchivedstring

Include archived queries (default: false)

truefalse

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create query

/api/v1/queries

Creates a query and, by default, immediately queues polling. Paid: each answer received from each AI model costs FoxCoin (prices in GET /api/v1/billing/balance). Polling five models costs five answers. Send dispatch: false to create a query without spending FoxCoin. Choose models using providers (slugs from GET /api/v1/sources). If omitted, account defaults are used; an unconfigured account uses only ChatGPT. For bulk creation with clusters, use POST /api/v1/queries/setup. Set geography through region (ISO 3166-1 alpha-2) and language; if region is omitted, the company country is used. geoOverride and resolvedGeoSnapshot are READ-ONLY snapshots computed by the server for clustered queries with geographic targets. They are not accepted in POST bodies (strict validation: unknown field → 400). Check the response’s dispatch field: dispatched=false with a nonempty error means the query was created but polling did not start.

Request body

textstringrequired

companyIdstringrequired

productIdstring

typestring= neutral

Legacy values negative and general are accepted: negative → reputational, general → neutral.

neutralcommercialinformationalcomparativereputationalbranded

languagestring= ru

ISO 639-1 response language code (ru, en, ar, hi, vi, ms, ...). Sets the required AI response language by adding an explicit instruction using its directory name. Defaults to ru.

regionstring

Query country, ISO 3166-1 alpha-2 (AE, SA, RU). Defaults to the company’s primary regionTarget, then RU. Legacy names (‘russia’) are accepted and normalized. Does not geographically target answers; used for filtering and analytics.

providersstring[]

AI models to poll. If omitted, uses account defaults; an unconfigured account uses only ChatGPT.

dispatchboolean= true

false: create a query WITHOUT queueing paid polling.

labelsstring[]

Cluster names: created or reused by slug.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

402application/json

Insufficient FoxCoin

HTTP_402

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get query

/api/v1/queries/{id}

Returns a query with AI responses and detected mentions.

Query parameters

idstring (uuid)required

Query ID

includeAnswersstring= true

Include responses with mentions (default: true)

truefalse

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Archive query

/api/v1/queries/{id}

Archives a query. Data is retained and can be restored.

Query parameters

idstring (uuid)required

Query ID

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Update a query

/api/v1/queries/{id}

Changes a query’s text, type, language, region, product, favorite status, and clusters. Changing the text does NOT poll AI models again: existing responses remain attached. To poll again, create a new query. Strict body validation: unknown field → 400.

Query parameters

idstring (uuid)required

Request body

textstring

typestring

neutralcommercialinformationalcomparativereputationalbranded

languagestring

regionstring

ISO 3166-1 alpha-2.

productIdstring

null: detach from the product.

isFavoriteboolean

labelsstring[]

COMPLETE cluster list: associations are rebuilt.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List queued runs

/api/v1/queries/queue

Query polling state: one run for each query–AI model pair. Distinguishes still polling, failed, and paused for insufficient funds, which cannot be determined from response counts alone.

Query parameters

statusstring= queued,onHold,failed

Comma-separated status groups. All three by default.

companyIdstring (uuid)

Limit to one company. If omitted, includes all account companies.

queryIdstring (uuid)

Runs for one query

providerstring

Filter by AI model

chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_mode

includeArchivedboolean= false

Include runs for archived queries

limitinteger= 50

Page size

offsetinteger= 0

Offset

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Queue summary and estimated cost

/api/v1/queries/queue/summary

Run counts, current queue cost, and FoxCoin balance in one request. Polling continues while queuedTotal > 0. onHold > 0 means insufficient funds: these runs do not resume automatically after a top-up.

Query parameters

companyIdstring (uuid)

Limit to one company

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Create queries in bulk with selected AI models

/api/v1/queries/setup

Creates clusters and queries in one transaction and immediately queues polling. Use providers to select AI models explicitly; if omitted, account defaults are used. To create one query, use POST /api/v1/queries, which also accepts providers. Paid: each answer received from each model costs FoxCoin (see GET /api/v1/billing/balance). Maximum 500 queries per call.

Request body

companyIdstring

If omitted, uses the key’s preferredCompanyId (see GET /api/v1/context)

clusterIdstring

Existing cluster for geographic inheritance; applies to all clusters entries without their own clusterId

providersstring[]

AI models to poll (slugs from GET /api/v1/sources). If omitted, account defaults are used; an unconfigured account uses ChatGPT. Selecting models through providers is also supported by POST /api/v1/queries.

clustersobject[]required

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

402application/json

Insufficient FoxCoin

HTTP_402

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Resume queued runs

/api/v1/queries/queue/resume

Resumes paused runs. **Why.** When FoxCoin is insufficient, a run enters ON_HOLD_NO_FUNDS. Workers do not pick up these runs, and topping up does NOT resume them. They remain paused until the scheduler moves them to CANCELLED after 45 days. Resuming is always explicit through this method. **How it happens.** Create queries with insufficient balance. Funds are checked both at queueing and execution, so some runs may be paused even if a query partially completed. Check `GET /api/v1/queries/queue/summary` → `onHold`, or the query’s `queue.status` = `on_hold_no_funds`. **402 is not a permanent rejection:** the balance does not cover the entire batch. Top up or retry with `force: true`: affordable runs will execute and the rest will pause again.

Request body

runIdsstring[]

Select individual run IDs

scopestring

All paused runs

onHold

companyIdstring

Limit scope to one company

forceboolean= false

Resume even if the balance cannot cover the entire batch

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

402application/json

Insufficient FoxCoin for the entire batch

HTTP_402

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Cancel queued runs

/api/v1/queries/queue/cancel

Cancels runs that have not started: waiting (PENDING, RETRYING) and paused runs. RUNNING runs are never changed: a worker already owns them, and cancellation would introduce a race. **When to use.** Stop unwanted bulk polling before FoxCoin is charged. Charges occur when responses arrive, so canceled runs cost nothing. Also useful for clearing paused runs you do not intend to fund. Cancellation is reversible: requeue a canceled run through `POST /api/v1/queries/queue/resume` with its `runId`.

Request body

runIdsstring[]

queryIdsstring[]

All cancellable runs for these queries

scopestring

onHold: paused runs only; queued: active queue only

onHoldqueued

companyIdstring

Limit scope to one company

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Generate query suggestions as drafts and approve them. Generation (1 FoxCoin per query) and paid AI polling (10 FoxCoin per answer) are separate steps.

Generate query suggestions without polling AI models

/api/v1/queries/autogenerate

The service generates queries and saves them as DRAFTS. AI models are NOT polled. Replaces isAutoGenerationEnabled, which inseparably combined generation and paid polling. These steps are now separate: polling starts only through POST /api/v1/query-drafts/approve. Cost: 1 FoxCoin for EACH generated query, charged for delivered drafts. Polling is charged separately: 10 FoxCoin per answer (query × model). Language and country: without language/region, uses company regional settings (regionTargets, PUT /api/v1/companies/{id}), then ru/RU. For multiple countries, send targets: one task per country, with the official language as default (AE → ar, IN → hi). Types: without types, uses Company.autogenQueryTypes, defaulting to commercial, informational, comparative, reputational. Comparative queries (‘X vs Y’) are generated only when comparative is selected AND the company has competitors. Returns 202 immediately by default and generates in the background. Read progress through GET at the same URL using clientToken. The short form (region/language/city/includeDistricts) and targets are mutually exclusive. Combining them returns 400 because a separate country’s city cannot be specified outside targets.

Request body

companyIdstring

If omitted, uses the key’s preferredCompanyId.

productIdstring

countintegerrequired

Queries to generate PER target. 1 FoxCoin per query.

typesstring[]

Generated query types; count is divided equally between them. If omitted, uses Company.autogenQueryTypes, which includes comparative by default.

clustersstring[]

Topics used to group queries.

userWishesstring

namestring

Task name, visible in the UI and GET response.

languagestring

ISO 639-1. Defaults to company language. Only WITHOUT targets.

regionstring

ISO 3166-1 alpha-2. Defaults to the company’s primary country (regionTargets), then RU. Legacy names (‘russia’) accepted. Only WITHOUT targets.

citystring

Only WITHOUT targets.

includeDistrictsboolean

Only WITHOUT targets.

targetsobject[]

Multiple-country measurement: one task per country. Cost is the sum of all target counts. MUTUALLY EXCLUSIVE with the short form: region / language / city / includeDistricts alongside targets → 400. Inside targets, each country has its own city and language.

waitboolean= false

true: wait for generation to finish. For small batches only; 100+ queries take minutes.

clientTokenstring

Custom task token used to retrieve progress later.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

402application/json

Insufficient FoxCoin: required and balance in the error body

HTTP_402

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

RATE_LIMIT_EXCEEDED

503application/json

Query generation is not configured on the server

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

Query generation task status

/api/v1/queries/autogenerate

Progress of tasks started through POST /api/v1/queries/autogenerate. Poll until status = OK, then read drafts using GET /api/v1/query-drafts. Drafts from a RUNNING task cannot be approved intentionally, to avoid approving an incomplete batch.

Query parameters

runIdstring (uuid)

Specific task.

clientTokenstring

Task identified by the client token returned by POST.

limitinteger= 20

Number of recent tasks to return.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Stop a query generation task

/api/v1/queries/autogenerate/cancel

Cancellation stops unstarted batches; you pay only for drafts already delivered. The run becomes CANCELLED. Generated drafts remain available for approval.

Request body

runIdstringrequired

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List query drafts

/api/v1/query-drafts

Storing a draft is free and does not trigger polling. It becomes a query only through POST /api/v1/query-drafts/approve.

Query parameters

statusstring

PENDING: awaiting a decision. All statuses by default.

PENDINGAPPROVEDREJECTEDEXPIRED

companyIdstring (uuid)

Filter by company.

typestring

Filter by query type.

neutralcommercialinformationalcomparativereputationalbranded

pageinteger= 1

Page number, starting at 1.

limitinteger= 50

Page size.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Approve drafts and run queries

/api/v1/query-drafts/approve

PAID STEP: approved drafts become queries and are sent to the selected AI models at 10 FoxCoin per answer (query × model). 50 drafts × 3 models = 150 answers = 1,500 FoxCoin. First call with dryRun: true and show the estimate to the user. Idempotent: repeated calls with the same draftIds neither duplicate queries nor poll them again. Drafts from a still-running generation task are skipped (skippedRunning); wait for status = OK.

Request body

draftIdsstring[]required

providersstring[]required

AI models to poll. Each multiplies the cost.

dryRunboolean

true: estimate only; nothing is created or charged.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

402application/json

Insufficient FoxCoin: required and balance in the error body

HTTP_402

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Reject drafts

/api/v1/query-drafts/reject

Soft rejection: drafts remain in the database as REJECTED for billing audits. No polling occurs. Generation FoxCoin is not refunded because the queries have already been generated.

Request body

draftIdsstring[]required

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

AI responses in bulk: links, mentions, and sentiment.

Retrieve AI responses in bulk

/api/v1/answers

Replaces a GET /api/v1/queries/{id} loop: returns up to 200 answers per page with links, mentions, and sentiment. links contains parsed citations from ANY AI model. Do not confuse it with raw answer.sources: that is scraper payload, populated only for Search with Alice, and is not a citation list. brandDomainCited indicates whether the company’s website domain was cited. Mention fields: position is the CHARACTER OFFSET in the response. The array is sorted by it, so the order in which a brand is named is the mention’s RANK in the array, not its position value. sentiment (1 / 0 / -1) and sentimentScore (-1..1) come from the ENTIRE response, so all mentions within one response share them. sentimentScore = null if sentiment has not been calculated. isOurs = false identifies a competitor. Repeat array parameters: ?companyId=a&companyId=b.

Query parameters

companyIdstring[]

Companies (multiple allowed).

productIdstring[]

Products (multiple allowed).

queryIdstring[]

Only answers to these queries.

sourceIdstring[]

AI model IDs (GET /api/v1/sources).

providerstring[]

AI model slugs.

typestring[]

Type of the query that produced the answer.

labelstring[]

Cluster slugs.

regionstring[]

Query region, ISO 3166-1 alpha-2. Legacy names are also matched.

languagestring[]

Query language.

createdAtFromstring (date-time)

ANSWER creation date, from (ISO 8601).

createdAtTostring (date-time)

ANSWER creation date, to (ISO 8601).

hasLinksboolean

true: only answers with links; false: only answers without links.

mentionsOursboolean

true: only answers mentioning the company’s brand.

showArchivedboolean= false

true: include answers to archived queries.

includestring= content,tonality

Comma-separated expansions: content, links, mentions, tonality.

limitinteger= 50

Page size.

offsetinteger= 0

Offset.

sortBystring= createdAt

Sort field.

createdAtdate

sortOrderstring= desc

Sort direction.

ascdesc

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Country, region, city, and language directories.

List countries

/api/v1/geo/countries

Directory IDs are used for company and cluster regionTargets and defaultLanguageId; iso2 is used for the query and generation region field.

Query parameters

qstring

Search by name.

continentstring

Filter by continent.

EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICA

limitinteger= 250

Maximum records.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List a country’s regions

/api/v1/geo/regions

Regions (states, provinces) of a specific country. Requires countryId or countryIso2.

Query parameters

countryIso2string

Two-letter country code.

countryIdstring (uuid)

Country UUID.

qstring

Search by name.

limitinteger= 100

Maximum records.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List a country’s cities

/api/v1/geo/cities

Cities of a specific country. Requires countryId or countryIso2. Use cityId in company regionTargets and cluster targets.

Query parameters

countryIso2string

Two-letter country code.

countryIdstring (uuid)

Country UUID.

regionIdstring (uuid)

Region UUID.

qstring

Search by name.

limitinteger= 50

Maximum records.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List languages

/api/v1/geo/languages

Directory IDs are used for company and cluster regionTargets and defaultLanguageId; iso2 is used for the query and generation region field.

Query parameters

qstring

Search by name or code.

limitinteger= 200

Maximum records.

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Query labels/clusters: list with an optional company filter; create with regional targeting

List query clusters

/api/v1/query-labels

Returns query labels/clusters in the current workspace with query counts. companyId limits results to clusters containing this company’s queries and calculates queryCount for that company. lite=true returns { items: [{ id, name, slug, queryCount }] } without statistics or sampleQueries.

Query parameters

companyIdstring (uuid)

Company filter: only clusters containing this company’s queries; queryCount counts its queries only.

litestring

lite=true returns a lightweight { items: [{ id, name, slug, queryCount }] } response without statistics.

truefalse

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

qstring

Case-insensitive substring search on the label name.

sortstring= queryCount:desc

Sort in field:direction format.

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

hasQueriesstring

with: clusters with queries only; without: empty clusters.

withwithout

minCountinteger

Minimum queries per cluster.

maxCountinteger

Maximum queries per cluster.

createdFromstring (date-time)

Labels created on or after this date.

createdTostring (date-time)

Labels created on or before this date.

lastUsedFromstring (date-time)

Labels with lastUsedAt on or after this date.

lastUsedTostring (date-time)

Labels with lastUsedAt on or before this date.

includestring

include=targets also loads cluster geographic targets (country/city).

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create or update a regional query cluster

/api/v1/query-labels

Find-or-create by (slug, userId). If the slug exists, updates the cluster name and geographic settings, recreating its targets. Optional companyId/productId are accepted but are not currently persisted on 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

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

409application/json

Conflict: resource already exists

CONFLICT

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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": "Input validation error"
  }
}

Input validation error

Mentions

View brand mentions

List mentions

/api/v1/mentions

Returns brand mentions in AI answers with full context.

Query parameters

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

sortBystring= createdAt

createdAtpositionsentiment

sortOrderstring= desc

Sort order

ascdesc

timeRangestring

Time range

24h7d30d90dall

createdAtFromstring (date-time)

Creation date range start (ISO 8601)

createdAtTostring (date-time)

Creation date range end (ISO 8601)

companyIdstring (uuid)

Filter by company

productIdstring (uuid)

Filter by product

competitorIdstring (uuid)

Filter by competitor

answerIdstring (uuid)

Filter by a specific response

typestring

Mention type

companyproductkeywordcompetitor

sentimentstring

Sentiment

positiveneutralnegative

searchstring

Search query (case-insensitive)

isOursstring

Only our mentions (true) or competitor mentions (false)

truefalse

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Analytics: competitors, sentiment, links, and brand visibility

Competitor analytics

/api/v1/analytics/competitors

Comprehensive comparison of your company and competitors by mentions in AI assistants. Supports cluster slug, AI provider, and period filters.

Query parameters

timeRangestring= 30d

Time range

24h7d30dall

fromstring (date-time)

Custom range start (ISO 8601)

tostring (date-time)

Custom range end (ISO 8601)

companyIdstring (uuid)

Company ID

productIdstring (uuid)

Product ID

sourceIdstring[]

AI provider IDs

labelIdstring[]

Cluster/label IDs

labelSlugstring

Cluster slug. Array: ?labelSlug=slug1&labelSlug=slug2

labelFilterModestring= or

Label filter mode

orand

includeDemostring

Include demo data

truefalse

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Mentions preview

/api/v1/analytics/competitors/preview

Returns individual AI answers with mentions for detailed analysis. Supports clusters, demo data, custom periods, and label filter modes. companyId is required to avoid combining all account companies. If omitted, the key’s preferredCompanyId is used (see GET /api/v1/context).

Query parameters

sidestringrequired

Whose side: our company or a competitor

ourcompetitor

competitorNamestring

Competitor name (if side=competitor)

mentionTypestring= both

Mention type

brandlinkboth

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

sourceIdstring[]

labelIdstring[]

includeMentionsstring

Include mentions in the response

truefalse

includeDemostring

Include demo data

truefalse

labelFilterModestring= or

Cluster filter logic

orand

fromstring (date-time)

Period start (ISO 8601)

tostring (date-time)

Period end (ISO 8601)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Tonality analytics

/api/v1/analytics/tonality

Complete sentiment analysis of AI answers: quality metrics, timeline, problematic and best answers.

Query parameters

timeRangestring= 30d

24h7d30d90d

companyIdstring (uuid)

productIdstring (uuid)

queryTypestring

Query type

neutralcomparativenegative

sentimentstring

Filter by sentiment

positiveneutralnegative

sourceIdstring[]

AI providers

labelSlugstring[]

Cluster/label slugs

labelFilterModestring= or

orand

fromstring (date-time)

tostring (date-time)

includeDemostring

truefalse

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Links analytics

/api/v1/analytics/links

Link analytics from AI answers: top domains, citations by provider, and timeline. Supports sentiment, cluster, query type, Impact/Overall Score threshold filters, and custom periods. companyId is required to avoid combining all account companies. If omitted, the key’s preferredCompanyId is used (see GET /api/v1/context).

Query parameters

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

labelSlugstring[]

sortDomainsBystring

Domain sorting

sentimentstring

Filter by sentiment

positiveneutralnegative

minImpactnumber

Minimum Impact Score

minOverallnumber

Minimum Overall Score

presetstring

Filter preset

queryTypestring

Query type

neutralnegativecomparative

labelstring

Cluster slug

labelFilterModestring= or

Filter logic

orand

fromstring (date-time)

Period start

tostring (date-time)

Period end

chartOnlystring

Chart data only

truefalse

citationModestring

Citation mode

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Top domains

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

Returns the most cited domains in AI answers. Supports sentiment, query type, Impact/Overall Score thresholds, and demo data. companyId is required to avoid combining all account companies. If omitted, the key’s preferredCompanyId is used (see GET /api/v1/context).

Query parameters

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

limitinteger= 10

Number of domains

includeDemostring

Include demo data

truefalse

sentimentstring

Filter by sentiment

positiveneutralnegative

minImpactnumber

Minimum Impact Score

minOverallnumber

Minimum Overall Score

queryTypestring

Query type

neutralnegativecomparative

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Brand visibility

/api/v1/analytics/brand-visibility

Brand visibility timeline compared with competitors, with configurable granularity. Supports clusters by ID and slug, AI providers, and filter logic.

Query parameters

granularitystring= day

Timeline granularity

dayweekmonth

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

fromstring (date-time)

tostring (date-time)

labelIdstring

Cluster ID. Array: ?labelId=id1&labelId=id2

labelSlugstring

Cluster slug

labelFilterModestring= or

Filter logic

orand

sourceIdstring

AI source ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Citation timeline

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

Daily share of answers citing us versus competitors. Based on daily rollups, so only overall citation mode is supported: rollups do not distinguish URL citations from domain citations.

Query parameters

companyIdstring (uuid)

Company. If omitted, the key’s preferredCompanyId is used

productIdstring

Product

timeRangestring

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

granularitystring

Trend breakdown

tzstring

Time zone

sourceIdstring[]

Sources

labelSlugstring[]

Clusters

labelFilterModestring

AND | OR

includeDemoboolean

Include demo data

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Companies and products for filters

/api/v1/analytics/companies-products

Account companies with their products for the company → product selector. companyId is NOT required: omitting it returns all companies, which is the purpose of this method.

Query parameters

companyIdstring (uuid)

Limit to one company

includeDemoboolean

Include demo data

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Domains and links from AI answers

Domains and links

/api/v1/links

Two-level table of domains and links from AI answers with sorting and filtering. companyId is required to avoid combining all account companies. If omitted, the key’s preferredCompanyId is used (see GET /api/v1/context).

Query parameters

pageinteger= 1

Page number

pageSizeinteger= 50

Page size

sortBystring= lastMentioned

lastMentionedmentionCountanswerCountourMentionCountcompetitorMentionCountdomaintrustRankdomainLinks

sortDirstring= desc

ascdesc

searchstring

Search query (case-insensitive)

searchFieldstring

Search field

domainurltitle

timeRangestring

24h7d30d

fromstring (date-time)

tostring (date-time)

companyIdstring (uuid)

productIdstring (uuid)

sentimentstring

positiveneutralnegative

queryTypestring

neutralnegativecomparative

providerstring[]

AI providers

activestring

Active links only

truefalse

domainsOnlystring

Domains only (no child links)

truefalse

domainstring

Child links for a specific domain

labelstring[]

Clusters/labels

includeDemostring

truefalse

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Filter options

/api/v1/links/filter-options

Returns available provider and label filters for the links table. companyId is required to avoid combining all account companies. If omitted, the key’s preferredCompanyId is used (see GET /api/v1/context).

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Advertising data from AI answers

Advertising data

/api/v1/advertising

Analytics for advertising and promotional blocks in AI answers. Supports pagination, domain/URL search, cluster, promotion type and period filters, and sorting. companyId is required to avoid combining all account companies. If omitted, the key’s preferredCompanyId is used (see GET /api/v1/context).

Query parameters

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

pageinteger= 1

Page number

pageSizeinteger= 50

Page size

searchstring

Search by domain or URL

searchFieldstring

Search field

domainurltitle

labelstring

Cluster slug. Array: ?label=slug1&label=slug2

promoTypestring

Promotion block type

sortBystring

Sort field

sortDirstring

Sort direction

ascdesc

fromstring (date-time)

Period start (ISO 8601)

tostring (date-time)

Period end (ISO 8601)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Preview advertising blocks

/api/v1/advertising/preview

Details for the /api/v1/advertising summary: which promotions appeared and in which answers.

Query parameters

domainstringrequired

Promotion domain. REQUIRED; otherwise 400

companyIdstring (uuid)

Company. If omitted, the key’s preferredCompanyId is used

productIdstring

Product

promoTypestring

ours | competitor | other

ourscompetitorother

timeRangestring

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

labelstring[]

Clusters

labelFilterModestring

AND | OR

limitinteger= 20

1..50

offsetinteger= 0

Offset

includeDemoboolean

Include demo data

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Content factory: tasks, tags, enrichment, outline and article generation, insight detection

List tasks

/api/v1/factory/tasks

Returns content factory tasks with filtering, pagination, and sorting.

Query parameters

companyIdstring (uuid)

Filter by company

statusstring[]

Filter by status (multiple values: ?status=TODO&status=IN_PROGRESS)

typestring[]

Filter by task type (multiple values allowed)

prioritystring[]

Filter by priority (multiple values allowed)

searchstring

Search task titles and descriptions

tagIdstring (uuid)

Filter by tag

aiGeneratedboolean

AI-generated tasks only

sortBystring= createdAt

createdAtupdatedAtprioritystatusposition

sortOrderstring= desc

Sort order

ascdesc

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create task

/api/v1/factory/tasks

Creates a content factory task.

Request body

titlestringrequired

Task title

companyIdstringrequired

Company ID

typestringrequired

Task type

NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDY

prioritystring= MEDIUM

Priority

CRITICALHIGHMEDIUMLOW

descriptionstring

Task description

targetKeywordsstring[]

Target keywords (maximum 20)

targetProvidersstring[]

Target AI providers

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get task

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

Returns full content factory task details.

Query parameters

idstring (uuid)required

Task ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Update task

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

Partially updates a content factory task.

Query parameters

idstring (uuid)required

Task ID

Request body

statusstring

IDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSED

prioritystring

CRITICALHIGHMEDIUMLOW

titlestring

descriptionstring

tagIdsstring[]

Array of tag IDs to attach

targetKeywordsstring[]

targetProvidersstring[]

dueDatestring

Task deadline

metadataobject

Custom task metadata

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Archive task

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

Archives a task. Data is retained and its status becomes DISMISSED.

Query parameters

idstring (uuid)required

Task ID

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Enrich task

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

RAG search across the source database, competitor analysis, and AI recommendations.

Query parameters

idstring (uuid)required

Task ID

Request body

topicstringrequired

Topic for enrichment

descriptionstring

Additional description

keywordsstring[]

Keywords for RAG search

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Generate plan

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

Generates an article outline from enriched data: structure, headings, key points, and tone of voice.

Query parameters

idstring (uuid)required

Task ID

Request body

promptstring

Additional instructions for outline generation

topicIdstring

Selected topic ID (from suggest topics)

topicTitlestring

Topic title

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Generate article

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

Generates an article from an outline using SSE streaming. Content-Type: text/event-stream.

Query parameters

idstring (uuid)required

Task ID

Request body

planIdstring

Outline ID for article generation

articleLengthstring= medium

Article length: short (~1,000 words), medium (~2,000), long (~3,500)

shortmediumlong

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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": "Unauthorized: missing or invalid token"
  }
}

Unauthorized: missing or invalid token

Content versions

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

Returns content versions (outlines, articles, briefs) for a task.

Query parameters

idstring (uuid)required

Task ID

typestring

Filter by content type

planarticlebrief

planIdstring

Filter by outline ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Task analytics

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

Returns task analytics: enrichment, generation, and publication statistics.

Query parameters

idstring (uuid)required

Task ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Suggest topics

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

Generates 10 topics from task data.

Query parameters

idstring (uuid)required

Task ID

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List tags

/api/v1/factory/tags

Returns all content factory tags with task counts.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Create tag

/api/v1/factory/tags

Creates a tag for content factory tasks.

Request body

namestringrequired

Tag name

colorstring

HEX color, e.g. #6366f1

iconstring

Tag icon (optional)

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

409application/json

Conflict: resource already exists

CONFLICT

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Update tag

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

Partially updates a content factory tag.

Query parameters

idstring (uuid)required

Tag ID

Request body

namestring

colorstring

iconstring

positioninteger

Sort position

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

409application/json

Conflict: resource already exists

CONFLICT

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Delete tag

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

Deletes a tag. System tags cannot be deleted.

Query parameters

idstring (uuid)required

Tag ID

Responses

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

403application/json

Access denied

FORBIDDEN

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List publications

/api/v1/factory/publications

Returns content factory publications with pagination.

Query parameters

companyIdstring (uuid)

Filter by company

offsetinteger= 0

Pagination offset

limitinteger= 20

Records per page

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Detect insights

/api/v1/factory/insights

Runs detectors (15 types): content gaps, competitor wins, white space, reputation risks, and more.

Request body

companyIdstringrequired

Company ID

insightTypestring

Insight type (if omitted, runs all detectors)

CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDING

limitinteger

Maximum insights

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Factory settings

/api/v1/factory/settings

Returns the user’s current content factory settings.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Update settings

/api/v1/factory/settings

Updates content factory settings using deep merge.

Request body

settingsobjectrequired

Settings object to deep-merge with current settings

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get the brand card

/api/v1/factory/brand-card

Reads the brand card: a tree of company Markdown documents used as knowledge for content generation. Three modes: without extra parameters, returns the entire card as Markdown (manifest → core files → linked files → remaining files; ```private blocks removed; approximately 12,000-character limit). mode=index returns the manifest and files with path, id, isCore, and outgoing links (the link graph). path=... returns one file: content with [Name](brandcard://id) links preserved verbatim, plus links resolving each reference to a path.

Query parameters

companyIdstring (uuid)required

Company ID

modestring

index: return the manifest and file list instead of the full card

index

pathstring

File path from the index (e.g. "main / settings.md"); returns one file. Case-insensitive

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Create or update a brand card file

/api/v1/factory/brand-card

Creates or fully overwrites a brand card file by path. Missing folders are created automatically; .md is added if no extension is supplied. To reference another card file, insert [Name](brandcard://<id from index>) in Markdown. References use IDs, survive moves and renames, and increase the target file’s generation priority. Preserve existing brandcard:// links verbatim when editing. Wrap personal notes and options in a ```private block so they are not sent to AI models.

Request body

companyIdstringrequired

Company ID

pathstringrequired

File path with segments separated by "/", e.g. "products / pricing.md"

contentstringrequired

Complete file Markdown (replaces current content)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Delete a brand card file or folder

/api/v1/factory/brand-card

Deletes a brand card file or folder by path; folders are deleted recursively. Protected files (instruction.md, README.md, core files) cannot be deleted; edit them through POST. After file deletion, references become dangling: removed from links in the index, returned with path=null when reading a file.

Query parameters

companyIdstring (uuid)required

Company ID

pathstringrequired

File or folder path (as shown in the index)

Responses

204

Successfully deleted

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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 balance and transaction history

FoxCoin balance and pricing

/api/v1/billing/balance

Balance, turnover, and operation prices. The wallet is shared by the account: team members spend the owner’s balance. Prices are returned here to avoid hardcoding them in integrations.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Transaction history

/api/v1/billing/transactions

Wallet transaction log. For response charges, query identifies the query being charged.

Query parameters

typestring

Filter by operation type

ANSWER_CHARGEQUERY_GENERATIONBRAND_CARD_GENERATIONTASK_ENRICHMENTARTICLE_GENERATIONCONTENT_PLANTOPIC_SUGGESTIONFACT_CHECKTOPUPBONUSREFUNDMANUAL_ADJUSTMENTSUBSCRIPTION_CREDITAPI_CALL_FREE

fromstring (date-time)

Window start, ISO date (inclusive)

tostring (date-time)

Window end, ISO date (inclusive)

limitinteger= 50

Page size

offsetinteger= 0

Offset

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

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

Reference data and key context

List AI models

/api/v1/sources

Available AI assistants and account defaults. value is accepted by providers in POST /api/v1/queries/setup. Names outside this list are silently discarded when queueing.

Query parameters

includeUnpollableboolean= false

Include claude (legacy queue; not polled in this pipeline)

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Get API key context

/api/v1/context

Start an integration here: the key’s owning account, permissions, accessible companies and products, and default company.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Website visits from AI answers (Yandex Metrika)

AI traffic

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

Website visits from AI answers: visits from each model and changes over time. Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

timeRangestring

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

fromstring

Period start, ISO date

tostring

Period end, ISO date

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Visitors from AI models

/api/v1/analytics/metrika/visitors

AI-sourced visits and on-site behavior: page depth, goals, and returning visits. Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

timeRangestring

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

fromstring

Period start, ISO date

tostring

Period end, ISO date

hasGoalsboolean

Only visits with completed goals

includeSyntheticboolean

Include synthetic traffic

pvMininteger

Minimum page views

pvMaxinteger

Maximum page views

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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 traffic funnel

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

The path from an AI answer click to a conversion. Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

timeRangestring

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

fromstring

Period start, ISO date

tostring

Period end, ISO date

hasGoalsboolean

Only visits with completed goals

includeSyntheticboolean

Include synthetic traffic

pvMininteger

Minimum page views

pvMaxinteger

Maximum page views

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Mentions and traffic correlation

/api/v1/analytics/metrika/correlation

Compares brand mention trends with actual visit trends: does increased visibility lead to more traffic? Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

companyIdstring (uuid)

Company. If omitted, the key’s preferredCompanyId is used

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

timeRangestring

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

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Metrika goals

/api/v1/analytics/metrika/goals

Counter goal directory explaining the hasGoals parameter used by other methods. Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

includeInactiveboolean

Include inactive goals

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Synthetic traffic summary

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

Share of bot and nonorganic visits to prevent distortion of AI traffic analysis. Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

timeRangestring

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

fromstring

Period start, ISO date

tostring

Period end, ISO date

filterstring

Classification filter

hasGoalsboolean

Only visits with completed goals

pvMininteger

Minimum page views

pvMaxinteger

Maximum page views

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

List synthetic visits

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

Paginated summary details: individual visits with synthetic traffic indicators. Account-scoped: another account’s integrationId is ignored. Empty results usually mean Metrika is not connected; check /api/v1/integrations/metrika/status.

Query parameters

integrationIdstring (uuid)

Metrika counter. If omitted, all connected account counters

timeRangestring

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

fromstring

Period start, ISO date

tostring

Period end, ISO date

filterstring

Classification filter

qstring

qScopestring

Search scope

hasRevenueboolean

With revenue only

returningOnlyboolean

Returning visitors only

pageinteger

Page

pageSizeinteger

Page size

sortBystring

Sort field

sortOrderstring

asc | desc

hasGoalsboolean

Only visits with completed goals

pvMininteger

Minimum page views

pvMaxinteger

Maximum page views

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Connected counters

/api/v1/integrations/metrika/list

Start working with AI traffic here: returns integrationId for the other methods in this section.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Integration status

/api/v1/integrations/metrika/status

Whether Metrika is connected, when it last synced, and whether access has expired. Explains empty results from this section’s methods.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Product cards in AI answers

Commerce analytics

/api/v1/analytics/commerce

Product cards shown by AI models alongside their answers. view=summary: share of answers with cards and trends by model; sellers: top sellers and domains; brands: our brand’s cards versus competitors; cards: paginated list.

Query parameters

viewstring= summary

summary | sellers | brands | cards

summarysellersbrandscards

companyIdstring (uuid)

Company. If omitted, the key’s preferredCompanyId is used

productIdstring[]

Multiple values allowed

timeRangestring

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

granularitystring

Trend breakdown

tzstring

Time zone

labelIdstring[]

Clusters

labelSlugstring[]

Cluster slugs

labelFilterModestring

AND | OR

sourceIdstring[]

Sources

queryTypestring[]

Query types

includeDemoboolean

Include demo data

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Tracked products

/api/v1/commerce/products

Product catalog for matching cards in responses. Without it, Commerce shows sellers and domains but cannot compare our products against competitors.

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Add a product

/api/v1/commerce/products

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Recurring query polling on a schedule

List monitored queries

/api/v1/favorite-queries

Queries scheduled for recurring polling.

Query parameters

searchstring

Search text

activeboolean

Enabled only

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

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

Start monitoring a query

/api/v1/favorite-queries

Regular POST /api/v1/queries polls AI models ONCE. Recurring polling is a separate entity created here. Creating a record does not start polling. Set the schedule in a second step through POST /api/v1/favorite-queries/{id}/assignments. Every scheduled poll is paid: 10 FoxCoin per answer from EACH model. A 60-minute interval across three models means 72 answers per day. With insufficient funds, runs pause and do not resume automatically (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

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get a monitoring entry

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

Query parameters

idstring (uuid)required

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Update a monitoring entry

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

Text, company, tags, isActive. Set isActive: false to stop polling without deleting the record.

Query parameters

idstring (uuid)required

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Stop monitoring a query

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

Deletes the record and schedule: no further polling occurs. Existing answers and mentions remain; they belong to the query, not the subscription.

Query parameters

idstring (uuid)required

Responses

204

Successfully deleted

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Get the polling schedule

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

Query parameters

idstring (uuid)required

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

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

Set the polling schedule

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

This is where recurring polling starts: a record without a schedule does nothing. Each record has one schedule; calling again replaces it. Every scheduled poll is paid: 10 FoxCoin per answer from EACH model. A 60-minute interval across three models means 72 answers per day. With insufficient funds, runs pause and do not resume automatically (POST /api/v1/queries/queue/resume).

Query parameters

idstring (uuid)required

Request body

providersstring[]required

List: GET /api/v1/sources

frequencyMinutesintegerrequired

Polling interval

isEnabledboolean= true

Pause without deleting the schedule

timezonestring= Europe/Moscow

Time zone used to interpret daysOfWeek and hoursWindow

daysOfWeekinteger[]

1..7; empty means every day

hoursWindowobject

Hours outside which polling does not run

modelobject

AI model → model variant mapping

Responses

200

Successful response

400application/json

Input validation error

VALIDATION_ERROR

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

Run a query now

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

Extra polling run without waiting for or shifting the schedule. Standard charges apply.

Query parameters

idstring (uuid)required

Responses

200

Successful response

401application/json

Unauthorized: missing or invalid token

UNAUTHORIZED

404application/json

Resource not found

NOT_FOUND

429application/json

Rate limit exceeded (IP: 120 req/min, per user: 60 req/min)

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

List accessible workspaces

Responses

Switch the API key’s active workspace

Request body

Responses

Companies

List companies

Query parameters

Responses

Create company

Request body

Responses

Get company

Query parameters

Responses

Update company

Query parameters

Request body

Responses

Archive company

Query parameters

Responses

List industries

Responses

Products

List products

Query parameters

Responses

Create product

Request body

Responses

Get product

Query parameters

Responses

Update product

Query parameters

Request body

Responses

Archive product

Query parameters

Responses

Competitors

List competitors

Query parameters

Responses

Create competitor

Request body

Responses

Get competitor

Query parameters

Responses

Update competitor

Query parameters

Request body

Responses

Archive competitor

Query parameters

Responses

Keywords

List intents

Query parameters

Responses

Create or reuse an intent

Request body

Responses

Get an intent

Query parameters

Responses

Rename an intent

Query parameters

Request body

Responses

Archive or delete an intent

Query parameters

Responses