v1.2.0

brandfound. API

用于追踪 AI 助手 (ChatGPT、Gemini、Claude、Perplexity) 中品牌提及的 API。管理公司、产品、竞争对手、查询、提及与分析。

基础 URL

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

Playground

点击请求面板中的 ,打开交互式 Playground。选择 API Key,设置参数并直接从文档发送请求。

快速开始

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

成功响应

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

错误

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "未找到"
  }
}

请求限制

按 IP 地址120 / 分钟

按用户60 / 分钟

错误代码

401

UNAUTHORIZED授权无效

403

FORBIDDEN权限不足

404

NOT_FOUND资源未找到

400

VALIDATION_ERROR校验错误

429

RATE_LIMIT_EXCEEDED超过速率限制

500

INTERNAL_ERROR内部错误

1.2 版本新增内容

方法的公开地址未变更，保持向后兼容。

分析功能恢复正常

分析、链接和广告板块的方法因我方问题返回 500 错误。已修复，您无需任何操作。

可查看查询状态

查询列表新增 answersCount、providers 中的实际助手列表以及汇总状态 queue.status。此前 providers 始终为空。

轮询队列

queries/queue 和 queue/summary 显示当前轮询内容及其费用。因 FoxCoin 不足而停止的轮询需通过 queue/resume 恢复，不会自行重启。

余额与支出

billing/balance 返回余额和各项操作价格，billing/transactions 返回扣费记录及对应查询。

回答语言

language 字段现在决定回答语言。适用于 ChatGPT、Gemini、Perplexity 和 DeepSeek。

助手目录

sources 方法返回可用助手，并标记默认使用的助手。

监控

可为查询设置定期轮询和排期。此前仅能在界面中操作。

AI 流量

来自 AI 回答的网站访问、访客行为、漏斗和目标，数据来自 Yandex.Metrica。

电商

AI 回答中的商品卡片以及用于匹配的商品目录。

公司参数变为必填

links、links/filter-options、analytics/links/top-domains、analytics/competitors/preview 和 advertising 方法需要 companyId。此前不传会合并账户下所有公司。

身份验证

所有 API 请求均需授权。请在设置 → API Key中创建 API Key。Key 的前缀为 gfx_.

Bearer Token

工作空间

环境（工作区/团队）。一个 OAuth 令牌可访问用户有权限的所有环境：自有环境及 ACCEPTED TeamMember。活动环境存储在 ApiKey.activeAccountId，切换会持久保存，并从下一次请求起对使用同一密钥的全部 MCP 客户端生效。每次请求都会检查权限；成员资格失效后，中间件会自动回退到 OAuth 授权时的 accountId，不返回401。切换还会清空属于旧环境的 preferredCompanyId。

列出可访问的工作区

/api/v1/workspaces

返回当前用户可访问的所有工作区（accountId）：自有工作区和 ACCEPTED TeamMember。`isCurrent: true` 标记 API 密钥当前使用的环境，包括 activeAccountId 覆盖设置。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/workspaces

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

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

成功响应

切换 API 密钥的当前工作区

/api/v1/workspaces/switch

更新 ApiKey.activeAccountId，持久影响此密钥的所有后续请求，包括其他 MCP 客户端。accountId=null 清除覆盖设置，恢复令牌原有 accountId。属于旧环境的 preferredCompanyId 会设为 null。仅支持 API 密钥认证。

请求体

accountIdstring必填

要切换到的工作区 UUID。null 清除活动覆盖设置，恢复 OAuth 授权时的 accountId。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

403application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/workspaces/switch

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

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

成功响应

公司

管理公司

公司列表

/api/v1/companies

返回用户的公司列表及产品、竞争对手和关键词。

查询参数

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

sortBystring= createdAt

createdAtupdatedAtnamelastUsedAt

sortOrderstring= desc

排序顺序

ascdesc

searchstring

搜索文本，不区分大小写

categoryIdstring (uuid)

按类别筛选

countrystring

按国家筛选

createdAtFromstring (date-time)

创建日期范围开始（ISO 8601）

createdAtTostring (date-time)

创建日期范围结束（ISO 8601）

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/companies

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

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

成功响应

创建公司

/api/v1/companies

创建新公司，数量上限取决于套餐。

请求体

namestring必填

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2（"AE"）。接受并规范化 "russia" 等旧名称。推荐使用 regionTargets，此字段属于旧版。

synonymsstring[]

同义名称/别名（最多20个）

regionTargetsobject[]

监测国家和城市。代表完整状态，旧目标会重建。主目标决定自动生成查询的国家和语言。

defaultLanguageIdstring

生成查询的语言（GET /api/v1/geo/languages）。

defaultResponseLanguageIdstring

要求 AI 使用的回答语言。

defaultLocalestring

BCP-47，例如 "ar-AE"。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/companies

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

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

成功响应

获取公司

/api/v1/companies/{id}

返回完整公司资料，包括产品、竞争对手和关键词。

查询参数

idstring (uuid)必填

公司 ID

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/companies/{id}

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

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

成功响应

更新公司

/api/v1/companies/{id}

部分更新公司，仅传入要修改的字段。地区设置：regionTargets 指定监测国家和城市，主目标决定自动生成查询（POST /api/v1/queries/autogenerate）的国家与语言。countryId/cityId 来自 GET /api/v1/geo/countries 和 /api/v1/geo/cities；defaultLanguageId 来自 /api/v1/geo/languages。请求体中的 regionTargets 代表完整状态，旧目标会重新创建。 isAutoGenerationEnabled 已废弃，true 会被忽略。它曾用于已移除的调度器，该调度器会生成查询并立即发起付费执行。

查询参数

idstring (uuid)必填

公司 ID

请求体

namestring

descriptionstring

urlstring

categoryIdstring

countrystring

ISO 3166-1 alpha-2（"AE"）。接受并规范化 "russia" 等旧名称。推荐使用 regionTargets，此字段属于旧版。

synonymsstring[]

isAutoGenerationEnabledboolean

已废弃，true 会被忽略。它属于已移除的调度器，曾同时生成查询并启动付费执行。仅生成而不执行请用 POST /api/v1/queries/autogenerate。

regionTargetsobject[]

监测国家和城市。代表完整状态，旧目标会重建。主目标决定自动生成查询的国家和语言。

defaultLanguageIdstring

生成查询的语言（GET /api/v1/geo/languages）。

defaultResponseLanguageIdstring

要求 AI 使用的回答语言。

defaultLocalestring

BCP-47，例如 "ar-AE"。

autogenQueryTypesstring[]

自动生成的查询类型。默认 commercial、informational、comparative、reputational。移除 comparative 后不再生成“X vs Y”比较查询。

autogenQueriesPerRuninteger

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

PUT/api/v1/companies/{id}

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

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

成功响应

归档公司

/api/v1/companies/{id}

归档公司。数据保留，但公司不再显示在列表中。

查询参数

idstring (uuid)必填

公司 ID

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

DELETE/api/v1/companies/{id}

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

// No Content

删除成功

列出行业

/api/v1/companies/categories

创建或更新公司时允许使用的 categoryId 值。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/companies/categories

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

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

成功响应

产品

管理产品

产品列表

/api/v1/products

返回产品列表及其关联公司、关键词和竞争对手。

查询参数

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

排序顺序

ascdesc

companyIdstring (uuid)

按公司筛选

searchstring

搜索文本，不区分大小写

createdAtFromstring (date-time)

创建日期范围开始（ISO 8601）

createdAtTostring (date-time)

创建日期范围结束（ISO 8601）

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/products

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

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

成功响应

创建产品

/api/v1/products

创建属于某家公司的新产品。

请求体

namestring必填

companyIdstring必填

descriptionstring

urlstring

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/products

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

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

成功响应

获取产品

/api/v1/products/{id}

返回完整产品资料，包括关键词和竞争对手。

查询参数

idstring (uuid)必填

产品 ID

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/products/{id}

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

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

成功响应

更新产品

/api/v1/products/{id}

部分更新产品。

查询参数

idstring (uuid)必填

产品 ID

请求体

namestring

descriptionstring

urlstring

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

PUT/api/v1/products/{id}

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

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

成功响应

归档产品

/api/v1/products/{id}

归档产品。数据保留，但产品不再显示在列表中。

查询参数

idstring (uuid)必填

产品 ID

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

DELETE/api/v1/products/{id}

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

// No Content

删除成功

竞争对手

管理竞争对手

竞争对手列表

/api/v1/competitors

返回竞争对手列表及关联公司、产品和关键词。

查询参数

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

sortBystring= createdAt

createdAtupdatedAtname

sortOrderstring= desc

排序顺序

ascdesc

companyIdstring (uuid)

按公司筛选

productIdstring (uuid)

按产品筛选

