v1.2.0

brandfound. API

API para rastrear menciones de marca en asistentes de IA (ChatGPT, Gemini, Claude, Perplexity). Gestión de empresas, productos, competencia, consultas, menciones y analítica.

URL base

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

Playground

Pulsa en el panel de la solicitud para abrir el Playground interactivo. Selecciona una clave API, define los parámetros y envía la solicitud directamente desde la documentación.

Inicio rápido

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

Respuesta correcta

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

Error

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No encontrado"
  }
}

Límites de solicitudes

Por dirección IP120 / min

Por usuario60 / min

Códigos de error

401

UNAUTHORIZEDAutorización inválida

403

FORBIDDENPermisos insuficientes

404

NOT_FOUNDRecurso no encontrado

400

VALIDATION_ERRORError de validación

429

RATE_LIMIT_EXCEEDEDLímite de tasa superado

500

INTERNAL_ERRORError interno

Novedades de la versión 1.2

Las direcciones públicas de los métodos no han cambiado, se mantiene la compatibilidad.

La analítica vuelve a responder

Los métodos de Analítica, Enlaces y Publicidad devolvían un error 500 por un problema de nuestro lado. Corregido, no requiere acción por su parte.

Estado de la consulta visible

La lista de consultas ahora incluye answersCount, la lista real de asistentes en providers y el estado resumido queue.status. Antes providers siempre llegaba vacío.

Cola de consultas

queries/queue y queue/summary muestran qué se está consultando y cuánto cuesta. Las consultas detenidas por falta de FoxCoin se reanudan con queue/resume, solas no se reinician.

Saldo y gastos

billing/balance devuelve el saldo y los precios de todas las operaciones, billing/transactions el historial de cargos con la consulta asociada.

Idioma de la respuesta

El campo language ahora define el idioma de la respuesta. Funciona en ChatGPT, Gemini, Perplexity y DeepSeek.

Directorio de asistentes

El método sources devuelve los asistentes disponibles y marca los usados por defecto.

Monitorización

Una consulta puede programarse para ejecución periódica. Antes solo estaba disponible en la interfaz.

Tráfico de IA

Visitas al sitio desde respuestas de IA, comportamiento de visitantes, embudo y objetivos según Yandex.Metrica.

Commerce

Fichas de producto en respuestas de IA y el catálogo con el que se comparan.

La empresa pasa a ser obligatoria

Los métodos links, links/filter-options, analytics/links/top-domains, analytics/competitors/preview y advertising exigen companyId. Sin él la respuesta combinaba todas las empresas de la cuenta.

Autenticación

Todas las solicitudes a la API requieren autorización. Crea una clave API en la sección Configuración → Claves API. Las claves tienen el prefijo gfx_.

Bearer Token

Recomendado

Pasa la clave en la cabecera Authorization de cada solicitud.

Cookie de sesión

La aplicación web utiliza automáticamente la cookie session-token. No requiere configuración adicional.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Espacios de trabajo

Espacios de trabajo (workspaces / teams). Un token OAuth puede acceder a todos los espacios disponibles para el usuario: el suyo y aquellos donde sea ACCEPTED TeamMember. El espacio activo se guarda en ApiKey.activeAccountId; el cambio persiste y se aplica a todos los clientes MCP de esa clave desde la siguiente solicitud. El acceso se comprueba en cada solicitud: si se pierde la membresía, el middleware vuelve silenciosamente al accountId asignado durante OAuth, sin error 401. Al cambiar de espacio se restablece preferredCompanyId, vinculado al espacio anterior.

Listar espacios disponibles

/api/v1/workspaces

Devuelve todos los workspaces (accountId) accesibles para el usuario actual: el suyo y aquellos donde sea ACCEPTED TeamMember. `isCurrent: true` indica el espacio que utiliza la clave API, teniendo en cuenta la sustitución activeAccountId.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Cambiar el espacio activo de la clave API

/api/v1/workspaces/switch

Actualiza ApiKey.activeAccountId. El efecto persiste para TODAS las solicitudes posteriores de esa clave, incluidas las de otros clientes MCP. accountId=null elimina la sustitución y vuelve al accountId del token. preferredCompanyId se restablece a null porque pertenece al espacio anterior. Solo con autenticación mediante clave API.

Cuerpo de la solicitud

accountIdstringobligatorio

UUID del workspace de destino. null elimina la sustitución activa y vuelve al accountId asignado durante OAuth.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

403application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Empresas

Gestión de empresas

Listar empresas

/api/v1/companies

Devuelve las empresas del usuario con sus productos, competidores y palabras clave.

Parámetros de consulta

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

sortBystring= createdAt

createdAtupdatedAtnamelastUsedAt

sortOrderstring= desc

Orden de clasificación

ascdesc

searchstring

Texto de búsqueda, sin distinguir mayúsculas y minúsculas

categoryIdstring (uuid)

Filtrar por categoría

countrystring

Filtrar por país

createdAtFromstring (date-time)

Inicio del intervalo de fechas de creación (ISO 8601)

createdAtTostring (date-time)

Fin del intervalo de fechas de creación (ISO 8601)

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear empresa

/api/v1/companies

Crea una empresa. El límite depende del plan contratado.

Cuerpo de la solicitud

namestringobligatorio

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2 («AE»). Se aceptan y normalizan nombres heredados («russia»). Es preferible usar regionTargets: este campo es heredado.

synonymsstring[]

Sinónimos/nombres alternativos (máximo 20)

regionTargetsobject[]

Países y ciudades de medición. Estado COMPLETO: se recrean los destinos anteriores. El destino primary define el país y el idioma de la generación automática de consultas.

defaultLanguageIdstring

