竞争对手

竞争对手是 Topify.ai 在 AI 回复中与您一同跟踪的品牌。此端点返回活跃的竞争对手，并附带聚合的可见度、情感分析和位置指标。

列出竞争对手

GET /projects/{project_id}/competitors

返回项目中所有活跃的竞争对手，及给定日期范围内的聚合指标。

路径参数

参数	类型	描述
`project_id`	string (UUID)	项目 ID

查询参数

参数	类型	默认值	描述
`duration_days`	integer	`7`	回溯天数
`date_from`	string	—	起始日期（`YYYY-MM-DD`）
`date_to`	string	—	结束日期（`YYYY-MM-DD`）
`providers`	string	—	以逗号分隔的 AI 服务商筛选

cURL
Python
Node.js（服务端）

curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/competitors?duration_days=7" \
  -H "X-API-Key: tk_live_..."

resp = client.get(f"/projects/{project_id}/competitors", params={"duration_days": 7})

const resp = await fetch(`${BASE}/projects/${projectId}/competitors?duration_days=7`, { headers });

响应

{
  "success": true,
  "data": {
    "active_competitors": [
      {
        "competitor_id": "00000000-0000-0000-0000-000000000000",
        "project_id": "a1b2c3d4-...",
        "name": "Acme Corp",
        "website": "https://acme.com",
        "icon_url": "https://logo.clearbit.com/acme.com",
        "icon_urls": [
          "https://logo.clearbit.com/acme.com",
          "https://www.google.com/s2/favicons?domain=acme.com&sz=64"
        ],
        "state": "active",
        "is_own_brand": true,
        "metrics": {
          "visibility": 85.0,
          "sentiment": 72.0,
          "position": 1.8,
          "mention_count": null,
          "days_with_data": 7,
          "period": "2026-02-27 to 2026-03-06"
        }
      },
      {
        "competitor_id": "c1d2e3f4-...",
        "project_id": "a1b2c3d4-...",
        "name": "Competitor A",
        "website": "https://competitor-a.com",
        "icon_url": "https://logo.clearbit.com/competitor-a.com",
        "icon_urls": [
          "https://logo.clearbit.com/competitor-a.com",
          "https://www.google.com/s2/favicons?domain=competitor-a.com&sz=64"
        ],
        "state": "active",
        "is_own_brand": false,
        "metrics": {
          "visibility": 72.0,
          "sentiment": 65.0,
          "position": 3.1,
          "mention_count": null,
          "days_with_data": 7,
          "period": "2026-02-27 to 2026-03-06"
        }
      }
    ],
    "total_active": 8
  }
}

CompetitorResponse 字段

字段	类型	可空	描述
`competitor_id`	string (UUID)	No	竞争对手 ID。`00000000-...` 表示注入的自有品牌
`project_id`	string (UUID)	No	父项目 ID
`name`	string	No	竞争对手品牌名称
`website`	string	No	竞争对手网站 URL
`icon_url`	string	Yes	主要 logo URL
`icon_urls`	string[]	No	多个 logo URL 来源（Clearbit + Google favicon）
`state`	string	Yes	在此端点中始终为 `active`
`is_own_brand`	boolean	No	如果这是您自己的品牌则为 `true`
`metrics`	CompetitorMetrics	Yes	日期范围内的聚合指标

CompetitorMetrics 字段

字段	类型	可空	描述
`visibility`	float	Yes	该周期内的平均可见度评分
`sentiment`	float	Yes	该周期内的平均情感分析评分
`position`	float	Yes	AI 回复中的平均位置
`mention_count`	integer	Yes	总提及次数（可能为 `null`）
`days_with_data`	integer	Yes	收集到数据的天数
`period`	string	No	人类可读的日期范围（例如 `2026-02-27 to 2026-03-06`）

您自己的品牌始终包含在响应中，并以 is_own_brand: true 标识。如果您的品牌还未作为竞争对手存在，则会以零值指标自动注入，以便您直接进行比较。

列出待审核竞争对手

GET /projects/{project_id}/competitors/pending

返回由 AI 发现、等待跟踪或拒绝决定的竞争对手。待审核竞争对手尚无分析指标。

curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/competitors/pending" \
  -H "X-API-Key: tk_live_..."

{
  "success": true,
  "data": {
    "pending_competitors": [
      {
        "competitor_id": "e5f6a7b8-...",
        "project_id": "a1b2c3d4-...",
        "name": "Acme",
        "website": "https://acme.com",
        "state": "pending",
        "is_own_brand": false,
        "metrics": null
      }
    ],
    "total_pending": 1
  }
}

审核待定竞争对手

PATCH /projects/{project_id}/competitors/{competitor_id}/state

跟踪或拒绝待审核竞争对手。发送 active 开始跟踪，或发送 inactive 拒绝。只有当前处于 pending 状态的竞争对手可通过此端点审核。

curl -X PATCH "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/competitors/{competitor_id}/state" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"state":"active"}'

字段	类型	必填	描述
`state`	string	是	`active` 表示跟踪，`inactive` 表示拒绝

状态	原因
`400`	目标状态无效
`404`	在此项目中未找到竞争对手
`409`	竞争对手当前不是待审核状态

创建竞争对手

POST /projects/{project_id}/competitors

向项目中添加一个或多个竞争对手品牌。每个竞争对手会立即开始跟踪。

API 密钥由管理员创建，目前对整个团队拥有完整权限。创建竞争对手前请确认项目和列表。