searchstring

搜索文本，不区分大小写

createdAtFromstring (date-time)

创建日期范围开始（ISO 8601）

createdAtTostring (date-time)

创建日期范围结束（ISO 8601）

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/competitors

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

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

成功响应

创建竞争对手

/api/v1/competitors

创建竞争对手，可关联公司或具体产品。

请求体

namestring必填

companyIdstring必填

productIdstring

urlstring

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/competitors

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

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

成功响应

获取竞争对手

/api/v1/competitors/{id}

返回完整竞争对手资料及关键词。

查询参数

idstring (uuid)必填

竞争对手 ID

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/competitors/{id}

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

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

成功响应

更新竞争对手

/api/v1/competitors/{id}

更新竞争对手名称和/或 URL。

查询参数

idstring (uuid)必填

竞争对手 ID

请求体

namestring

urlstring

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

PUT/api/v1/competitors/{id}

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

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

成功响应

归档竞争对手

/api/v1/competitors/{id}

归档竞争对手。数据保留，但不再显示在列表中。

查询参数

idstring (uuid)必填

竞争对手 ID

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

DELETE/api/v1/competitors/{id}

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

// No Content

删除成功

关键词

意图（keywords）：创建、重命名、归档/删除、恢复，以及批量关联或解除与公司、产品、竞争对手的关系。

列出搜索意图

/api/v1/keywords

返回当前工作区的意图（keywords）。目标筛选只能指定 companyId、productId、competitorId 之一。state 控制归档筛选：active（默认）、archived 或 all。

查询参数

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

sortBystring= createdAt

createdAtname

sortOrderstring= desc

排序顺序

ascdesc

statestring= active

生命周期筛选：active（未归档，默认）、archived（仅归档）、all。

activearchivedall

searchstring

按 name 子字符串搜索，不区分大小写。

companyIdstring (uuid)

仅包含与此公司存在活动关联的意图。

productIdstring (uuid)

仅包含与此产品存在活动关联的意图。

competitorIdstring (uuid)

仅包含与此竞争对手存在活动关联的意图。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/keywords

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

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

成功响应

创建或复用搜索意图

/api/v1/keywords

按 (name, userId) 查找或创建。已有意图会复用，若已归档则恢复。可选 attach 必须恰好包含 { companyId | productId | competitorId } 之一，在同一事务中将意图关联到目标。

请求体

namestring必填

attachobject

关联/解除关联的目标，必须恰好包含其中一个字段。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords

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

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

成功响应

获取搜索意图

/api/v1/keywords/{id}

返回意图及其与公司、产品、竞争对手的活动关联。

查询参数

idstring (uuid)必填

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/keywords/{id}

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

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

成功响应

重命名搜索意图

/api/v1/keywords/{id}

仅 name 可编辑。已归档意图必须先 restore 才能重命名。

查询参数

idstring (uuid)必填

请求体

namestring必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

PUT/api/v1/keywords/{id}

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

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

成功响应

归档或删除搜索意图

/api/v1/keywords/{id}

默认归档意图及全部关联（软删除），可通过 POST /restore 恢复。?permanent=true 从数据库永久删除，要求意图已归档或具有归档关联。?dryRun=true 仅返回影响范围报告，不执行操作。

查询参数

idstring (uuid)必填

permanentboolean= false

true 表示从数据库永久删除，要求已归档。

dryRunboolean= false

true 仅返回报告，不产生副作用。

响应

204

删除成功

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

DELETE/api/v1/keywords/{id}

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

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

成功响应

恢复已归档的搜索意图

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

清除 keyword 及其归档关联的 archivedAt，但仅恢复父实体（company/product/competitor）仍存在的关联。指向已删除目标的关联保持归档。

查询参数

idstring (uuid)必填

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

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

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

成功响应

批量关联搜索意图

/api/v1/keywords/attach

对每个 name 按 (name, userId) 查找或创建，并确保存在活动目标关联。归档关联会恢复。目标必须恰好指定 companyId/productId/competitorId 之一。

请求体

targetobject必填

关联/解除关联的目标，必须恰好包含其中一个字段。

namesstring[]必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords/attach

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

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

成功响应

批量解除搜索意图关联

/api/v1/keywords/detach

归档活动 keyword↔target 关联。意图本身保留，仍可关联其他目标。目标必须恰好指定 companyId/productId/competitorId 之一。

请求体

targetobject必填

关联/解除关联的目标，必须恰好包含其中一个字段。

keywordIdsstring[]必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/keywords/detach

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

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

成功响应

查询

管理发送给 AI 助手的查询

查询列表

/api/v1/queries

返回发送给 AI 助手的查询列表及回答数量。支持按情感、聚类、地区、收藏、搜索范围和情感指标区间筛选。通过 queue.status 和 answersCount 判断执行状态。providers 显示实际调用的 AI 系统。具体执行详情见 GET /api/v1/queries/queue。

查询参数

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

sortBystring= createdAt

createdAttextupdatedAt

sortOrderstring= desc

排序顺序

ascdesc

companyIdstring (uuid)

按公司筛选

productIdstring (uuid)

按产品筛选

typestring

查询类型（general、comparative、negative 等）。支持数组：?type=comparative&type=neutral

originstring

查询来源。支持数组：?origin=manual&origin=auto

manualauto

hasAnswersstring

是否有回答

truefalse

languagestring

查询语言（ru、en 等）。支持数组：?language=ru&language=en

searchTextstring

按查询文本搜索

providerstring

按回答的 AI 提供商筛选

sourceIdstring

按回答来源 ID 筛选。支持数组：?sourceId=id1&sourceId=id2

labelSlugstring

按聚类/标签 slug 筛选

regionstring

查询地区。支持数组：?region=RU&region=US

isFavoritestring

仅收藏的查询

truefalse

sentimentstring

按回答中提及的情感筛选

positiveneutralnegative

searchFieldstring= query

searchText 的搜索范围：查询文本、回答或来源

queryanswersources

labelFilterModestring= or

聚类筛选逻辑：any（or）或 all（and）

orand

labelstring

聚类 slug。支持数组：?label=slug1&label=slug2

createdAtFromstring (date-time)

创建日期范围开始（ISO 8601）

createdAtTostring (date-time)

创建日期范围结束（ISO 8601）

showArchivedstring

显示已归档查询（默认 false）

truefalse

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/queries

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

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

成功响应

创建查询

/api/v1/queries

创建查询，默认立即加入执行队列。此操作收费：每个 AI 系统实际返回的每条回答扣除 FoxCoin，价格见 GET /api/v1/billing/balance。向5个系统查询即按5条回答计费。传入 dispatch: false 可仅创建查询，不消耗 FoxCoin。通过 providers 选择 AI 系统，slug 见 GET /api/v1/sources。省略时使用账户默认值；未配置账户仅使用 ChatGPT。批量创建并分配聚类请用 POST /api/v1/queries/setup。地区通过 region（ISO 3166-1 alpha-2）和 language 设置；省略 region 时使用公司国家。geoOverride 和 resolvedGeoSnapshot 是服务器为含地理目标的聚类查询计算的只读快照，POST 不接受它们。请求体严格校验，未知字段返回400。查看响应中的 dispatch 判断入队结果：dispatched=false 且 error 非空表示查询已创建，但执行未启动。

请求体

textstring必填

companyIdstring必填

productIdstring

typestring= neutral

接受旧值：negative → reputational，general → neutral。

neutralcommercialinformationalcomparativereputationalbranded

languagestring= ru

回答语言的 ISO 639-1 代码（ru、en、ar、hi、vi、ms 等）。提示词会通过目录中的语言名称明确要求使用该语言回答。默认 ru。

regionstring

查询国家，ISO 3166-1 alpha-2（AE、SA、RU）。省略时采用公司主 regionTarget，再回退到 RU。接受并规范化 "russia" 等旧名称。不会对结果进行地理定向，仅用于筛选和分析。

providersstring[]

要调用的 AI 系统。省略时使用账户默认设置；未配置账户仅使用 ChatGPT。

dispatchboolean= true

false 表示仅创建查询，不加入付费执行队列。

labelsstring[]

聚类名称，按 slug 创建或复用。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

402application/json

FoxCoin 余额不足

HTTP_402

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/queries

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

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

成功响应

获取查询

/api/v1/queries/{id}

返回查询、AI 助手回答及识别到的提及。

查询参数

idstring (uuid)必填

查询 ID

includeAnswersstring= true

包含回答及提及（默认 true）

truefalse

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/queries/{id}

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

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

成功响应

归档查询

/api/v1/queries/{id}

将查询归档。数据保留，可恢复。

查询参数

idstring (uuid)必填

查询 ID

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

DELETE/api/v1/queries/{id}

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

// No Content

删除成功

修改查询