Idioma de las consultas generadas (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Idioma en el que debe responder la IA.

defaultLocalestring

BCP-47, por ejemplo «ar-AE».

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Obtener empresa

/api/v1/companies/{id}

Devuelve la información completa de la empresa, incluidos productos, competidores y palabras clave.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la empresa

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Actualizar empresa

/api/v1/companies/{id}

Actualiza parcialmente una empresa. Envía solo los campos que cambian. Configuración regional: regionTargets define los países y ciudades de medición; el destino primary determina el país y el idioma de la selección automática de consultas (POST /api/v1/queries/autogenerate). countryId / cityId proceden de GET /api/v1/geo/countries y /api/v1/geo/cities, y defaultLanguageId de /api/v1/geo/languages. regionTargets representa el estado COMPLETO: los destinos anteriores se vuelven a crear. El campo isAutoGenerationEnabled está obsoleto: activarlo (true) se IGNORA. Era una opción de un programador eliminado que generaba consultas y las añadía inmediatamente a la cola de ejecuciones de pago.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la empresa

Cuerpo de la solicitud

namestring

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2 («AE»). Se aceptan y normalizan nombres heredados («russia»). Es preferible usar regionTargets: este campo es heredado.

synonymsstring[]

isAutoGenerationEnabledboolean

OBSOLETO e IGNORADO cuando vale true. Pertenecía a un programador eliminado que generaba consultas y las añadía inmediatamente a la cola de pago. Para generar sin ejecutar: POST /api/v1/queries/autogenerate.

regionTargetsobject[]

Países y ciudades de medición. Estado COMPLETO: se recrean los destinos anteriores. El destino primary define el país y el idioma de la generación automática de consultas.

defaultLanguageIdstring

Idioma de las consultas generadas (GET /api/v1/geo/languages).

defaultResponseLanguageIdstring

Idioma en el que debe responder la IA.

defaultLocalestring

BCP-47, por ejemplo «ar-AE».

autogenQueryTypesstring[]

Tipos de consulta generados automáticamente. Por defecto: commercial, informational, comparative, reputational. Quitar comparative elimina las comparaciones «X vs Y» de las consultas generadas.

autogenQueriesPerRuninteger

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Archivar empresa

/api/v1/companies/{id}

Archiva la empresa. Los datos se conservan, pero la empresa deja de aparecer en las listas.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la empresa

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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

Eliminado correctamente

Listar sectores

/api/v1/companies/categories

Valores categoryId permitidos al crear o actualizar una empresa.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Productos

Gestión de productos

Listar productos

/api/v1/products

Devuelve los productos con las empresas, palabras clave y competidores asociados.

Parámetros de consulta

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

Orden de clasificación

ascdesc

companyIdstring (uuid)

Filtrar por empresa

searchstring

Texto de búsqueda, sin distinguir mayúsculas y minúsculas

createdAtFromstring (date-time)

Inicio del intervalo de fechas de creación (ISO 8601)

createdAtTostring (date-time)

Fin del intervalo de fechas de creación (ISO 8601)

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear producto

/api/v1/products

Crea un producto asociado a una empresa.

Cuerpo de la solicitud

namestringobligatorio

companyIdstringobligatorio

descriptionstring

urlstring

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Obtener producto

/api/v1/products/{id}

Devuelve la información completa del producto, incluidas sus palabras clave y competidores.

Parámetros de consulta

idstring (uuid)obligatorio

ID del producto

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Actualizar producto

/api/v1/products/{id}

Actualiza parcialmente un producto.

Parámetros de consulta

idstring (uuid)obligatorio

ID del producto

Cuerpo de la solicitud

namestring

descriptionstring

urlstring

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Archivar producto

/api/v1/products/{id}

Archiva el producto. Los datos se conservan, pero el producto deja de aparecer en las listas.

Parámetros de consulta

idstring (uuid)obligatorio

ID del producto

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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

Eliminado correctamente

Competencia

Gestión de competidores

Listar competidores

/api/v1/competitors

Devuelve los competidores con las empresas, productos y palabras clave asociados.

Parámetros de consulta

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

Orden de clasificación

ascdesc

companyIdstring (uuid)

Filtrar por empresa

productIdstring (uuid)

Filtrar por producto

searchstring

Texto de búsqueda, sin distinguir mayúsculas y minúsculas

createdAtFromstring (date-time)

Inicio del intervalo de fechas de creación (ISO 8601)

createdAtTostring (date-time)

Fin del intervalo de fechas de creación (ISO 8601)

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear competidor

/api/v1/competitors

Crea un competidor, que puede vincularse a una empresa o a un producto concreto.

Cuerpo de la solicitud

namestringobligatorio

companyIdstringobligatorio

productIdstring

urlstring

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Obtener competidor

/api/v1/competitors/{id}

Devuelve la información completa del competidor y sus palabras clave.

Parámetros de consulta

idstring (uuid)obligatorio

ID del competidor

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Actualizar competidor

/api/v1/competitors/{id}

Actualiza el nombre y/o la URL del competidor.

Parámetros de consulta

idstring (uuid)obligatorio

ID del competidor

Cuerpo de la solicitud

namestring

urlstring

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Archivar competidor

/api/v1/competitors/{id}

Archiva el competidor. Los datos se conservan, pero el competidor deja de aparecer en las listas.

Parámetros de consulta

idstring (uuid)obligatorio

ID del competidor

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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

Eliminado correctamente

Palabras clave

Intenciones (keywords): creación, cambio de nombre, archivo/eliminación, restore y asociación/desasociación masiva con empresas, productos y competidores

Listar intenciones

/api/v1/keywords

Devuelve las intenciones (keywords) del workspace actual. El filtro target admite solo uno de companyId | productId | competitorId. state controla el archivo: active (por defecto), archived o all.

Parámetros de consulta

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

sortBystring= createdAt

createdAtname

sortOrderstring= desc

Orden de clasificación

ascdesc

statestring= active

Filtro de ciclo de vida: active (no archivados, por defecto), archived (solo archivados), all.

activearchivedall

searchstring

Subcadena de name, sin distinguir mayúsculas y minúsculas.

companyIdstring (uuid)

Solo intenciones con una asociación activa con esta empresa.

productIdstring (uuid)

Solo intenciones con una asociación activa con este producto.

competitorIdstring (uuid)

Solo intenciones con una asociación activa con este competidor.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear o reutilizar una intención

/api/v1/keywords

Busca o crea por (name, userId). Si la intención existe, la reutiliza y la restaura si estaba archivada. El campo opcional attach: { companyId | productId | competitorId }, con exactamente un destino, vincula la intención con él en la misma transacción.

Cuerpo de la solicitud

namestringobligatorio

attachobject

Destino de asociación/desasociación. Debe contener EXACTAMENTE UNO de los campos.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": "..."
  }
}

Respuesta correcta

Obtener una intención

/api/v1/keywords/{id}

Devuelve la intención con sus asociaciones activas a empresas, productos y competidores.

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Renombrar una intención

/api/v1/keywords/{id}

El único campo editable es name. No se puede cambiar el nombre de una intención archivada: utiliza restore primero.

Parámetros de consulta

idstring (uuid)obligatorio

Cuerpo de la solicitud

namestringobligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
        }
      }
    ]
  }
}

Respuesta correcta

Archivar o eliminar una intención

/api/v1/keywords/{id}

Por defecto, archiva la intención y todas sus asociaciones (soft-delete), reversible mediante POST /restore. ?permanent=true la elimina físicamente de la base; debe estar archivada o tener asociaciones archivadas. ?dryRun=true devuelve un informe de los elementos afectados sin ejecutar la operación.

Parámetros de consulta

idstring (uuid)obligatorio

permanentboolean= false

true elimina de forma irreversible de la base de datos. Requiere que el elemento esté archivado.

dryRunboolean= false

true devuelve un informe sin efectos secundarios.

Respuestas

204

Eliminado correctamente

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
          }
        }
      ]
    }
  }
}

Respuesta correcta

Restaurar una intención archivada

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

Elimina archivedAt del keyword y de sus asociaciones archivadas cuyas entidades superiores (company / product / competitor) aún existen. Las asociaciones con destinos eliminados permanecen archivadas.

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
    }
  }
}

Respuesta correcta

Asociar intenciones en lote

/api/v1/keywords/attach

Para cada name, busca o crea por (name, userId) y garantiza una asociación activa con target. Restaura las asociaciones archivadas. target requiere EXACTAMENTE UNO de companyId / productId / competitorId.

Cuerpo de la solicitud

targetobjectobligatorio

Destino de asociación/desasociación. Debe contener EXACTAMENTE UNO de los campos.

namesstring[]obligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
      }
    ]
  }
}

Respuesta correcta

Desvincular intenciones en lote

/api/v1/keywords/detach

Archiva las asociaciones activas keyword↔target. La intención sigue existiendo y puede vincularse con otros destinos. target requiere EXACTAMENTE UNO de companyId / productId / competitorId.

Cuerpo de la solicitud

targetobjectobligatorio

Destino de asociación/desasociación. Debe contener EXACTAMENTE UNO de los campos.

keywordIdsstring[]obligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
    ]
  }
}

Respuesta correcta

Consultas

Gestión de consultas a asistentes de IA

Listar consultas

/api/v1/queries

Devuelve las consultas a asistentes de IA con el número de respuestas. Admite filtros avanzados por sentimiento, grupos, regiones, favoritos, ámbito de búsqueda y rangos de indicadores de sentimiento. Consulta queue.status y answersCount para conocer el estado. providers indica las IA consultadas realmente. Detalles de las ejecuciones: GET /api/v1/queries/queue.

Parámetros de consulta

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

sortBystring= createdAt

createdAttextupdatedAt

sortOrderstring= desc

Orden de clasificación

ascdesc

companyIdstring (uuid)

Filtrar por empresa

productIdstring (uuid)

Filtrar por producto

typestring

Tipo de consulta (general, comparative, negative, etc.). Admite un array: ?type=comparative&type=neutral

originstring

Origen de la consulta. Admite un array: ?origin=manual&origin=auto

manualauto

hasAnswersstring

Existencia de respuestas

truefalse

languagestring

Idioma de la consulta (ru, en, etc.). Admite un array: ?language=ru&language=en

searchTextstring

Búsqueda en el texto de la consulta

providerstring

Filtrar por proveedor de IA de la respuesta

sourceIdstring

Filtrar por ID de la fuente de la respuesta. Admite un array: ?sourceId=id1&sourceId=id2

labelSlugstring

Filtrar por slug del grupo/etiqueta

regionstring

Región de la consulta. Admite un array: ?region=RU&region=US

isFavoritestring

Solo consultas favoritas

truefalse

sentimentstring

Filtrar por sentimiento de las menciones en las respuestas

positiveneutralnegative

searchFieldstring= query

Ámbito de searchText: texto de las consultas, respuestas o fuentes

queryanswersources

labelFilterModestring= or

Lógica del filtro por grupos: any (or) o all (and)

orand

labelstring

Slug del grupo. Admite un array: ?label=slug1&label=slug2

createdAtFromstring (date-time)

Inicio del intervalo de fechas de creación (ISO 8601)

createdAtTostring (date-time)

Fin del intervalo de fechas de creación (ISO 8601)

showArchivedstring

Mostrar consultas archivadas (por defecto: false)

truefalse

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear consulta

/api/v1/queries