路径参数

参数	类型	描述
`project_id`	string (UUID)	要添加竞争对手的项目

请求体

字段	类型	必填	描述
`competitors`	object[]	Yes	要添加的竞争对手数组（每次请求 1—20 个）
`competitors[].name`	string	Yes	品牌名称
`competitors[].website`	string	Yes	网站域名或 URL（例如 `acme.com` 或 `https://acme.com`）

cURL
Python
Node.js（服务端）

curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/competitors" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "competitors": [
      {"name": "Acme Corp", "website": "acme.com"},
      {"name": "Globex Inc", "website": "globex.net"}
    ]
  }'

resp = client.post(f"/projects/{project_id}/competitors", json={
    "competitors": [
        {"name": "Acme Corp", "website": "acme.com"},
        {"name": "Globex Inc", "website": "globex.net"},
    ],
})

const resp = await fetch(`${BASE}/projects/${projectId}/competitors`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    competitors: [
      { name: "Acme Corp", website: "acme.com" },
      { name: "Globex Inc", website: "globex.net" },
    ],
  }),
});

响应

{
  "code": 200,
  "message": "200 OK",
  "data": {
    "projectId": "a1b2c3d4-...",
    "created": 2,
    "competitors": [
      {
        "competitorId": "c1d2e3f4-...",
        "projectId": "a1b2c3d4-...",
        "name": "Acme Corp",
        "website": "https://acme.com",
        "iconUrl": "https://img.logo.dev/acme.com?token=...",
        "iconUrls": ["https://img.logo.dev/acme.com?token=..."],
        "state": "active",
        "isOwnBrand": false,
        "metrics": null
      }
    ]
  }
}

错误响应

状态	原因
`400`	竞争对手数组为空、名称为空、网站 URL 无效，或请求中存在重复域名
`409`	项目中已存在相同域名的竞争对手
`429`	已达到活跃竞争对手数量上限（最多 10 个）

更新竞争对手

PATCH /projects/{project_id}/competitors/{competitor_id}

更新现有竞争对手的名称或网站。

API 密钥由管理员创建，目前对整个团队拥有完整权限。更新竞争对手前请确认项目和字段。

路径参数

参数	类型	描述
`project_id`	string (UUID)	项目 ID
`competitor_id`	string (UUID)	要更新的竞争对手

请求体

所有字段均为可选。仅包含您想要修改的字段。

字段	类型	描述
`name`	string	新的品牌名称（不能为空）
`website`	string	新的网站域名或 URL

cURL
Python
Node.js（服务端）

curl -X PATCH "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/competitors/{competitor_id}" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Inc", "website": "acmeinc.com"}'

resp = client.patch(f"/projects/{project_id}/competitors/{competitor_id}", json={
    "name": "Acme Inc",
})

const resp = await fetch(`${BASE}/projects/${projectId}/competitors/${competitorId}`, {
  method: "PATCH",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Acme Inc" }),
});

响应

返回更新后的竞争对手及其全部字段（与列出竞争对手中的项形状相同）。

错误响应

状态	原因
`400`	请求体为空、名称只有空白字符、网站 URL 无效，或没有字段被修改
`403`	API 密钥具有只读权限
`404`	在此项目中未找到竞争对手

删除竞争对手

DELETE /projects/{project_id}/competitors/{competitor_id}

从您的项目中永久删除一个竞争对手并停止跟踪。

此操作不可撤销。API 密钥由管理员创建，目前对整个团队拥有完整权限。

路径参数

参数	类型	描述
`project_id`	string (UUID)	项目 ID
`competitor_id`	string (UUID)	要删除的竞争对手

cURL
Python
Node.js（服务端）

curl -X DELETE "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/competitors/{competitor_id}" \
  -H "X-API-Key: tk_live_..."

resp = client.delete(f"/projects/{project_id}/competitors/{competitor_id}")

const resp = await fetch(`${BASE}/projects/${projectId}/competitors/${competitorId}`, {
  method: "DELETE",
  headers,
});

响应

{
  "code": 200,
  "message": "200 OK",
  "data": {
    "competitorId": "c1d2e3f4-...",
    "message": "Competitor deleted successfully"
  }
}

错误响应

状态	原因
`403`	API 密钥具有只读权限
`404`	在此项目中未找到竞争对手

开始使用

经授权的 AI 智能体设置

端点

列出竞争对手

路径参数

查询参数

响应

CompetitorResponse 字段

CompetitorMetrics 字段

列出待审核竞争对手

审核待定竞争对手

创建竞争对手

路径参数

请求体

响应

错误响应

更新竞争对手

路径参数

请求体

响应

错误响应

删除竞争对手

路径参数

响应

错误响应

​列出竞争对手

​路径参数

​查询参数

​响应

​CompetitorResponse 字段

​CompetitorMetrics 字段

​列出待审核竞争对手

​审核待定竞争对手

​创建竞争对手

​路径参数

​请求体

​响应

​错误响应

​更新竞争对手

​路径参数

​请求体

​响应

​错误响应

​删除竞争对手

​路径参数

​响应

​错误响应

列出竞争对手

路径参数

查询参数

响应

CompetitorResponse 字段

CompetitorMetrics 字段

列出待审核竞争对手

审核待定竞争对手

创建竞争对手

路径参数

请求体

响应

错误响应

更新竞争对手

路径参数

请求体

响应

错误响应

删除竞争对手

路径参数

响应

错误响应