/api/v1/queries/{id}

修改查询文本、类型、语言、地区、产品、收藏状态和聚类。修改文本不会重新调用 AI，已有回答仍关联该查询。如需重新执行，请创建新查询。请求体严格校验：未知字段→400。

查询参数

idstring (uuid)必填

请求体

textstring

typestring

neutralcommercialinformationalcomparativereputationalbranded

languagestring

regionstring

ISO 3166-1 alpha-2.

productIdstring

null 表示解除产品关联。

isFavoriteboolean

labelsstring[]

完整聚类列表，关联会重建。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

PATCH/api/v1/queries/{id}

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

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

成功响应

列出排队中的任务

/api/v1/queries/queue

查询执行状态，每个查询与 AI 系统组合对应一次执行。可区分仍在执行、失败或因余额不足暂停，仅凭回答数量无法判断。

查询参数

statusstring= queued,onHold,failed

逗号分隔的状态组，默认包含全部三组。

companyIdstring (uuid)

限定到某家公司，省略时包含账户全部公司。

queryIdstring (uuid)

单个查询的执行记录

providerstring

按 AI 系统筛选

chatgptgeminiperplexitygrokdeepseekgigachatyandex_alicealice_chatgoogle_ai_mode

includeArchivedboolean= false

包含已归档查询的执行记录

limitinteger= 50

每页数量

offsetinteger= 0

偏移量

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/queries/queue

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

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

成功响应

队列概况与费用预估

/api/v1/queries/queue/summary

一次请求获取执行计数、当前队列费用和 FoxCoin 余额。queuedTotal>0 表示查询仍在执行。onHold>0 表示余额不足，即使充值也不会自动恢复这些执行。

查询参数

companyIdstring (uuid)

限定到某家公司

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/queries/queue/summary

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

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

成功响应

使用所选 AI 模型批量创建查询

/api/v1/queries/setup

在同一事务中创建分组和查询，并立即加入查询队列。使用 providers 显式选择 AI 模型；省略时使用账户默认设置。创建单条查询可使用 POST /api/v1/queries，该接口同样支持 providers。收费：每个 AI 模型返回的每条回答均消耗 FoxCoin（参见 GET /api/v1/billing/balance）。每次调用最多 500 条查询。

请求体

companyIdstring

省略时使用密钥的 preferredCompanyId，参见 GET /api/v1/context。

clusterIdstring

用于继承地区设置的已有聚类，适用于 clusters 中未指定自身 clusterId 的所有项。

providersstring[]

要查询的 AI 模型（标识取自 GET /api/v1/sources）。省略时使用账户默认模型；未配置的账户使用 ChatGPT。POST /api/v1/queries 同样支持通过 providers 选择模型。

clustersobject[]必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

402application/json

FoxCoin 余额不足

HTTP_402

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/setup

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

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

成功响应

将任务重新加入队列

/api/v1/queries/queue/resume

恢复已暂停的执行。 **用途：**FoxCoin 不足时状态变为 ON_HOLD_NO_FUNDS。工作进程不会领取这些执行，充值也不会自动恢复；45天后调度器会将其设为 CANCELLED。因此必须显式调用本方法恢复。 **触发方式：**余额不足时创建查询。入队和执行时都会检查余额，因此同一查询可能部分完成、部分暂停。可通过 `GET /api/v1/queries/queue/summary` 的 `onHold`，或查询的 queue.status=`on_hold_no_funds` 检查。 **402 并非永久拒绝：**余额不足以覆盖整个批次。请充值，或使用 `force: true` 重试；余额足够的执行继续，其余再次暂停。

请求体

runIdsstring[]

按执行 ID 精确选择

scopestring

所有已暂停执行

onHold

companyIdstring

将 scope 限定到某家公司

forceboolean= false

即使余额不足以覆盖整个批次也恢复

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

402application/json

FoxCoin 不足以覆盖整个批次

HTTP_402

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/queue/resume

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

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

成功响应

取消排队任务

/api/v1/queries/queue/cancel

取消尚未开始处理的执行，包括等待中（PENDING、RETRYING）和暂停状态。RUNNING 永远不会被修改，因为工作进程已在处理，取消可能引发竞态。 **适用场景：**在扣费前停止多余批量执行，或清理不准备付费的暂停任务。仅在收到回答后扣费，所以取消的执行不收费。取消可恢复：通过 `POST /api/v1/queries/queue/resume` 传入对应 `runId`，重新加入队列。

请求体

runIdsstring[]

queryIdsstring[]

这些查询的所有可取消执行

scopestring

onHold：仅暂停；queued：仅活动队列

onHoldqueued

companyIdstring

将 scope 限定到某家公司

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/queue/cancel

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

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

成功响应

查询自动生成

自动选择语义内容：生成查询草稿并批准。生成（每条查询1 FoxCoin）与 AI 执行（每条回答10 FoxCoin）是两个独立步骤。

生成查询建议而不调用 AI 模型

/api/v1/queries/autogenerate

服务自动选择查询并保存为草稿，此时不会向 AI 执行查询。本接口替代 isAutoGenerationEnabled，旧标志会同时触发生成和付费执行，无法分离。现在仅在 POST /api/v1/query-drafts/approve 时开始执行。费用：每条实际交付的生成草稿1 FoxCoin。执行另计，每条回答10 FoxCoin（查询 × AI 系统）。语言和国家：省略 language/region 时采用公司地区设置（regionTargets、PUT /api/v1/companies/{id}），再回退到 ru/RU。多国监测使用 targets，每国一个任务，默认采用官方语言，如 AE→ar、IN→hi。类型：省略 types 时使用 Company.autogenQueryTypes，默认 commercial、informational、comparative、reputational。仅当列表包含 comparative 且公司已设置竞争对手时，才生成“X vs Y”比较查询。默认立即返回202并在后台生成，通过相同地址的 GET 和 clientToken 查询进度。简写形式 region/language/city/includeDistricts 与 targets 互斥，同时传入返回400，因为 targets 外的城市无法对应到特定国家。

请求体

companyIdstring

省略时使用密钥的 preferredCompanyId。

productIdstring

countinteger必填

每个目标生成的查询数量，每条1 FoxCoin。

typesstring[]

生成的查询类型，count 平均分配。省略时使用 Company.autogenQueryTypes，默认包含 comparative。

clustersstring[]

用于归类查询的主题。

userWishesstring

namestring

任务名称，在界面和 GET 中可见。

languagestring

ISO 639-1。省略时使用公司语言，仅可在无 targets 时使用。

regionstring

ISO 3166-1 alpha-2。省略时采用公司 regionTargets 主国家，再回退到 RU。接受 "russia" 等旧名称，仅可在无 targets 时使用。

citystring

仅可在无 targets 时使用。

includeDistrictsboolean

仅可在无 targets 时使用。

targetsobject[]

多国监测：每国一个任务，费用为所有目标 count 之和。与简写形式互斥：targets 外同时传 region/language/city/includeDistricts 返回400；targets 内每个国家可设置自己的城市和语言。

waitboolean= false

true 表示等待生成完成，仅适用于小批次；100条以上可能耗时数分钟。

clientTokenstring

自定义任务标识，用于后续查询进度。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

402application/json

FoxCoin 不足，错误响应体包含 required 和 balance。

HTTP_402

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

503application/json

服务器尚未配置自动生成。

HTTP_503

POST/api/v1/queries/autogenerate

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

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

成功响应

查询生成任务状态

/api/v1/queries/autogenerate

查看 POST /api/v1/queries/autogenerate 启动的任务进度。轮询至 status=OK，再通过 GET /api/v1/query-drafts 获取草稿。仍在运行（RUNNING）的任务草稿暂不允许批准，以免仅批准半个批次。

查询参数

runIdstring (uuid)

指定任务。

clientTokenstring

通过 POST 响应中的客户端标识查找任务。

limitinteger= 20

返回最近任务的数量。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/queries/autogenerate

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

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

成功响应

停止查询生成任务

/api/v1/queries/autogenerate/cancel

真正取消：尚未开始的批次不再执行，仅对已交付草稿收费。执行状态变为 CANCELLED，已有草稿保留且仍可批准。

请求体

runIdstring必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/queries/autogenerate/cancel

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

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

成功响应

列出查询草稿

/api/v1/query-drafts

草稿存储免费，不会执行查询。仅通过 POST /api/v1/query-drafts/approve 才转为正式查询。

查询参数

statusstring

PENDING 表示等待决定，默认全部。

PENDINGAPPROVEDREJECTEDEXPIRED

companyIdstring (uuid)

按公司筛选。

typestring

按查询类型筛选。

neutralcommercialinformationalcomparativereputationalbranded

pageinteger= 1

页码，从1开始。

limitinteger= 50