Crea una consulta y, por defecto, la añade inmediatamente a la cola de ejecución. De pago: cada respuesta recibida de cada IA consume FoxCoin (precios: GET /api/v1/billing/balance). Una consulta enviada a 5 IA cuesta 5 respuestas. Usa dispatch: false para crearla sin gastar FoxCoin. providers selecciona las IA (slugs: GET /api/v1/sources). Si se omite, se utilizan los valores predeterminados de la cuenta; sin configuración, únicamente ChatGPT. Para crear consultas masivamente con grupos: POST /api/v1/queries/setup. region (ISO 3166-1 alpha-2) y language definen la ubicación. Sin region se utiliza el país de la empresa. geoOverride y resolvedGeoSnapshot son instantáneas READ-ONLY calculadas por el servidor para consultas de grupos con destinos geográficos. No se aceptan en POST: el cuerpo es estricto y un campo desconocido provoca un error 400. Consulta dispatch en la respuesta para conocer el resultado de la puesta en cola: dispatched=false con error no vacío indica que la consulta se creó, pero la ejecución no comenzó.

Cuerpo de la solicitud

textstringobligatorio

companyIdstringobligatorio

productIdstring

typestring= neutral

Se aceptan los valores heredados negative y general: negative → reputational, general → neutral.

neutralcommercialinformationalcomparativereputationalbranded

languagestring= ru

Código ISO 639-1 del idioma de respuesta (ru, en, ar, hi, vi, ms, ...). Define el idioma obligatorio para la IA: se añade al prompt una instrucción explícita con el nombre del idioma del directorio. Por defecto: ru.

regionstring

País de la consulta, ISO 3166-1 alpha-2 (AE, SA, RU). Si se omite, se utiliza el país de la empresa (regionTarget primary) y, después, RU. Se aceptan y normalizan nombres heredados («russia»). No aplica segmentación geográfica a los resultados; sirve para filtros y analíticas.

providersstring[]

IA que se consultarán. Si se omite, se utilizan los valores predeterminados de la cuenta; sin configuración, únicamente ChatGPT.

dispatchboolean= true

false crea la consulta SIN añadirla a una ejecución de pago.

labelsstring[]

Nombres de los grupos: se crean o reutilizan según el slug.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

402application/json

FoxCoin insuficientes

HTTP_402

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
    }
  }
}

Respuesta correcta

Obtener consulta

/api/v1/queries/{id}

Devuelve la consulta, las respuestas de los asistentes de IA y las menciones detectadas.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la consulta

includeAnswersstring= true

Incluir respuestas con sus menciones (true por defecto)

truefalse

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Archivar consulta

/api/v1/queries/{id}

Archiva la consulta. Los datos se conservan y pueden restaurarse.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la consulta

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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

Eliminado correctamente

Modificar una consulta

/api/v1/queries/{id}

Modifica el texto, tipo, idioma, región, producto, estado de favorito y grupos de la consulta. Cambiar el texto NO vuelve a consultar las IA: las respuestas existentes siguen vinculadas a la consulta. Crea una consulta nueva para repetir la ejecución. Cuerpo estricto: campo desconocido → 400.

Parámetros de consulta

idstring (uuid)obligatorio

Cuerpo de la solicitud

textstring

typestring

neutralcommercialinformationalcomparativereputationalbranded

languagestring

regionstring

ISO 3166-1 alpha-2.

productIdstring

null desvincula la consulta del producto.

isFavoriteboolean

labelsstring[]

Lista COMPLETA de grupos: se recrean las asociaciones.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
    }
  }
}

Respuesta correcta

Listar ejecuciones en cola

/api/v1/queries/queue

Estado de las ejecuciones: una por cada par consulta/IA. Permite distinguir entre una consulta aún en curso, un fallo y una pausa por falta de fondos, algo que el número de respuestas por sí solo no permite.

Parámetros de consulta

statusstring= queued,onHold,failed

Grupos de estados separados por comas. Los tres por defecto.

companyIdstring (uuid)

Limitar a una empresa. Si se omite, todas las empresas de la cuenta.

queryIdstring (uuid)

Ejecuciones de una consulta

providerstring

Filtrar por IA

chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_mode

includeArchivedboolean= false

Incluir ejecuciones de consultas archivadas

limitinteger= 50

Tamaño de página

offsetinteger= 0

Desplazamiento

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Resumen de la cola y coste estimado

/api/v1/queries/queue/summary

Contadores de ejecuciones, coste de la cola actual y saldo FoxCoin en una solicitud. Mientras queuedTotal > 0, la ejecución continúa. onHold > 0 indica falta de fondos: esas ejecuciones no se reanudan automáticamente, ni tras recargar el saldo.

Parámetros de consulta

companyIdstring (uuid)

Limitar a una empresa

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Crear consultas en lote con los modelos de IA seleccionados

/api/v1/queries/setup

Crea grupos y consultas en una transacción y los añade inmediatamente a la cola. providers permite seleccionar los modelos de IA; si se omite, se usan los valores del perfil de la cuenta. Para crear una sola consulta, utilice POST /api/v1/queries, que también acepta providers. De pago: cada respuesta recibida de cada modelo cuesta FoxCoin (véase GET /api/v1/billing/balance). Máximo de 500 consultas por llamada.

Cuerpo de la solicitud

companyIdstring

Si se omite, utiliza preferredCompanyId de la clave (véase GET /api/v1/context)

clusterIdstring

Grupo existente del que heredar la configuración geográfica; se aplica a todos los elementos de clusters sin clusterId propio

providersstring[]

Modelos de IA que se consultarán (slugs de GET /api/v1/sources). Si se omite, se usan los valores predeterminados de la cuenta; una cuenta sin configurar utiliza ChatGPT. POST /api/v1/queries también permite la selección mediante providers.

clustersobject[]obligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

402application/json

FoxCoin insuficientes

HTTP_402

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
        ]
      }
    ]
  }
}

Respuesta correcta

Devolver ejecuciones a la cola

/api/v1/queries/queue/resume

Reanuda las ejecuciones pausadas. **Por qué.** Si el saldo FoxCoin es insuficiente, la ejecución pasa a ON_HOLD_NO_FUNDS. Los workers no la procesan y recargar el saldo NO la reactiva. Permanece en espera hasta que el programador la cambia a CANCELLED después de 45 días. Desde fuera puede parecer que has pagado pero las consultas no avanzan. La reanudación siempre debe solicitarse explícitamente mediante este método. **Cómo ocurre.** Crea consultas con saldo insuficiente. La comprobación se realiza al ponerlas en cola y al ejecutarlas: algunas ejecuciones pueden estar pausadas aunque la consulta se haya completado parcialmente. Comprueba `GET /api/v1/queries/queue/summary` → `onHold` o `queue.status` = `on_hold_no_funds`. **402 no es un rechazo definitivo:** el saldo no cubre todo el lote. Recárgalo o repite con `force: true`: se procesarán las ejecuciones cubiertas y las demás volverán a pausarse.

Cuerpo de la solicitud

runIdsstring[]

Seleccionar ID de ejecuciones concretas

scopestring

Todas las ejecuciones pausadas

onHold

companyIdstring

Limitar scope a una empresa

forceboolean= false

Reanudar aunque el saldo no cubra todo el lote

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

402application/json

FoxCoin insuficientes para todo el lote

HTTP_402

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Retirar ejecuciones de la cola

/api/v1/queries/queue/cancel

Cancela ejecuciones que aún no han comenzado: pendientes (PENDING, RETRYING) o pausadas. Nunca modifica las que están RUNNING: ya están siendo procesadas por un worker y cancelarlas provocaría una condición de carrera. **Cuándo usarlo.** Para detener un lote innecesario antes de que consuma FoxCoin: el cargo ocurre al recibir una respuesta, por lo que una ejecución cancelada no cuesta nada. También permite retirar una cola bloqueada que no se piensa pagar. La cancelación es reversible: una ejecución puede volver a la cola mediante `POST /api/v1/queries/queue/resume` con su `runId`.

Cuerpo de la solicitud

runIdsstring[]

queryIdsstring[]

Todas las ejecuciones cancelables de estas consultas

scopestring

onHold: solo pausadas; queued: solo cola activa

onHoldqueued

companyIdstring

Limitar scope a una empresa

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Generación de consultas

Selección automática de consultas: generación de borradores y confirmación. La generación (1 FoxCoin por consulta) y la consulta de pago a las IA (10 FoxCoin por respuesta) son pasos distintos.

Generar sugerencias sin consultar modelos de IA

/api/v1/queries/autogenerate