每页数量。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/query-drafts

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

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

成功响应

批准草稿并执行查询

/api/v1/query-drafts/approve

付费步骤：批准后的草稿转为查询，并发送给选定 AI 系统，每条回答10 FoxCoin（查询 × 系统）。50条草稿 ×3个系统 =150条回答 =1500 FoxCoin。请先用 dryRun:true 调用，向用户展示费用估算。幂等：重复提交相同 draftIds 不会创建重复查询或重复执行。仍在生成的任务草稿会跳过并记为 skippedRunning，请等待 status=OK。

请求体

draftIdsstring[]必填

providersstring[]必填

要执行查询的 AI 系统，每增加一个都会相应增加费用。

dryRunboolean

true 仅估算，不创建任何内容，也不扣费。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

402application/json

FoxCoin 不足，错误响应体包含 required 和 balance。

HTTP_402

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/query-drafts/approve

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

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

成功响应

拒绝草稿

/api/v1/query-drafts/reject

软拒绝：草稿以 REJECTED 状态保留，用于计费审计，不执行查询。生成费用不退还，因为查询已经生成。

请求体

draftIdsstring[]必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/query-drafts/reject

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

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

成功响应

AI 回答

批量获取 AI 回答：链接、提及和情感。

批量获取 AI 回答

/api/v1/answers

替代逐条循环调用 GET /api/v1/queries/{id}：每页最多200条回答，含链接、提及和情感。 links 是任意 AI 系统解析后的引用。不要与原始 answer.sources 混淆：后者为抓取器载荷，仅 Alice Search 填充，并非引用列表。 brandDomainCited 表示是否引用公司网站域名。提及字段：position 是回答文本中的字符偏移。数组按其排序，因此品牌第几次出现应看数组中的排名，而不是 position 值。sentiment（1/0/-1）和 sentimentScore（-1..1）取自整条回答的情感，因此同一回答的全部提及值一致。尚未分析时 sentimentScore=null。isOurs=false 表示竞争对手。数组参数重复传入：?companyId=a&companyId=b。

查询参数

companyIdstring[]

公司，可多个。

productIdstring[]

产品，可多个。

queryIdstring[]

仅这些查询的回答。

sourceIdstring[]

按 ID 指定 AI 系统（GET /api/v1/sources）。

providerstring[]

按 slug 指定 AI 系统。

typestring[]

回答所属查询的类型。

labelstring[]

聚类 slug。

regionstring[]

查询地区，ISO 3166-1 alpha-2。也支持旧版名称。

languagestring[]

查询语言。

createdAtFromstring (date-time)

回答创建日期起始（ISO 8601）。

createdAtTostring (date-time)

回答创建日期截止（ISO 8601）。

hasLinksboolean

true：仅含链接的回答；false：仅不含链接的回答。

mentionsOursboolean

true：仅提及公司品牌的回答。

showArchivedboolean= false

true：包含已归档查询的回答。

includestring= content,tonality

要包含的内容，逗号分隔：content、links、mentions、tonality。

limitinteger= 50

每页数量。

offsetinteger= 0

偏移量。

sortBystring= createdAt

排序字段。

createdAtdate

sortOrderstring= desc

排序方向。

ascdesc

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/answers

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

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

成功响应

地理

国家、地区、城市和语言目录。

列出国家

/api/v1/geo/countries

目录 ID 用于公司和聚类的 regionTargets、defaultLanguageId；iso2 用于查询及自动生成的 region 字段。

查询参数

qstring

按名称搜索。

continentstring

按大洲筛选。

EUROPEASIANORTH_AMERICASOUTH_AMERICAAFRICAOCEANIAANTARCTICA

limitinteger= 250

最大记录数。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/countries

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

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

成功响应

列出国家的地区

/api/v1/geo/regions

某国家的地区（州、省）。必须指定 countryId 或 countryIso2 之一。

查询参数

countryIso2string

两字母国家代码。

countryIdstring (uuid)

国家 UUID。

qstring

按名称搜索。

limitinteger= 100

最大记录数。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/regions

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

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

成功响应

列出国家的城市

/api/v1/geo/cities

某国家的城市，必须指定 countryId 或 countryIso2 之一。此处的 cityId 用于公司 regionTargets 和聚类 targets。

查询参数

countryIso2string

两字母国家代码。

countryIdstring (uuid)

国家 UUID。

regionIdstring (uuid)

地区 UUID。

qstring

按名称搜索。

limitinteger= 50

最大记录数。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/cities

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

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

成功响应

列出语言

/api/v1/geo/languages

目录 ID 用于公司和聚类的 regionTargets、defaultLanguageId；iso2 用于查询及自动生成的 region 字段。

查询参数

qstring

按名称或代码搜索。

limitinteger= 200

最大记录数。

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

GET/api/v1/geo/languages

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

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

成功响应

查询聚类

查询标签/聚类：列出（可按公司筛选），并创建包含地区设置的聚类。

列出查询分组

/api/v1/query-labels

返回当前工作区的查询标签/聚类及各自查询数。companyId 仅返回包含该公司查询的聚类，queryCount 也仅统计该公司。lite=true 返回精简结构 { items: [{ id, name, slug, queryCount }] }，不含统计和 sampleQueries。

查询参数

companyIdstring (uuid)

按公司筛选：仅包含该公司查询的聚类，queryCount 仅统计该公司查询。

litestring

lite=true 返回精简结构 { items: [{ id, name, slug, queryCount }] }，不含统计。

truefalse

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

qstring

按标签名子字符串搜索，不区分大小写。

sortstring= queryCount:desc

排序格式为 field:direction。

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

hasQueriesstring

with：仅有查询的聚类；without：仅空聚类。

withwithout

minCountinteger

聚类中的最少查询数。

maxCountinteger

聚类中的最多查询数。

createdFromstring (date-time)

创建日期不早于指定日期的标签。

createdTostring (date-time)

创建日期不晚于指定日期的标签。

lastUsedFromstring (date-time)

lastUsedAt 不早于指定日期的标签。

lastUsedTostring (date-time)

lastUsedAt 不晚于指定日期的标签。

includestring

include=targets 同时加载聚类地理目标（country/city）。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/query-labels

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

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

成功响应

创建或更新区域查询分组

/api/v1/query-labels

按 (slug, userId) 查找或创建。同 slug 聚类已存在时更新名称及地区设置，并重建 targets。接受可选 companyId/productId，但目前不持久保存到 QueryLabel。

请求体

namestring必填

slugstring

descriptionstring

companyIdstring

productIdstring

defaultLanguageIdstring

defaultLocalestring

defaultResponseLanguageIdstring

geoScopestring

GLOBALCOUNTRYREGIONCITY

injectLocationModestring

NONEAPPEND_PARENSAPPEND_NATURALPREPENDAI_REWRITE

autogenStrategystring

SHAREDPER_TARGETPER_TARGET_LOCALIZED

targetsobject[]

响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

409application/json

冲突：资源已存在。

CONFLICT

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/query-labels

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

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "输入数据校验错误"
  }
}

输入数据校验错误

提及

查看品牌提及

提及列表

/api/v1/mentions

返回 AI 回答中的品牌提及及完整上下文。

查询参数

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

sortBystring= createdAt

createdAtpositionsentiment

sortOrderstring= desc

排序顺序

ascdesc

timeRangestring

时间范围

24h7d30d90dall

createdAtFromstring (date-time)

创建日期范围开始（ISO 8601）

createdAtTostring (date-time)

创建日期范围结束（ISO 8601）

companyIdstring (uuid)

按公司筛选

productIdstring (uuid)

按产品筛选

competitorIdstring (uuid)

按竞争对手筛选

answerIdstring (uuid)

按具体回答筛选

typestring

提及类型

companyproductkeywordcompetitor

sentimentstring

情感

positiveneutralnegative

searchstring

搜索文本，不区分大小写

isOursstring

仅自身品牌（true）或仅竞争对手（false）

truefalse

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/mentions

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

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

成功响应

分析

分析：竞争对手、情感、链接和品牌可见度

竞争对手分析

/api/v1/analytics/competitors

根据 AI 提及全面比较您的公司与竞争对手。支持按聚类 slug、AI 提供商和时间段筛选。

查询参数

timeRangestring= 30d

时间范围

24h7d30dall

fromstring (date-time)

自定义时间范围开始（ISO 8601）

tostring (date-time)

自定义时间范围结束（ISO 8601）

companyIdstring (uuid)

公司 ID

productIdstring (uuid)

产品 ID

sourceIdstring[]

AI 提供商 ID

labelIdstring[]

聚类/标签 ID

labelSlugstring

聚类 slug。数组：?labelSlug=slug1&labelSlug=slug2

labelFilterModestring= or

标签筛选模式

orand

includeDemostring

包含演示数据

truefalse

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/competitors

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

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

成功响应

提及预览

/api/v1/analytics/competitors/preview

返回具体 AI 回答及提及以供详细分析。支持聚类筛选、演示数据、自定义时间段和标签筛选模式。必须指定 companyId，避免合并账户内所有公司数据。省略时使用密钥的 preferredCompanyId，参见 GET /api/v1/context。

查询参数

sidestring必填

所属方：自身公司或竞争对手

ourcompetitor

competitorNamestring

竞争对手名称（side=competitor 时）

mentionTypestring= both

提及类型

brandlinkboth

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

sourceIdstring[]

labelIdstring[]

includeMentionsstring

响应中包含提及

truefalse

includeDemostring

包含演示数据

truefalse

labelFilterModestring= or

聚类筛选逻辑

orand

fromstring (date-time)

时间段开始（ISO 8601）

tostring (date-time)

时间段结束（ISO 8601）

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/competitors/preview

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

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

成功响应

语气分析

/api/v1/analytics/tonality

完整分析 AI 回答情感：质量指标、时间趋势、问题回答和最佳回答。

查询参数

timeRangestring= 30d

24h7d30d90d

companyIdstring (uuid)

productIdstring (uuid)

queryTypestring

查询类型

neutralcomparativenegative

sentimentstring

按情感筛选

positiveneutralnegative

sourceIdstring[]

AI 提供商

labelSlugstring[]

按 slug 指定聚类/标签

labelFilterModestring= or

orand

fromstring (date-time)

tostring (date-time)

includeDemostring

truefalse

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/tonality

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

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

成功响应

链接分析

/api/v1/analytics/links

分析 AI 回答中的链接：热门域名、按提供商的引用和时间趋势。支持按情感、聚类、查询类型、Impact/Overall Score 阈值及自定义时间段筛选。必须指定 companyId，避免合并账户内所有公司数据。省略时使用密钥的 preferredCompanyId，参见 GET /api/v1/context。

查询参数

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

labelSlugstring[]

sortDomainsBystring

域名排序

sentimentstring

按情感筛选

positiveneutralnegative

minImpactnumber

Impact Score 最低阈值

minOverallnumber

Overall Score 最低阈值

presetstring

筛选预设

queryTypestring

查询类型

neutralnegativecomparative

labelstring

聚类 slug

labelFilterModestring= or

筛选逻辑

orand

fromstring (date-time)

时间段开始

tostring (date-time)

时间段结束

chartOnlystring

仅图表数据

truefalse

citationModestring

引用模式

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/links

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

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

成功响应

品牌可见度

/api/v1/analytics/brand-visibility

品牌与竞争对手可见度的时间趋势，可配置时间粒度。支持按聚类 ID/slug、AI 提供商及筛选逻辑过滤。

查询参数

granularitystring= day

时间轴粒度

dayweekmonth

timeRangestring

24h7d30dall

companyIdstring (uuid)

productIdstring (uuid)

includeDemostring

truefalse

fromstring (date-time)

tostring (date-time)

labelIdstring

聚类 ID。数组：?labelId=id1&labelId=id2

labelSlugstring

聚类 slug

labelFilterModestring= or

筛选逻辑

orand

sourceIdstring

AI 来源 ID

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/brand-visibility

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

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

成功响应

引用趋势

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

按天比较自身与竞争对手被引用的回答占比。基于每日汇总，仅支持总体引用模式，汇总不区分 URL 引用和域名引用。

查询参数

companyIdstring (uuid)

公司，省略时使用密钥的 preferredCompanyId。

productIdstring

产品

timeRangestring

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

granularitystring

趋势分组维度

tzstring

时区

sourceIdstring[]

来源

labelSlugstring[]

聚类

labelFilterModestring

AND | OR

includeDemoboolean

包含演示数据

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

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

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

{
  "success": true
}

成功响应

用于筛选的公司和产品

/api/v1/analytics/companies-products

返回账户公司及产品，为“公司→产品”选择器提供数据。此处 companyId 非必填，省略时返回所有公司，这正是接口用途。

查询参数

companyIdstring (uuid)

限定到某家公司

includeDemoboolean

包含演示数据

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/companies-products

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

{
  "success": true
}

成功响应

链接

AI 回答中的域名和链接

域名与链接

/api/v1/links

AI 回答中的域名和链接双层表格，支持排序和筛选。必须指定 companyId，避免合并账户内所有公司数据。省略时使用密钥的 preferredCompanyId，参见 GET /api/v1/context。

查询参数

pageinteger= 1

页码

pageSizeinteger= 50

每页数量

sortBystring= lastMentioned

lastMentionedmentionCountanswerCountourMentionCountcompetitorMentionCountdomaintrustRankdomainLinks

sortDirstring= desc

ascdesc

searchstring

搜索文本，不区分大小写

searchFieldstring

搜索字段

domainurltitle

timeRangestring

24h7d30d

fromstring (date-time)

tostring (date-time)

companyIdstring (uuid)

productIdstring (uuid)

sentimentstring

positiveneutralnegative

queryTypestring

neutralnegativecomparative

providerstring[]

AI 提供商

activestring

仅活动链接

truefalse

domainsOnlystring

仅域名，不含子链接

truefalse

domainstring

指定域名的子链接

labelstring[]

聚类/标签

includeDemostring

truefalse

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/links

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

{
  "success": true,
  "data": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 120,
    "hasMore": true,
    "rows": [
      {
        "domain": "samsung.com",
        "trustRank": 95,
        "mentionCount": 45,
        "answerCount": 30,
        "ourMentionCount": 40,
        "competitorMentionCount": 5,
        "lastMentioned": "2026-04-05T12:00:00.000Z",
        "domainLinks": 8
      }
    ]
  }
}

成功响应

筛选选项

/api/v1/links/filter-options

返回链接表格的可用筛选值：提供商和标签。必须指定 companyId，避免合并账户内所有公司数据。省略时使用密钥的 preferredCompanyId，参见 GET /api/v1/context。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/links/filter-options

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

{
  "success": true,
  "data": {
    "providers": [
      {
        "value": "chatgpt",
        "label": "ChatGPT"
      },
      {
        "value": "gemini",
        "label": "Gemini"
      },
      {
        "value": "claude",
        "label": "Claude"
      },
      {
        "value": "perplexity",
        "label": "Perplexity"
      }
    ],
    "labels": [
      {
        "value": "brand-queries",
        "label": "Брендовые запросы"
      }
    ]
  }
}

成功响应

{
  "success": true,
  "data": {
    "summary": {
      "promoCount": 25,
      "ourPromos": 8,
      "competitorPromos": 17,
      "uniqueDomains": 12
    },
    "topDomains": [
      {
        "domain": "samsung.com",
        "count": 5,
        "isOurs": true
      },
      {
        "domain": "apple.com",
        "count": 8,
        "isOurs": false
      }
    ],
    "timeseries": [
      {
        "date": "2026-04-01",
        "count": 3
      }
    ]
  }
}

成功响应

广告模块预览

/api/v1/advertising/preview

/api/v1/advertising 汇总的详细数据：哪些推广出现在什么回答中。

查询参数

domainstring必填

推广域名，必填，否则返回400。

companyIdstring (uuid)

公司，省略时使用密钥的 preferredCompanyId。

productIdstring

产品

promoTypestring

ours | competitor | other

ourscompetitorother

timeRangestring

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

labelstring[]

聚类

labelFilterModestring

AND | OR

limitinteger= 20

1..50

offsetinteger= 0

偏移量

includeDemoboolean

包含演示数据

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/advertising/preview

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

{
  "success": true
}

成功响应

内容工厂

内容工厂：任务、标签、信息补充、计划与文章生成，以及洞察检测

任务列表

/api/v1/factory/tasks

返回内容工厂任务列表，支持筛选、分页和排序。

查询参数

companyIdstring (uuid)

按公司筛选

statusstring[]

按状态筛选，可多选：?status=TODO&status=IN_PROGRESS

typestring[]

按任务类型筛选，可多选

prioritystring[]

按优先级筛选，可多选

searchstring

按任务名称和描述搜索

tagIdstring (uuid)

按标签筛选

aiGeneratedboolean

仅 AI 生成的任务

sortBystring= createdAt

createdAtupdatedAtprioritystatusposition

sortOrderstring= desc

排序顺序

ascdesc

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/factory/tasks

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