El servicio propone consultas y las guarda como BORRADORES. En este paso NO se consultan las IA. Sustituye isAutoGenerationEnabled, que iniciaba la generación y la ejecución de pago a la vez sin permitir separarlas. Aquí la ejecución solo comienza con POST /api/v1/query-drafts/approve. Coste: 1 FoxCoin por CADA consulta generada, cobrado según los borradores entregados realmente. La ejecución se cobra por separado: 10 FoxCoin por respuesta (consulta × IA). Idioma y país: sin language/region se utiliza la configuración regional de la empresa (regionTargets, PUT /api/v1/companies/{id}) y, después, ru/RU. Para varios países, envía targets: una tarea por país, con su idioma oficial por defecto (AE → ar, IN → hi). Tipos: sin types, utiliza Company.autogenQueryTypes, por defecto commercial, informational, comparative, reputational. Las comparaciones «X vs Y» solo se generan si comparative está en la lista Y la empresa tiene competidores. Por defecto, devuelve 202 inmediatamente y genera en segundo plano: consulta el progreso con GET en la misma dirección usando clientToken. La forma corta (region/language/city/includeDistricts) y targets son incompatibles: usarlas juntas devuelve 400, porque fuera de targets no se puede asignar una ciudad a un país concreto.

Cuerpo de la solicitud

companyIdstring

Si se omite, utiliza preferredCompanyId de la clave.

productIdstring

countintegerobligatorio

Número de consultas que se generarán POR destino. 1 FoxCoin por consulta.

typesstring[]

Tipos de consulta generados; count se reparte por igual. Si se omite, utiliza Company.autogenQueryTypes, que incluye comparative por defecto.

clustersstring[]

Temas en los que se distribuyen las consultas.

userWishesstring

namestring

Nombre de la tarea, visible en la interfaz y en GET.

languagestring

ISO 639-1. Si se omite, idioma de la empresa. Solo SIN targets.

regionstring

ISO 3166-1 alpha-2. Si se omite, país primary de la empresa (regionTargets) y, después, RU. Se aceptan nombres heredados («russia»). Solo SIN targets.

citystring

Solo SIN targets.

includeDistrictsboolean

Solo SIN targets.

targetsobject[]

Medición en varios países: una tarea por país. El coste es la suma de count de todos los destinos. INCOMPATIBLE con la forma corta: region / language / city / includeDistricts junto a targets → 400. Dentro de targets, cada país tiene su ciudad e idioma.

waitboolean= false

true espera a que termine la generación. Solo para lotes pequeños: a partir de 100 consultas, el proceso tarda varios minutos.

clientTokenstring

Tu marcador de tarea, utilizado después para consultar su progreso.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

402application/json

FoxCoin insuficientes: campos required y balance en el cuerpo del error

HTTP_402

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 60 req/min)

RATE_LIMIT_EXCEEDED

503application/json

La generación automática no está configurada en el servidor

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

Respuesta correcta

Estado de las tareas de generación de consultas

/api/v1/queries/autogenerate

Progreso de las tareas iniciadas con POST /api/v1/queries/autogenerate. Consulta hasta status = OK y después recupera los borradores mediante GET /api/v1/query-drafts. No se permite aprobar borradores de una tarea RUNNING, para evitar confirmar un lote incompleto.

Parámetros de consulta

runIdstring (uuid)

Tarea concreta.

clientTokenstring

Tarea identificada por el marcador del cliente devuelto por POST.

limitinteger= 20

Número de tareas recientes que se devolverán.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
    }
  ]
}

Respuesta correcta

Detener una tarea de generación

/api/v1/queries/autogenerate/cancel

La cancelación es efectiva: los lotes no iniciados no se ejecutan y solo se cobran los borradores ya entregados. La ejecución pasa a CANCELLED; los borradores generados se conservan y pueden aprobarse.

Cuerpo de la solicitud

runIdstringobligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Listar borradores de consultas

/api/v1/query-drafts

Guardar un borrador no tiene coste ni consulta ninguna IA. Solo se convierte en consulta mediante POST /api/v1/query-drafts/approve.

Parámetros de consulta

statusstring

PENDING: pendientes de decisión. Todos los estados por defecto.

PENDINGAPPROVEDREJECTEDEXPIRED

companyIdstring (uuid)

Filtrar por empresa.

typestring

Filtrar por tipo de consulta.

neutralcommercialinformationalcomparativereputationalbranded

pageinteger= 1

Número de página, desde 1.

limitinteger= 50

Tamaño de página.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": {}
  }
}

Respuesta correcta

Aprobar borradores y ejecutar consultas

/api/v1/query-drafts/approve

PASO DE PAGO: los borradores aprobados se convierten en consultas enviadas a las IA elegidas, a 10 FoxCoin por respuesta (consulta × IA). 50 borradores × 3 IA = 150 respuestas = 1500 FoxCoin. Llama primero con dryRun: true y muestra el presupuesto al usuario. Idempotente: repetir la llamada con los mismos draftIds no duplica las consultas ni vuelve a ejecutarlas. Se omiten los borradores de una tarea de generación aún en curso (skippedRunning); espera a status = OK.

Cuerpo de la solicitud

draftIdsstring[]obligatorio

providersstring[]obligatorio

IA que se consultarán. Cada una multiplica el coste.

dryRunboolean

true devuelve solo el presupuesto, sin crear nada ni cobrar.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

402application/json

FoxCoin insuficientes: campos required y balance en el cuerpo del error

HTTP_402

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Rechazar borradores

/api/v1/query-drafts/reject

Rechazo lógico: el borrador permanece en la base con estado REJECTED para auditar la facturación. No se consulta ninguna IA. No se reembolsan los FoxCoin de generación, ya que las consultas ya se generaron.

Cuerpo de la solicitud

draftIdsstring[]obligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Respuestas de IA

Respuestas de IA por lotes: enlaces, menciones y sentimiento.

Obtener respuestas de IA en lote

/api/v1/answers

Sustituye un bucle GET /api/v1/queries/{id} por cada consulta: una página contiene hasta 200 respuestas con enlaces, menciones y sentimiento. links contiene las citas analizadas de CUALQUIER IA. No debe confundirse con answer.sources, que contiene los datos brutos del scraper, solo se rellena para «Búsqueda con Alice» y no es una lista de citas. brandDomainCited indica si la respuesta cita el dominio del sitio de la empresa. Campos de mención: position es el DESPLAZAMIENTO EN CARACTERES dentro de la respuesta. El array se ordena por ese valor; el orden de aparición de la marca es la POSICIÓN de la mención en el array, no el valor de position. sentiment (1 / 0 / -1) y sentimentScore (-1..1) describen la respuesta COMPLETA y son iguales para todas sus menciones. sentimentScore = null si aún no se ha calculado el sentimiento. isOurs = false identifica a un competidor. Los parámetros de array se repiten: ?companyId=a&companyId=b.

Parámetros de consulta

companyIdstring[]

Empresas; admite varias.

productIdstring[]

Productos; admite varios.

queryIdstring[]

Solo respuestas a estas consultas.

sourceIdstring[]

IA por id (GET /api/v1/sources).

providerstring[]

IA por slug.

typestring[]

Tipo de consulta al que pertenece la respuesta.

labelstring[]

Slugs de los grupos.

regionstring[]

Región de la consulta, ISO 3166-1 alpha-2. También se reconocen nombres heredados.

languagestring[]

Idioma de la consulta.

createdAtFromstring (date-time)

Fecha de creación de la RESPUESTA, límite inicial (ISO 8601).

createdAtTostring (date-time)

Fecha de creación de la RESPUESTA, límite final (ISO 8601).

hasLinksboolean

true: solo respuestas con enlaces; false: solo respuestas sin enlaces.

mentionsOursboolean

true: solo respuestas que mencionan la marca de la empresa.

showArchivedboolean= false

true: incluir respuestas de consultas archivadas.

includestring= content,tonality

Elementos que se incluirán, separados por comas: content, links, mentions, tonality.

limitinteger= 50

Tamaño de página.

offsetinteger= 0

Desplazamiento.

sortBystring= createdAt

Campo de ordenación.

createdAtdate

sortOrderstring= desc

Sentido de ordenación.

ascdesc

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
        }
      ]
    }
  ]
}

Respuesta correcta

Geografía

Directorios de países, regiones, ciudades e idiomas.

Listar países

/api/v1/geo/countries

Los id del directorio se utilizan en regionTargets y defaultLanguageId de empresas y grupos; iso2 se utiliza en region de las consultas y de la generación automática.

Parámetros de consulta

qstring

Búsqueda por nombre.

continentstring

Filtrar por continente.

EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICA

limitinteger= 250

Número máximo de registros.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Listar regiones de un país

/api/v1/geo/regions

Regiones (provincias, estados) de un país. Es obligatorio countryId o countryIso2.

Parámetros de consulta

countryIso2string

Código de país de dos letras.

countryIdstring (uuid)

UUID del país.

qstring

Búsqueda por nombre.

limitinteger= 100

Número máximo de registros.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": {}
}

Respuesta correcta

Listar ciudades de un país

/api/v1/geo/cities