{
  "success": true,
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "title": "Написать FAQ по Galaxy S25",
      "status": "TODO",
      "type": "CREATE_FAQ",
      "priority": "HIGH",
      "position": 1,
      "aiGenerated": true,
      "aiReasoning": "Обнаружен content gap по FAQ-запросам",
      "aiConfidence": 0.87,
      "description": "Создать FAQ на основе частых вопросов пользователей",
      "targetKeywords": [
        "galaxy s25 faq",
        "samsung s25 характеристики"
      ],
      "targetProviders": [
        "chatgpt",
        "gemini"
      ],
      "companyId": "clx1abc2d0001abcdef123456",
      "companyName": "Samsung",
      "companyFavicon": "https://samsung.com/favicon.ico",
      "dueDate": "2026-04-20T00:00:00.000Z",
      "tags": [
        {
          "id": "tag-001",
          "name": "FAQ",
          "color": "#6366f1",
          "icon": null,
          "isSystem": false,
          "position": 0
        }
      ],
      "metadata": {},
      "createdAt": "2026-04-07T12:00:00.000Z",
      "updatedAt": "2026-04-07T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

成功响应

创建任务

/api/v1/factory/tasks

创建内容工厂新任务。

请求体

titlestring必填

任务名称

companyIdstring必填

公司 ID

typestring必填

任务类型

NEW_ARTICLEOPTIMIZE_PAGECREATE_FAQCOMPARISONGUIDECASE_STUDY

prioritystring= MEDIUM

优先级

CRITICALHIGHMEDIUMLOW

descriptionstring

任务描述

targetKeywordsstring[]

目标关键词（最多20个）

targetProvidersstring[]

目标 AI 提供商

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tasks

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Написать FAQ по Galaxy S25",
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "CREATE_FAQ",
  "priority": "HIGH",
  "description": "Создать FAQ на основе частых вопросов пользователей",
  "targetKeywords": [
    "galaxy s25 faq",
    "samsung s25 характеристики"
  ],
  "targetProviders": [
    "chatgpt",
    "gemini"
  ]
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

成功响应

获取任务

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

返回内容工厂任务的完整资料。

查询参数

idstring (uuid)必填

任务 ID

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

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

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

{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

成功响应

更新任务

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

部分更新内容工厂任务。

查询参数

idstring (uuid)必填

任务 ID

请求体

statusstring

IDEABACKLOGTODOIN_PROGRESSREVIEWDONEDISMISSED

prioritystring

CRITICALHIGHMEDIUMLOW

titlestring

descriptionstring

tagIdsstring[]

要关联的标签 ID 数组

targetKeywordsstring[]

targetProvidersstring[]

dueDatestring

任务截止日期

metadataobject

自定义任务元数据

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

curl -X PATCH "https://app.brandfound.ai/api/v1/factory/tasks/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "tagIds": [
    "tag-001",
    "tag-002"
  ]
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "title": "example_title",
    "status": "IDEA",
    "type": "NEW_ARTICLE",
    "priority": "CRITICAL",
    "position": 1,
    "aiGenerated": true,
    "aiReasoning": "example_aiReasoning",
    "aiConfidence": 1,
    "description": "example_description",
    "targetKeywords": [
      "example"
    ],
    "targetProviders": [
      "example"
    ],
    "companyId": "example_companyId",
    "companyName": "example_companyName",
    "companyFavicon": "example_companyFavicon",
    "dueDate": "2026-01-15T12:00:00Z",
    "tags": [
      {
        "id": "example_id",
        "name": "example_name",
        "color": "example_color",
        "icon": "example_icon",
        "isSystem": true,
        "position": 1,
        "taskCount": 1
      }
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:00:00Z"
  }
}

成功响应

归档任务

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

归档任务。数据保留，状态变为 DISMISSED。

查询参数

idstring (uuid)必填

任务 ID

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

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

// No Content

删除成功

丰富任务

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

在来源库中执行 RAG 检索、竞争分析并提供 AI 建议。

查询参数

idstring (uuid)必填

任务 ID

请求体

topicstring必填

需要补充信息的主题

descriptionstring

补充描述

keywordsstring[]

RAG 检索关键词

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/enrich" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Samsung Galaxy S25 FAQ",
  "description": "Часто задаваемые вопросы о Galaxy S25",
  "keywords": [
    "galaxy s25",
    "samsung",
    "характеристики"
  ]
}'

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

成功响应

生成计划

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

根据补充后的资料生成文章计划：结构、标题、关键观点和表达语气。

查询参数

idstring (uuid)必填

任务 ID

请求体

promptstring

生成计划的补充指令

topicIdstring

选定主题的 ID（来自 suggest topics）

topicTitlestring

主题名称

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/plan" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Сфокусируйся на сравнении с iPhone 16",
  "topicId": "topic-001",
  "topicTitle": "Samsung Galaxy S25 vs iPhone 16: полное сравнение"
}'

{
  "success": true,
  "data": {
    "plan": {},
    "usage": {
      "inputTokens": 1,
      "outputTokens": 1
    }
  }
}

成功响应

生成文章

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

根据计划生成文章，使用 SSE 流式输出。Content-Type: text/event-stream。

查询参数

idstring (uuid)必填

任务 ID

请求体

planIdstring

用于生成文章的计划 ID

articleLengthstring= medium

文章长度：short（约1000词）、medium（约2000词）、long（约3500词）

shortmediumlong

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

curl -X POST "https://app.brandfound.ai/api/v1/factory/tasks/{id}/article" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan-001",
  "articleLength": "medium"
}'

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "未认证：令牌缺失或无效。"
  }
}

未认证：令牌缺失或无效。

内容版本

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

返回任务的内容版本列表，包括计划、文章和简报。

查询参数

idstring (uuid)必填

任务 ID

typestring

按内容类型筛选

planarticlebrief

planIdstring

按计划 ID 筛选

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

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

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

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "type": "plan",
      "version": 1,
      "content": {},
      "createdAt": "2026-01-15T12:00:00Z"
    }
  ]
}

成功响应

任务分析

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

返回任务分析：信息补充、生成和发布统计。

查询参数

idstring (uuid)必填

任务 ID

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

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

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

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

成功响应

标签列表

/api/v1/factory/tags

返回内容工厂所有标签及任务数量。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/factory/tags

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

{
  "success": true,
  "data": [
    {
      "id": "tag-001",
      "name": "FAQ",
      "color": "#6366f1",
      "icon": null,
      "isSystem": false,
      "position": 0,
      "taskCount": 5
    },
    {
      "id": "tag-002",
      "name": "SEO",
      "color": "#10b981",
      "icon": "search",
      "isSystem": true,
      "position": 1,
      "taskCount": 12
    }
  ]
}

成功响应

创建标签

/api/v1/factory/tags

为内容工厂任务创建新标签。

请求体

namestring必填

标签名称

colorstring

HEX 颜色，例如 #6366f1

iconstring

标签图标（可选）

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

409application/json

冲突：资源已存在。

CONFLICT

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/tags

curl -X POST "https://app.brandfound.ai/api/v1/factory/tags" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ",
  "color": "#6366f1",
  "icon": "help-circle"
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "color": "example_color",
    "icon": "example_icon",
    "isSystem": true,
    "position": 1,
    "taskCount": 1
  }
}

成功响应

更新标签

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

部分更新内容工厂标签。

查询参数

idstring (uuid)必填

标签 ID

请求体

namestring

colorstring

iconstring

positioninteger

排序位置

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

409application/json

冲突：资源已存在。

CONFLICT

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

curl -X PATCH "https://app.brandfound.ai/api/v1/factory/tags/{id}" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "FAQ Updated",
  "color": "#8b5cf6",
  "position": 2
}'

{
  "success": true,
  "data": {
    "id": "example_id",
    "name": "example_name",
    "color": "example_color",
    "icon": "example_icon",
    "isSystem": true,
    "position": 1,
    "taskCount": 1
  }
}

成功响应

删除标签

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

删除标签，系统标签不可删除。

查询参数

idstring (uuid)必填

标签 ID

响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

403application/json

访问被拒绝

FORBIDDEN

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

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

// No Content

删除成功

发布列表

/api/v1/factory/publications

分页返回内容工厂的发布列表。

查询参数

companyIdstring (uuid)

按公司筛选

offsetinteger= 0

分页偏移量

limitinteger= 20

每页记录数

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/factory/publications

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