Ciudades de un país. Es obligatorio countryId o countryIso2. cityId se utiliza en regionTargets de las empresas y targets de los grupos.

Parámetros de consulta

countryIso2string

Código de país de dos letras.

countryIdstring (uuid)

UUID del país.

regionIdstring (uuid)

UUID de la región.

qstring

Búsqueda por nombre.

limitinteger= 50

Número máximo de registros.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": {}
}

Respuesta correcta

Listar idiomas

/api/v1/geo/languages

Los id del directorio se utilizan en regionTargets y defaultLanguageId de empresas y grupos; iso2 se utiliza en region de las consultas y de la generación automática.

Parámetros de consulta

qstring

Búsqueda por nombre o código.

limitinteger= 200

Número máximo de registros.

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Clústeres de consultas

Etiquetas/grupos de consultas: lista con filtro opcional por empresa y creación con configuración regional

Listar grupos de consultas

/api/v1/query-labels

Devuelve las etiquetas/grupos de consultas del workspace actual con el número de consultas de cada uno. companyId limita los resultados a grupos con consultas de esa empresa; queryCount cuenta solo sus consultas. lite=true devuelve la forma reducida { items: [{ id, name, slug, queryCount }] }, sin estadísticas ni sampleQueries.

Parámetros de consulta

companyIdstring (uuid)

Filtro por empresa: solo grupos que contienen sus consultas; queryCount cuenta sus consultas.

litestring

lite=true devuelve la forma reducida { items: [{ id, name, slug, queryCount }] }, sin estadísticas.

truefalse

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

qstring

Subcadena del nombre de la etiqueta, sin distinguir mayúsculas y minúsculas.

sortstring= queryCount:desc

Orden en formato field:direction.

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

hasQueriesstring

with: grupos con consultas; without: grupos vacíos.

withwithout

minCountinteger

Número mínimo de consultas del grupo.

maxCountinteger

Número máximo de consultas del grupo.

createdFromstring (date-time)

Etiquetas creadas a partir de la fecha indicada.

createdTostring (date-time)

Etiquetas creadas hasta la fecha indicada.

lastUsedFromstring (date-time)

Etiquetas con lastUsedAt igual o posterior a la fecha indicada.

lastUsedTostring (date-time)

Etiquetas con lastUsedAt igual o anterior a la fecha indicada.

includestring

include=targets añade los destinos geográficos del grupo (country/city).

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear o actualizar un grupo regional de consultas

/api/v1/query-labels

Busca o crea por (slug, userId). Si existe un grupo con ese slug, se actualizan el nombre y la configuración geográfica y se recrean sus targets. Se aceptan companyId/productId opcionales, pero aún no se guardan en QueryLabel.

Cuerpo de la solicitud

namestringobligatorio

slugstring

descriptionstring

companyIdstring

productIdstring

defaultLanguageIdstring

defaultLocalestring

defaultResponseLanguageIdstring

geoScopestring

GLOBALCOUNTRYREGIONCITY

injectLocationModestring

NONEAPPEND_PARENSAPPEND_NATURALPREPENDAI_REWRITE

autogenStrategystring

SHAREDPER_TARGETPER_TARGET_LOCALIZED

targetsobject[]

Respuestas

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

409application/json

Conflicto: el recurso ya existe

CONFLICT

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": "Error de validación de los datos de entrada"
  }
}

Error de validación de los datos de entrada

Menciones

Consulta de menciones de marca

Listar menciones

/api/v1/mentions

Devuelve las menciones de marca en respuestas de asistentes de IA con su contexto completo.

Parámetros de consulta

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

sortBystring= createdAt

createdAtpositionsentiment

sortOrderstring= desc

Orden de clasificación

ascdesc

timeRangestring

Intervalo temporal

24h7d30d90dall

createdAtFromstring (date-time)

Inicio del intervalo de fechas de creación (ISO 8601)

createdAtTostring (date-time)

Fin del intervalo de fechas de creación (ISO 8601)

companyIdstring (uuid)

Filtrar por empresa

productIdstring (uuid)

Filtrar por producto

competitorIdstring (uuid)

Filtrar por competidor

answerIdstring (uuid)

Filtrar por una respuesta concreta

typestring

Tipo de mención

companyproductkeywordcompetitor

sentimentstring

Sentimiento

positiveneutralnegative

searchstring

Texto de búsqueda, sin distinguir mayúsculas y minúsculas

isOursstring

Solo nuestra marca (true) o los competidores (false)

truefalse

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Analítica

Analíticas: competidores, sentimiento, enlaces y visibilidad de marca

Analítica de competidores

/api/v1/analytics/competitors

Análisis comparativo completo de tu empresa y sus competidores según las menciones en asistentes de IA. Admite filtros por grupos (slug), proveedores de IA y período.

Parámetros de consulta

timeRangestring= 30d

Intervalo temporal

24h7d30dall

fromstring (date-time)

Inicio del intervalo personalizado (ISO 8601)

tostring (date-time)

Fin del intervalo personalizado (ISO 8601)

companyIdstring (uuid)

ID de la empresa

productIdstring (uuid)

ID del producto

sourceIdstring[]

ID de proveedores de IA

labelIdstring[]

ID de grupos/etiquetas

labelSlugstring

Slug del grupo. Array: ?labelSlug=slug1&labelSlug=slug2

labelFilterModestring= or

Modo de filtrado por etiquetas

orand

includeDemostring

Incluir datos de demostración

truefalse

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Vista previa de menciones

/api/v1/analytics/competitors/preview

Devuelve respuestas concretas de asistentes de IA con menciones para un análisis detallado. Admite filtros por grupos, datos de demostración, período personalizado y lógica de filtrado por etiquetas. companyId es obligatorio: sin él se mezclarían los datos de todas las empresas de la cuenta. Si se omite, se utiliza preferredCompanyId de la clave (véase GET /api/v1/context).

Parámetros de consulta

sidestringobligatorio

Parte analizada: nuestra empresa o un competidor

ourcompetitor

competitorNamestring

Nombre del competidor (si side=competitor)

mentionTypestring= both

Tipo de mención

brandlinkboth

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

sourceIdstring[]

labelIdstring[]

includeMentionsstring

Incluir menciones en la respuesta

truefalse

includeDemostring

Incluir datos de demostración

truefalse

labelFilterModestring= or

Lógica del filtrado por grupos

orand

fromstring (date-time)

Inicio del período (ISO 8601)

tostring (date-time)

Fin del período (ISO 8601)

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Analítica de tonalidad

/api/v1/analytics/tonality

Análisis completo del sentimiento de las respuestas de asistentes de IA: indicadores de calidad, evolución temporal, respuestas problemáticas y mejores respuestas.

Parámetros de consulta

timeRangestring= 30d

24h7d30d90d

companyIdstring (uuid)

productIdstring (uuid)

queryTypestring

Tipo de consulta

neutralcomparativenegative

sentimentstring

Filtrar por sentimiento

positiveneutralnegative

sourceIdstring[]

Proveedores de IA

labelSlugstring[]

Grupos/etiquetas por slug

labelFilterModestring= or

orand

fromstring (date-time)

tostring (date-time)

includeDemostring

truefalse

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Analítica de enlaces

/api/v1/analytics/links

Analíticas de enlaces de respuestas de asistentes de IA: principales dominios, citas por proveedor y evolución temporal. Admite filtros por sentimiento, grupos, tipo de consulta, umbrales Impact/Overall Score y período personalizado. companyId es obligatorio: sin él se mezclarían los datos de todas las empresas de la cuenta. Si se omite, se utiliza preferredCompanyId de la clave (véase GET /api/v1/context).

Parámetros de consulta

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

labelSlugstring[]

sortDomainsBystring

Orden de los dominios

sentimentstring

Filtrar por sentimiento

positiveneutralnegative

minImpactnumber

Umbral mínimo de Impact Score

minOverallnumber

Umbral mínimo de Overall Score

presetstring

Preajuste de filtrado

queryTypestring

Tipo de consulta

neutralnegativecomparative

labelstring

Slug del grupo

labelFilterModestring= or

Lógica de filtrado

orand

fromstring (date-time)

Inicio del período

tostring (date-time)

Fin del período

chartOnlystring

Solo datos del gráfico

truefalse

citationModestring

Modo de cita

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Dominios principales

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

Devuelve los dominios más citados en las respuestas de asistentes de IA. Admite filtros por sentimiento, tipo de consulta, umbrales Impact/Overall Score y datos de demostración. companyId es obligatorio: sin él se mezclarían los datos de todas las empresas de la cuenta. Si se omite, se utiliza preferredCompanyId de la clave (véase GET /api/v1/context).

Parámetros de consulta

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

limitinteger= 10

Número de dominios

includeDemostring

Incluir datos de demostración

truefalse

sentimentstring

Filtrar por sentimiento

positiveneutralnegative

minImpactnumber

Umbral mínimo de Impact Score

minOverallnumber

Umbral mínimo de Overall Score

queryTypestring

Tipo de consulta

neutralnegativecomparative

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Visibilidad de marca

/api/v1/analytics/brand-visibility

Evolución de la visibilidad de marca frente a competidores, con granularidad ajustable. Admite filtros por grupos (ID y slug), proveedores de IA y lógica de filtrado.

Parámetros de consulta

granularitystring= day

Granularidad del eje temporal

dayweekmonth

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

fromstring (date-time)

tostring (date-time)

labelIdstring

ID del grupo. Array: ?labelId=id1&labelId=id2

labelSlugstring

Slug del grupo

labelFilterModestring= or

Lógica de filtrado

orand

sourceIdstring

ID de la fuente de IA

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Evolución de las citas

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

Proporción diaria de respuestas que nos citan frente a competidores. Se calcula a partir de agregados diarios; solo admite el modo de cita global, ya que estos agregados no distinguen citas por URL y por dominio.

Parámetros de consulta

companyIdstring (uuid)

Empresa. Si se omite, se utiliza preferredCompanyId de la clave

productIdstring

Producto

timeRangestring

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

granularitystring

Desglose de la evolución temporal

tzstring

Zona horaria

sourceIdstring[]

Fuentes

labelSlugstring[]

Grupos

labelFilterModestring

AND | OR

includeDemoboolean

Incluir datos de demostración

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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
}

Respuesta correcta

Empresas y productos para filtros

/api/v1/analytics/companies-products

Empresas de la cuenta con sus productos, para el selector «empresa → producto». Aquí companyId NO es obligatorio: sin él se devuelven todas las empresas, que es precisamente el objetivo del método.

Parámetros de consulta

companyIdstring (uuid)

Limitar a una empresa

includeDemoboolean

Incluir datos de demostración

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Enlaces

Dominios y enlaces de las respuestas de IA

Dominios y enlaces

/api/v1/links

Tabla de dos niveles con dominios y enlaces de las respuestas de asistentes de IA, con ordenación y filtros. companyId es obligatorio: sin él se mezclarían los datos de todas las empresas de la cuenta. Si se omite, se utiliza preferredCompanyId de la clave (véase GET /api/v1/context).

Parámetros de consulta

pageinteger= 1

Número de página

pageSizeinteger= 50

Tamaño de página

sortBystring= lastMentioned

lastMentionedmentionCountanswerCountourMentionCountcompetitorMentionCountdomaintrustRankdomainLinks

sortDirstring= desc

ascdesc

searchstring

Texto de búsqueda, sin distinguir mayúsculas y minúsculas

searchFieldstring

Campo de búsqueda

domainurltitle

timeRangestring

24h7d30d

fromstring (date-time)

tostring (date-time)

companyIdstring (uuid)

productIdstring (uuid)

sentimentstring

positiveneutralnegative

queryTypestring

neutralnegativecomparative

providerstring[]

Proveedores de IA

activestring

Solo enlaces activos

truefalse

domainsOnlystring

Solo dominios, sin enlaces secundarios

truefalse

domainstring

Enlaces secundarios de un dominio concreto

labelstring[]

Grupos/etiquetas

includeDemostring

truefalse

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Opciones de filtro

/api/v1/links/filter-options

Devuelve los valores disponibles para los filtros de la tabla de enlaces: proveedores y etiquetas. companyId es obligatorio: sin él se mezclarían los datos de todas las empresas de la cuenta. Si se omite, se utiliza preferredCompanyId de la clave (véase GET /api/v1/context).

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Analíticas de bloques publicitarios y promocionales en respuestas de asistentes de IA. Admite paginación, búsqueda por dominio/URL, filtros por grupos, tipo de promoción, período y ordenación. companyId es obligatorio: sin él se mezclarían los datos de todas las empresas de la cuenta. Si se omite, se utiliza preferredCompanyId de la clave (véase GET /api/v1/context).

Parámetros de consulta

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

pageinteger= 1

Número de página

pageSizeinteger= 50

Tamaño de página

searchstring

Búsqueda por dominio o URL

searchFieldstring

Campo de búsqueda

domainurltitle

labelstring

Slug del grupo. Array: ?label=slug1&label=slug2

promoTypestring

Tipo de bloque promocional

sortBystring

Campo de ordenación

sortDirstring

Sentido de ordenación

ascdesc

fromstring (date-time)

Inicio del período (ISO 8601)

tostring (date-time)

Fin del período (ISO 8601)

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Vista previa de bloques publicitarios

/api/v1/advertising/preview

Detalle del resumen /api/v1/advertising: promociones mostradas y respuestas donde aparecen.

Parámetros de consulta

domainstringobligatorio

Dominio de la promoción. OBLIGATORIO; si falta, error 400

companyIdstring (uuid)

Empresa. Si se omite, se utiliza preferredCompanyId de la clave

productIdstring

Producto

promoTypestring

ours | competitor | other

ourscompetitorother

timeRangestring

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

labelstring[]

Grupos

labelFilterModestring

AND | OR

limitinteger= 20

1..50

offsetinteger= 0

Desplazamiento

includeDemoboolean

Incluir datos de demostración

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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
}

Respuesta correcta

Fábrica de contenido

Fábrica de contenido: tareas, etiquetas, enriquecimiento, generación de esquemas y artículos, detección de hallazgos

Listar tareas

/api/v1/factory/tasks

Devuelve las tareas de la fábrica de contenido con filtros, paginación y ordenación.

Parámetros de consulta

companyIdstring (uuid)

Filtrar por empresa

statusstring[]

Filtrar por estado; admite varios: ?status=TODO&status=IN_PROGRESS

typestring[]

Filtrar por tipo de tarea; admite varios

prioritystring[]

Filtrar por prioridad; admite varias

searchstring

Búsqueda en el título y la descripción de la tarea

tagIdstring (uuid)

Filtrar por etiqueta

aiGeneratedboolean

Filtro: solo tareas generadas por IA

sortBystring= createdAt

createdAtupdatedAtprioritystatusposition

sortOrderstring= desc

Orden de clasificación

ascdesc

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear tarea

/api/v1/factory/tasks

Crea una tarea en la fábrica de contenido.

Cuerpo de la solicitud

titlestringobligatorio

Título de la tarea

companyIdstringobligatorio

ID de la empresa

typestringobligatorio

Tipo de tarea

NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDY

prioritystring= MEDIUM

Prioridad

CRITICALHIGHMEDIUMLOW

descriptionstring

Descripción de la tarea

targetKeywordsstring[]

Palabras clave objetivo (máximo 20)

targetProvidersstring[]

Proveedores de IA objetivo

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Obtener tarea

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

Devuelve la información completa de una tarea de la fábrica de contenido.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Actualizar tarea

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

Actualiza parcialmente una tarea de la fábrica de contenido.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Cuerpo de la solicitud

statusstring

IDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSED

prioritystring

CRITICALHIGHMEDIUMLOW

titlestring

descriptionstring

tagIdsstring[]

Array de ID de etiquetas que se asociarán

targetKeywordsstring[]

targetProvidersstring[]

dueDatestring

Fecha límite de la tarea

metadataobject

Metadatos libres de la tarea

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Archivar tarea

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

Archiva la tarea. Los datos se conservan, pero su estado pasa a DISMISSED.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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

Eliminado correctamente

Enriquecer tarea

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

Búsqueda RAG en la base de fuentes, análisis de competidores y recomendaciones de IA.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Cuerpo de la solicitud

topicstringobligatorio

Tema que se enriquecerá

descriptionstring

Descripción adicional

keywordsstring[]

Palabras clave para la búsqueda RAG

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": {}
}

Respuesta correcta

Generar plan

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

Genera un esquema de artículo a partir de los datos enriquecidos: estructura, títulos, ideas principales y tono.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Cuerpo de la solicitud

promptstring

Instrucciones adicionales para generar el esquema

topicIdstring

ID del tema seleccionado entre las sugerencias

topicTitlestring

Título del tema

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
    }
  }
}

Respuesta correcta

Generar artículo

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

Genera un artículo a partir de un esquema, mediante streaming SSE. Content-Type: text/event-stream.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Cuerpo de la solicitud

planIdstring

ID del esquema utilizado para generar el artículo

articleLengthstring= medium

Longitud del artículo: short (~1000 palabras), medium (~2000), long (~3500)

shortmediumlong

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": "No autenticado: token ausente o no válido"
  }
}

No autenticado: token ausente o no válido

Versiones de contenido

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

Devuelve las versiones de contenido de la tarea: esquemas, artículos y briefs.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