{
  "success": true,
  "data": [
    {
      "id": "pub-001",
      "url": "https://samsung.com/blog/galaxy-s25-faq",
      "platform": "blog",
      "publishedAt": "2026-04-10T12:00:00.000Z",
      "planId": "plan-001",
      "planTitle": "FAQ по Galaxy S25",
      "notes": null,
      "taskId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "taskTitle": "Написать FAQ по Galaxy S25",
      "companyId": "clx1abc2d0001abcdef123456"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

成功响应

检测洞察

/api/v1/factory/insights

启动15类检测器：内容缺口、竞争对手优势、空白领域、声誉风险等。

请求体

companyIdstring必填

公司 ID

insightTypestring

洞察类型，省略时启动所有检测器。

CONTENT_GAPCOMPETITOR_WINWHITE_SPACEREPUTATION_RISKKEYWORD_OPPORTUNITYTRENDING_TOPICPROVIDER_BIASSEASONAL_OPPORTUNITYFAQ_OPPORTUNITYCOMPARISON_OPPORTUNITYGUIDE_OPPORTUNITYCASE_STUDY_OPPORTUNITYOPTIMIZATION_NEEDEDAUTHORITY_BUILDING

limitinteger

洞察最大数量

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/insights

curl -X POST "https://app.brandfound.ai/api/v1/factory/insights" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "insightType": "CONTENT_GAP",
  "limit": 10
}'

{
  "success": true,
  "data": {
    "company": "Samsung",
    "insightsFound": 5,
    "tasksCreated": 3,
    "savedTaskIds": [
      "task-001",
      "task-002",
      "task-003"
    ],
    "byType": {
      "CONTENT_GAP": 2,
      "COMPETITOR_WIN": 1,
      "WHITE_SPACE": 2
    }
  }
}

成功响应

Factory 设置

/api/v1/factory/settings

返回用户当前内容工厂设置。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/factory/settings

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

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

成功响应

更新设置

/api/v1/factory/settings

通过深度合并更新内容工厂设置。

请求体

settingsobject必填

与当前设置深度合并的对象

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

PATCH/api/v1/factory/settings

curl -X PATCH "https://app.brandfound.ai/api/v1/factory/settings" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "defaultPriority": "MEDIUM",
    "autoEnrich": true,
    "preferredProviders": [
      "chatgpt",
      "gemini"
    ]
  }
}'

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

成功响应

获取品牌资料卡

/api/v1/factory/brand-card

读取公司的品牌档案，即用于内容生成的 Markdown 文档树。三种模式：无额外参数时，将完整档案合并为 Markdown（清单→核心文件→链接文件→其余文件；移除 ```private 私密区块；上限约12000字符）。mode=index 返回清单及文件列表，包含 path、id、isCore 和出站链接。path=... 返回单个文件：content 原样保留 [名称](brandcard://id)，links 将每个链接解析为路径。

查询参数

companyIdstring (uuid)必填

公司 ID

modestring

index 返回清单和文件列表，而非完整档案。

index

pathstring

与索引一致的文件路径，例如 "main / settings.md"。返回单个文件，不区分大小写。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/factory/brand-card

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

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

成功响应

创建或更新品牌资料卡文件

/api/v1/factory/brand-card

按路径创建或完全覆盖品牌档案文件。自动创建缺失文件夹，无扩展名时添加 .md。引用其他档案文件时使用 [名称](brandcard://<索引中的id>)，链接基于 ID，重命名或移动后仍有效，并提高目标文件在生成中的优先级。编辑时须原样保留已有 brandcard:// 链接。个人笔记和选项应放入 ```private 区块，不会发送给 AI。

请求体

companyIdstring必填

公司 ID

pathstring必填

文件路径，以 "/" 分隔，例如 "products / pricing.md"

contentstring必填

完整 Markdown 文本，会覆盖文件当前内容。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/factory/brand-card

curl -X POST "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "companyId": "9f1c0e2a-…",
  "path": "products / pricing.md",
  "content": "# Прайс\n\nТариф Лайт — 1900 ₽/мес.\n\nСм. также: [Настройки](brandcard://b7e2…)"
}'

{
  "success": true,
  "data": {
    "path": "example_path",
    "created": true
  }
}

成功响应

删除品牌资料卡文件或文件夹

/api/v1/factory/brand-card

按路径删除品牌档案文件或文件夹，删除文件夹时级联删除内容。系统框架（instruction.md、README.md、核心文件）不可删除，应通过 POST 编辑。删除文件后，相关链接变为失效链接：索引 links 不再包含它们，读取文件时返回 path=null。

查询参数

companyIdstring (uuid)必填

公司 ID

pathstring必填

与索引一致的文件或文件夹路径

响应

204

删除成功

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

DELETE/api/v1/factory/brand-card

curl -X DELETE "https://app.brandfound.ai/api/v1/factory/brand-card" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "success": true,
  "data": {
    "deleted": true,
    "path": "example_path"
  }
}

成功响应

余额与支出

FoxCoin 余额和交易记录

FoxCoin 余额与价格

/api/v1/billing/balance

返回余额、收支和操作价格。钱包为账户共享，团队成员使用所有者余额。此处提供价目表，避免在集成代码中写死价格。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/billing/balance

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

{
  "success": true,
  "data": {
    "balance": 1,
    "totalEarned": 1,
    "totalSpent": 1,
    "billingEnabled": true,
    "pricing": {
      "coinToRub": 1,
      "minTopUpRub": 1,
      "answer": 1,
      "generatedQuery": 1,
      "brandCardGeneration": 1,
      "taskEnrichment": 1,
      "contentPlan": 1,
      "articleGeneration": 1,
      "topicSuggestion": 1,
      "factCheck": 1
    }
  }
}

成功响应

交易记录

/api/v1/billing/transactions

钱包交易记录。回答扣费中的 query 指明对应查询。

查询参数

typestring

按交易类型筛选

ANSWER_CHARGEQUERY_GENERATIONBRAND_CARD_GENERATIONTASK_ENRICHMENTARTICLE_GENERATIONCONTENT_PLANTOPIC_SUGGESTIONFACT_CHECKTOPUPBONUSREFUNDMANUAL_ADJUSTMENTSUBSCRIPTION_CREDITAPI_CALL_FREE

fromstring (date-time)

时间窗口开始，ISO 日期，含该日期

tostring (date-time)

时间窗口结束，ISO 日期，含该日期

limitinteger= 50

每页数量

offsetinteger= 0

偏移量

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/billing/transactions

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