typestring

Filtrar por tipo de contenido

planarticlebrief

planIdstring

Filtrar por ID del esquema

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Analítica de la tarea

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

Devuelve las analíticas de la tarea: estadísticas de enriquecimiento, generación y publicación.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Sugerir temas

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

Genera 10 temas a partir de los datos de la tarea.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la tarea

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
    }
  ]
}

Respuesta correcta

Listar etiquetas

/api/v1/factory/tags

Devuelve todas las etiquetas de la fábrica de contenido con el número de tareas.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Crear etiqueta

/api/v1/factory/tags

Crea una etiqueta para las tareas de la fábrica de contenido.

Cuerpo de la solicitud

namestringobligatorio

Nombre de la etiqueta

colorstring

Color HEX, por ejemplo #6366f1

iconstring

Icono de la etiqueta, opcional

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

409application/json

Conflicto: el recurso ya existe

CONFLICT

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Actualizar etiqueta

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

Actualiza parcialmente una etiqueta de la fábrica de contenido.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la etiqueta

Cuerpo de la solicitud

namestring

colorstring

iconstring

positioninteger

Posición de ordenación

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

409application/json

Conflicto: el recurso ya existe

CONFLICT

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Eliminar etiqueta

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

Elimina una etiqueta. No se pueden eliminar las etiquetas del sistema.

Parámetros de consulta

idstring (uuid)obligatorio

ID de la etiqueta

Respuestas

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

403application/json

Acceso denegado

FORBIDDEN

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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

Eliminado correctamente

Listar publicaciones

/api/v1/factory/publications

Devuelve la lista paginada de publicaciones de la fábrica de contenido.

Parámetros de consulta

companyIdstring (uuid)

Filtrar por empresa

offsetinteger= 0

Desplazamiento de paginación

limitinteger= 20

Número de registros por página

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Detectar insights

/api/v1/factory/insights

Ejecuta los detectores (15 tipos): carencias de contenido, éxitos de competidores, oportunidades sin explotar, riesgos reputacionales, etc.

Cuerpo de la solicitud

companyIdstringobligatorio

ID de la empresa

insightTypestring

Tipo de hallazgo; si se omite, se ejecutan todos los detectores

CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDING

limitinteger

Número máximo de hallazgos

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
    }
  }
}

Respuesta correcta

Ajustes de Factory

/api/v1/factory/settings

Devuelve la configuración actual de la fábrica de contenido del usuario.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Actualizar ajustes

/api/v1/factory/settings

Actualiza la configuración de la fábrica de contenido mediante una combinación recursiva (deep merge).

Cuerpo de la solicitud

settingsobjectobligatorio

Configuración que se combinará recursivamente con la actual

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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": {}
}

Respuesta correcta

Obtener la ficha de marca

/api/v1/factory/brand-card

Lee la ficha de marca, un árbol de documentos Markdown de la empresa con la información utilizada para generar contenido. Tres modos: sin parámetros adicionales, toda la ficha en un documento Markdown (manifiesto → archivos core → archivos enlazados → resto; se excluyen los bloques privados ```private; límite de unos 12 000 caracteres); mode=index devuelve el manifiesto y los archivos con path, id, isCore y enlaces salientes; path=... devuelve un archivo: content, conservando literalmente los enlaces [Nombre](brandcard://id), y links con la ruta resuelta de cada enlace.

Parámetros de consulta

companyIdstring (uuid)obligatorio

ID de la empresa

modestring

index devuelve el manifiesto y la lista de archivos en lugar de la ficha completa

index

pathstring

Ruta del archivo tal como aparece en el índice, por ejemplo "main / settings.md", para devolver un archivo. No distingue mayúsculas y minúsculas

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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

Respuesta correcta

Crear o actualizar un archivo de la ficha de marca

/api/v1/factory/brand-card

Crea o reemplaza por completo un archivo de la ficha de marca mediante su ruta. Se crean las carpetas que falten y se añade .md si no hay extensión. Para enlazar otro archivo, inserta un enlace Markdown [Nombre](brandcard://<id del índice>): se basa en el id, resiste cambios de nombre o ubicación y aumenta la prioridad del archivo de destino durante la generación. Conserva literalmente los enlaces brandcard:// existentes al editar. Encierra notas personales y opciones en un bloque ```private: no se enviarán a las IA.

Cuerpo de la solicitud

companyIdstringobligatorio

ID de la empresa

pathstringobligatorio

Ruta del archivo, con segmentos separados por "/", por ejemplo "products / pricing.md"

contentstringobligatorio

Markdown completo del archivo; reemplaza su contenido actual

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
  }
}

Respuesta correcta

Eliminar un archivo o carpeta de la ficha de marca

/api/v1/factory/brand-card

Elimina un archivo o carpeta de la ficha de marca por su ruta; las carpetas se eliminan en cascada con todo su contenido. No se pueden eliminar los archivos estructurales instruction.md, README.md y core: edítalos mediante POST. Los enlaces a un archivo eliminado quedan rotos: desaparecen de links en el índice y se devuelven con path=null al leer un archivo.

Parámetros de consulta

companyIdstring (uuid)obligatorio

ID de la empresa

pathstringobligatorio

Ruta del archivo o carpeta, tal como aparece en el índice

Respuestas

204

Eliminado correctamente

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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"
  }
}

Respuesta correcta

Saldo y gastos

Saldo FoxCoin e historial de operaciones

Saldo FoxCoin y tarifas

/api/v1/billing/balance

Saldo, movimientos y precios de las operaciones. El monedero se comparte en la cuenta: los miembros del equipo gastan del saldo del propietario. Los precios se ofrecen aquí para evitar codificarlos de forma fija en la integración.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Historial de transacciones

/api/v1/billing/transactions

Historial de operaciones del monedero. En los cargos por respuestas, query identifica la consulta facturada.

Parámetros de consulta

typestring

Filtrar por tipo de operación

ANSWER_CHARGEQUERY_GENERATIONBRAND_CARD_GENERATIONTASK_ENRICHMENTARTICLE_GENERATIONCONTENT_PLANTOPIC_SUGGESTIONFACT_CHECKTOPUPBONUSREFUNDMANUAL_ADJUSTMENTSUBSCRIPTION_CREDITAPI_CALL_FREE

fromstring (date-time)

Inicio del intervalo, fecha ISO incluida

tostring (date-time)

Fin del intervalo, fecha ISO incluida

limitinteger= 50

Tamaño de página

offsetinteger= 0

Desplazamiento

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Datos de referencia

Directorios y contexto de la clave

Listar modelos de IA

/api/v1/sources

Asistentes disponibles para las ejecuciones y asistentes utilizados por defecto. value es el valor aceptado por providers en POST /api/v1/queries/setup. Los nombres que no estén en la lista se descartan silenciosamente al poner la consulta en cola.

Parámetros de consulta

includeUnpollableboolean= false

Añadir claude, cola heredada que no se consulta en este sistema

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Obtener el contexto de la clave API

/api/v1/context

Punto de partida recomendado para integrar: cuenta de la clave, permisos, empresas y productos disponibles y empresa utilizada por defecto.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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

Respuesta correcta

Tráfico de IA

Visitas al sitio desde respuestas de IA (Yandex Metrica)

Tráfico de IA

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

Visitas al sitio desde respuestas de IA: visitas aportadas por cada IA y su evolución. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

timeRangestring

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

fromstring

Inicio del período, fecha ISO

tostring

Fin del período, fecha ISO

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Visitantes procedentes de modelos de IA

/api/v1/analytics/metrika/visitors

Visitas procedentes de IA y comportamiento en el sitio: profundidad de navegación, objetivos y visitas repetidas. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

timeRangestring

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

fromstring

Inicio del período, fecha ISO

tostring

Fin del período, fecha ISO

hasGoalsboolean

Solo visitas con objetivos cumplidos

includeSyntheticboolean

Incluir tráfico sintético

pvMininteger

Número mínimo de páginas vistas

pvMaxinteger

Número máximo de páginas vistas

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Embudo de tráfico de IA

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

Recorrido desde una visita procedente de una respuesta de IA hasta la acción objetivo. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

timeRangestring

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

fromstring

Inicio del período, fecha ISO

tostring

Fin del período, fecha ISO

hasGoalsboolean

Solo visitas con objetivos cumplidos

includeSyntheticboolean

Incluir tráfico sintético

pvMininteger

Número mínimo de páginas vistas

pvMaxinteger

Número máximo de páginas vistas

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Correlación entre menciones y tráfico

/api/v1/analytics/metrika/correlation

Compara la evolución de menciones de marca con las visitas reales para saber si una mayor visibilidad genera más tráfico. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

companyIdstring (uuid)