{
  "success": true,
  "data": [
    {
      "id": "example_id",
      "amount": 1,
      "type": "ANSWER_CHARGE",
      "description": "example_description",
      "referenceId": "example_referenceId",
      "referenceType": "example_referenceType",
      "balanceAfter": 1,
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00Z",
      "query": {
        "text": "example_text",
        "origin": "example_origin",
        "companyName": "example_companyName"
      }
    }
  ],
  "meta": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

成功响应

参考数据

目录和密钥上下文

列出 AI 模型

/api/v1/sources

列出可用助手及默认选项。value 即 POST /api/v1/queries/setup 中 providers 接受的值。不在此列表的名称会在入队时静默忽略。

查询参数

includeUnpollableboolean= false

包含 claude（旧版队列，当前流程不执行）

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/sources

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

{
  "success": true,
  "data": [
    {
      "value": "chatgpt",
      "label": "example_label",
      "pollable": true,
      "defaultForAccount": true
    }
  ]
}

成功响应

获取 API 密钥上下文

/api/v1/context

建议从这里开始集成：密钥所属账户、权限、可访问公司和产品，以及默认公司。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/context

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

{
  "success": true,
  "data": {
    "accountId": "example_accountId",
    "userId": "example_userId",
    "defaultCompanyId": "example_defaultCompanyId",
    "companies": [
      {
        "id": "example_id",
        "name": "example_name",
        "isDefault": true,
        "products": [
          {
            "id": "example_id",
            "name": "example_name"
          }
        ]
      }
    ],
    "apiKey": {
      "name": "example_name",
      "scopes": [
        "example"
      ],
      "expiresAt": "2026-01-15T12:00:00Z",
      "source": "example_source"
    },
    "tokenAccountId": "example_tokenAccountId",
    "activeAccountId": "example_activeAccountId",
    "availableWorkspaces": [
      {
        "accountId": "example_accountId",
        "role": "owner",
        "ownerName": "example_ownerName",
        "ownerEmail": "example_ownerEmail",
        "companiesCount": 0,
        "isCurrent": true,
        "teamRoleName": "example_teamRoleName",
        "teamRoleKey": "example_teamRoleKey"
      }
    ]
  }
}

成功响应

AI 流量

来自 AI 回答的网站访问（Yandex Metrica）

AI 流量

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

来自 AI 回答的网站访问：各系统带来的访问量及趋势。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

timeRangestring

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

fromstring

时间段开始，ISO 日期

tostring

时间段结束，ISO 日期

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

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

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

{
  "success": true
}

成功响应

来自 AI 模型的访客

/api/v1/analytics/metrika/visitors

AI 来源的访问及站内行为：浏览深度、目标和回访。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

timeRangestring

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

fromstring

时间段开始，ISO 日期

tostring

时间段结束，ISO 日期

hasGoalsboolean

仅达成目标的访问

includeSyntheticboolean

包含合成流量

pvMininteger

最少页面浏览量

pvMaxinteger

最多页面浏览量

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/metrika/visitors

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

{
  "success": true
}

成功响应

AI 流量转化漏斗

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

从 AI 回答点击进入网站到目标操作的路径。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

timeRangestring

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

fromstring

时间段开始，ISO 日期

tostring

时间段结束，ISO 日期

hasGoalsboolean

仅达成目标的访问

includeSyntheticboolean

包含合成流量

pvMininteger

最少页面浏览量

pvMaxinteger

最多页面浏览量

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

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

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

{
  "success": true
}

成功响应

提及与流量的相关性

/api/v1/analytics/metrika/correlation

比较品牌提及趋势与实际访问趋势，判断可见度增长是否带来流量增长。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

companyIdstring (uuid)

公司，省略时使用密钥的 preferredCompanyId。

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

timeRangestring

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

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/metrika/correlation

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

{
  "success": true
}

成功响应

Metrika 转化目标

/api/v1/analytics/metrika/goals

计数器目标目录，说明其他方法中的 hasGoals 参数。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

includeInactiveboolean

包含未启用目标

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/analytics/metrika/goals

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

{
  "success": true
}

成功响应

模拟流量概况

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

机器人及非自然访问占比，防止其影响 AI 流量分析。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

timeRangestring

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

fromstring

时间段开始，ISO 日期

tostring

时间段结束，ISO 日期

filterstring

分类筛选

hasGoalsboolean

仅达成目标的访问

pvMininteger

最少页面浏览量

pvMaxinteger

最多页面浏览量

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

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

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

{
  "success": true
}

成功响应

列出模拟访问

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

汇总的分页详情：具有合成流量特征的具体访问。作用范围为当前账户，其他账户的 integrationId 会被忽略。空结果通常表示未连接 Metrica，请检查 /api/v1/integrations/metrika/status。

查询参数

integrationIdstring (uuid)

Metrica 计数器，省略时使用账户全部已连接计数器。

timeRangestring

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

fromstring

时间段开始，ISO 日期

tostring

时间段结束，ISO 日期

filterstring

分类筛选

qstring

搜索

qScopestring

搜索范围

hasRevenueboolean

仅产生收入的访问

returningOnlyboolean

仅回访

pageinteger

页码

pageSizeinteger

每页数量

sortBystring

排序字段

sortOrderstring

asc | desc

hasGoalsboolean

仅达成目标的访问

pvMininteger

最少页面浏览量

pvMaxinteger

最多页面浏览量

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

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

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

{
  "success": true
}

成功响应

已连接的统计计数器

/api/v1/integrations/metrika/list

AI 流量功能的入口，返回其他方法使用的 integrationId。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/integrations/metrika/list

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

{
  "success": true
}

成功响应

集成状态

/api/v1/integrations/metrika/status

显示是否已连接 Metrica、同步时间及访问是否过期，可解释其他方法返回空结果的原因。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/integrations/metrika/status

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

{
  "success": true
}

成功响应

电商

AI 回答中的商品卡片

商品分析

/api/v1/analytics/commerce

AI 在回答文本旁展示的商品卡片。view=summary 返回含卡片回答占比及各系统趋势；sellers 返回热门卖家和域名；brands 比较自身品牌与竞争对手卡片；cards 返回分页列表。

查询参数

viewstring= summary

summary | sellers | brands | cards

summarysellersbrandscards

companyIdstring (uuid)

公司，省略时使用密钥的 preferredCompanyId。

productIdstring[]

可传入多个值

timeRangestring

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

granularitystring

趋势分组维度

tzstring

时区

labelIdstring[]

聚类

labelSlugstring[]

按 slug 指定聚类

labelFilterModestring

AND | OR

sourceIdstring[]

来源

queryTypestring[]

查询类型

includeDemoboolean

包含演示数据

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

GET/api/v1/analytics/commerce

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

{
  "success": true
}

成功响应

跟踪中的商品

/api/v1/commerce/products

用于匹配回答卡片的商品目录。没有目录时，“商业”仅显示卖家和域名，无法比较自身与其他商品。

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/commerce/products

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

{
  "success": true
}

成功响应

添加商品

/api/v1/commerce/products

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/commerce/products

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

{
  "success": true
}

成功响应

监控

按计划定期执行查询

列出监测中的查询

/api/v1/favorite-queries

已设置定期执行的查询列表。

查询参数

searchstring

按文本搜索

activeboolean

仅已启用项

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

GET/api/v1/favorite-queries

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

{
  "success": true
}

成功响应

开始监测查询

/api/v1/favorite-queries

普通 POST /api/v1/queries 仅执行一次 AI 查询。定期执行是独立实体，在此创建。创建记录不会启动查询，第二步须通过 POST /api/v1/favorite-queries/{id}/assignments 设置计划。每次计划执行均收费：每个 AI 系统的每条回答10 FoxCoin。例如，三系统、60分钟间隔，每天72条回答。余额不足时执行暂停，不会自动恢复，需调用 POST /api/v1/queries/queue/resume。

请求体

textstring必填

typestring必填

companyIdstring

productIdstring

languagestring= ru

regionstring= RU

isActiveboolean= true

tagsstring[]

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

POST/api/v1/favorite-queries

curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "best threat intelligence vendors for banks in UAE",
  "type": "comparative",
  "companyId": "e08cf948-88b4-4aac-949e-6c1cc3b4f427",
  "language": "en",
  "region": "AE"
}'

{
  "success": true
}

成功响应

获取监测记录

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

查询参数

idstring (uuid)必填

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

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

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

{
  "success": true
}

成功响应

修改监测记录

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

文本、公司、标签和 isActive。使用 isActive:false 可停用而不删除。

查询参数

idstring (uuid)必填

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

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

{
  "success": true
}

成功响应

停止监测查询

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

删除记录及计划，之后不再执行。已有回答和提及保留，因为它们属于查询，而非订阅。

查询参数

idstring (uuid)必填

响应

204

删除成功

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

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

{
  "success": true
}

成功响应

获取查询计划

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

查询参数

idstring (uuid)必填

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

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

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

{
  "success": true
}

成功响应

设置查询计划

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

从这里开始定期执行：没有计划的记录不会运行。每条记录仅有一个计划，再次调用会覆盖。每次计划执行均收费：每个 AI 系统的每条回答10 FoxCoin。例如，三系统、60分钟间隔，每天72条回答。余额不足时执行暂停，不会自动恢复，需调用 POST /api/v1/queries/queue/resume。

查询参数

idstring (uuid)必填

请求体

providersstring[]必填

列表：GET /api/v1/sources

frequencyMinutesinteger必填

执行间隔

isEnabledboolean= true

暂停但不删除计划

timezonestring= Europe/Moscow

用于计算 daysOfWeek 和 hoursWindow 的时区

daysOfWeekinteger[]

1..7，留空表示每天。

hoursWindowobject

允许执行的小时窗口，窗口外不执行。

modelobject

“AI 系统→模型”映射

响应

200

成功响应

400application/json

输入数据校验错误

VALIDATION_ERROR

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

curl -X POST "https://app.brandfound.ai/api/v1/favorite-queries/{id}/assignments" \
  -H "Authorization: Bearer gfx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "providers": [
    "chatgpt",
    "perplexity",
    "gemini"
  ],
  "frequencyMinutes": 1440,
  "timezone": "Europe/Moscow"
}'

{
  "success": true
}

成功响应

立即执行查询

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

立即额外执行一次，不等待或改变原有计划，按正常规则收费。

查询参数

idstring (uuid)必填

响应

200

成功响应

401application/json

未认证：令牌缺失或无效。

UNAUTHORIZED

404application/json

资源未找到

NOT_FOUND

429application/json

请求频率超限：每 IP 每分钟120次，每用户每分钟60次。

RATE_LIMIT_EXCEEDED

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

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

{
  "success": true
}

成功响应

brandfound. API

1.2 版本新增内容

面向 AI 助手

身份验证

工作空间

列出可访问的工作区

响应

切换 API 密钥的当前工作区

请求体

响应

公司

公司列表

查询参数

响应

创建公司

请求体

响应

获取公司

查询参数

响应

更新公司

查询参数

请求体

响应

归档公司

查询参数

响应

列出行业

响应

产品

产品列表

查询参数

响应

创建产品

请求体

响应

获取产品

查询参数

响应

更新产品

查询参数

请求体

响应

归档产品

查询参数

响应

竞争对手

竞争对手列表

查询参数

响应

创建竞争对手

请求体

响应

获取竞争对手

查询参数

响应

更新竞争对手

查询参数

请求体

响应

归档竞争对手

查询参数

响应

关键词

列出搜索意图

查询参数

响应

创建或复用搜索意图

请求体

响应

获取搜索意图

查询参数

响应

重命名搜索意图

查询参数

请求体

响应

归档或删除搜索意图

查询参数

响应