Empresa. Si se omite, se utiliza preferredCompanyId de la clave

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

timeRangestring

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

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Objetivos de Metrika

/api/v1/analytics/metrika/goals

Directorio de objetivos del contador: explica qué representa hasGoals en los demás métodos. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

includeInactiveboolean

Incluir objetivos inactivos

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Resumen del tráfico sintético

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

Proporción de visitas de bots y no orgánicas, para evitar que distorsionen las conclusiones sobre tráfico de IA. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

timeRangestring

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

fromstring

Inicio del período, fecha ISO

tostring

Fin del período, fecha ISO

filterstring

Filtro de clasificación

hasGoalsboolean

Solo visitas con objetivos cumplidos

pvMininteger

Número mínimo de páginas vistas

pvMaxinteger

Número máximo de páginas vistas

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Listar visitas sintéticas

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

Detalle paginado del resumen: visitas concretas con indicios de tráfico sintético. Ámbito de la cuenta: se ignora cualquier integrationId ajeno. Un resultado vacío suele indicar que Metrica no está conectado; comprueba /api/v1/integrations/metrika/status.

Parámetros de consulta

integrationIdstring (uuid)

Contador de Metrica. Si se omite, todos los contadores conectados a la cuenta

timeRangestring

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

fromstring

Inicio del período, fecha ISO

tostring

Fin del período, fecha ISO

filterstring

Filtro de clasificación

qstring

Búsqueda

qScopestring

Ámbito de búsqueda

hasRevenueboolean

Solo con ingresos

returningOnlyboolean

Solo visitantes recurrentes

pageinteger

Página

pageSizeinteger

Tamaño de página

sortBystring

Campo de ordenación

sortOrderstring

asc | desc

hasGoalsboolean

Solo visitas con objetivos cumplidos

pvMininteger

Número mínimo de páginas vistas

pvMaxinteger

Número máximo de páginas vistas

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Contadores conectados

/api/v1/integrations/metrika/list

Punto de partida para el tráfico de IA: devuelve integrationId para los demás métodos de esta sección.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Estado de la integración

/api/v1/integrations/metrika/status

Indica si Metrica está conectado, cuándo se sincronizó y si el acceso ha caducado. Permite explicar los resultados vacíos de los métodos de esta sección.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Commerce

Fichas de producto en las respuestas de IA

Analítica comercial

/api/v1/analytics/commerce

Fichas de producto que las IA muestran junto al texto de la respuesta. view=summary: proporción de respuestas con fichas y evolución por IA; sellers: principales vendedores y dominios; brands: fichas de nuestra marca frente a competidores; cards: lista paginada.

Parámetros de consulta

viewstring= summary

summary | sellers | brands | cards

summarysellersbrandscards

companyIdstring (uuid)

Empresa. Si se omite, se utiliza preferredCompanyId de la clave

productIdstring[]

Admite varios valores

timeRangestring

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

granularitystring

Desglose de la evolución temporal

tzstring

Zona horaria

labelIdstring[]

Grupos

labelSlugstring[]

Grupos por slug

labelFilterModestring

AND | OR

sourceIdstring[]

Fuentes

queryTypestring[]

Tipos de consulta

includeDemoboolean

Incluir datos de demostración

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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
}

Respuesta correcta

Productos en seguimiento

/api/v1/commerce/products

Catálogo utilizado para identificar los productos en las fichas de las respuestas. Sin él, la sección Comercio muestra vendedores y dominios, pero no distingue nuestros productos de los de competidores.

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Añadir un producto

/api/v1/commerce/products

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
}

Respuesta correcta

Monitorización

Ejecución periódica de consultas según una programación

Listar consultas en seguimiento

/api/v1/favorite-queries

Lista de consultas configuradas para ejecutarse periódicamente.

Parámetros de consulta

searchstring

Búsqueda por texto

activeboolean

Solo elementos activados

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

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
}

Respuesta correcta

Empezar a seguir una consulta

/api/v1/favorite-queries

POST /api/v1/queries consulta normalmente las IA UNA sola vez. El seguimiento periódico es una entidad independiente que se crea aquí. Crear el registro aún no inicia la ejecución: el calendario se define después mediante POST /api/v1/favorite-queries/{id}/assignments. Cada ejecución programada es de pago: 10 FoxCoin por respuesta de CADA IA. Un intervalo de 60 minutos con tres IA supone 72 respuestas al día. Si faltan fondos, las ejecuciones se pausan y no se reanudan automáticamente (POST /api/v1/queries/queue/resume).

Cuerpo de la solicitud

textstringobligatorio

typestringobligatorio

companyIdstring

productIdstring

languagestring= ru

regionstring= RU

isActiveboolean= true

tagsstring[]

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
}

Respuesta correcta

Obtener un registro de seguimiento

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

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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
}

Respuesta correcta

Modificar un registro de seguimiento

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

Texto, empresa, etiquetas e isActive. Para detener sin eliminar: isActive: false.

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
}

Respuesta correcta

Dejar de seguir una consulta

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

Elimina el registro y su calendario: no habrá nuevas ejecuciones. Se conservan las respuestas y menciones existentes, ya que pertenecen a la consulta y no a la suscripción.

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

204

Eliminado correctamente

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
}

Respuesta correcta

Obtener el calendario de consultas

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

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

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
}

Respuesta correcta

Establecer el calendario de consultas

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

Aquí comienza el seguimiento periódico: un registro sin calendario no ejecuta nada. Solo hay un calendario por registro; una nueva llamada lo reemplaza. Cada ejecución programada es de pago: 10 FoxCoin por respuesta de CADA IA. Un intervalo de 60 minutos con tres IA supone 72 respuestas al día. Si faltan fondos, las ejecuciones se pausan y no se reanudan automáticamente (POST /api/v1/queries/queue/resume).

Parámetros de consulta

idstring (uuid)obligatorio

Cuerpo de la solicitud

providersstring[]obligatorio

Lista: GET /api/v1/sources

frequencyMinutesintegerobligatorio

Intervalo entre ejecuciones

isEnabledboolean= true

Pausar sin eliminar la programación

timezonestring= Europe/Moscow

Zona horaria utilizada para daysOfWeek y hoursWindow

daysOfWeekinteger[]

1..7; vacío = todos los días

hoursWindowobject

Franja horaria fuera de la cual no se ejecutan consultas

modelobject

Correspondencia «IA → modelo»

Respuestas

200

Respuesta correcta

400application/json

Error de validación de los datos de entrada

VALIDATION_ERROR

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
}

Respuesta correcta

Ejecutar una consulta ahora

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

Ejecución inmediata, sin esperar ni modificar la programación. Se cobra según las tarifas habituales.

Parámetros de consulta

idstring (uuid)obligatorio

Respuestas

200

Respuesta correcta

401application/json

No autenticado: token ausente o no válido

UNAUTHORIZED

404application/json

Recurso no encontrado

NOT_FOUND

429application/json

Se ha superado el límite de solicitudes (IP: 120 req/min, por usuario: 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
}

Respuesta correcta

brandfound. API

Novedades de la versión 1.2

Para asistentes de IA

Autenticación

Espacios de trabajo

Listar espacios disponibles

Respuestas

Cambiar el espacio activo de la clave API

Cuerpo de la solicitud

Respuestas

Empresas

Listar empresas

Parámetros de consulta

Respuestas

Crear empresa

Cuerpo de la solicitud

Respuestas

Obtener empresa

Parámetros de consulta

Respuestas

Actualizar empresa

Parámetros de consulta

Cuerpo de la solicitud

Respuestas

Archivar empresa

Parámetros de consulta

Respuestas

Listar sectores

Respuestas

Productos

Listar productos

Parámetros de consulta

Respuestas

Crear producto

Cuerpo de la solicitud

Respuestas

Obtener producto

Parámetros de consulta

Respuestas

Actualizar producto

Parámetros de consulta

Cuerpo de la solicitud

Respuestas

Archivar producto

Parámetros de consulta

Respuestas

Competencia

Listar competidores

Parámetros de consulta

Respuestas

Crear competidor

Cuerpo de la solicitud

Respuestas

Obtener competidor

Parámetros de consulta

Respuestas

Actualizar competidor

Parámetros de consulta

Cuerpo de la solicitud

Respuestas

Archivar competidor

Parámetros de consulta

Respuestas

Palabras clave

Listar intenciones

Parámetros de consulta

Respuestas

Crear o reutilizar una intención

Cuerpo de la solicitud

Respuestas

Obtener una intención

Parámetros de consulta

Respuestas

Renombrar una intención

Parámetros de consulta

Cuerpo de la solicitud

Respuestas

Archivar o eliminar una intención

Parámetros de consulta

Respuestas