搜索词

搜索词是 Topify.ai 每天在所有 AI 服务商上跟踪的 AI 搜索查询。每个搜索词会生成回复，并被分析以衡量品牌可见度、情感分析、引用和竞争对手提及情况。 API 支持对搜索词进行完整的 CRUD 操作。读取端点对所有 API 密钥开放。写入端点（创建、更新、删除）需要管理员作用域的 API 密钥。

列出搜索词

GET /projects/{project_id}/prompts

返回项目中的所有搜索词，按创建日期排序。

路径参数

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

cURL
Python
JavaScript

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

resp = client.get(f"/projects/{project_id}/prompts")

const resp = await fetch(`${BASE}/projects/${projectId}/prompts`, { headers });

响应

{
  "success": true,
  "data": {
    "project_id": "a1b2c3d4-...",
    "total": 25,
    "prompts": [
      {
        "id": "e5f6a7b8-...",
        "project_id": "a1b2c3d4-...",
        "content": "What is the best project management tool?",
        "prompt_type": "active",
        "topic_id": "t1u2v3w4-...",
        "country": "US",
        "visibility": 85.0,
        "sentiment": 72,
        "position": 2.3,
        "volume": 150,
        "cvr": 45.0,
        "intent": "commercial",
        "trend": "up",
        "created_at": "2026-01-15T10:30:00+00:00"
      }
    ]
  }
}

搜索词字段

字段	类型	可空	描述
`id`	string (UUID)	No	搜索词 ID
`project_id`	string (UUID)	No	父项目 ID
`content`	string	No	AI 搜索查询文本
`prompt_type`	string	No	`active`、`suggested`、`pending`、`inactive` 或 `url_recommended`
`topic_id`	string (UUID)	Yes	该搜索词所属的主题
`country`	string	Yes	用于本地化回复的目标国家
`visibility`	float	Yes	品牌可见度百分比（0—100）
`sentiment`	integer	Yes	品牌情感分析评分
`position`	float	Yes	品牌在回复中的平均位置
`volume`	integer	Yes	收集到的回复数量
`cvr`	float	Yes	内容可见度率
`intent`	string	Yes	查询意图：`informational`、`commercial`、`navigational`、`transactional`
`trend`	string	Yes	趋势方向：`up`、`down` 或 `stable`
`created_at`	string (ISO 8601)	No	创建时间

获取搜索词

GET /projects/{project_id}/prompts/{prompt_id}

返回单个搜索词。字段与列表相同。

路径参数

参数	类型	描述
`project_id`	string (UUID)	项目 ID
`prompt_id`	string (UUID)	搜索词 ID

cURL
Python
JavaScript

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

resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}")

const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}`, { headers });

创建搜索词

POST /projects/{project_id}/prompts

向项目中添加一个或多个搜索词。每个搜索词会立即开始跟踪 —— Topify.ai 将在后台开始收集 AI 回复并计算指标。

需要管理员作用域的 API 密钥。只读密钥会收到 403 响应。

路径参数

参数	类型	描述
`project_id`	string (UUID)	要添加搜索词的项目

请求体

字段	类型	必填	描述
`prompts`	string[]	Yes	要跟踪的搜索词文本数组（每次请求 1—50 个）
`topicId`	string (UUID)	Yes	要将搜索词分配到的主题
`country`	string	No	用于本地化回复的 ISO 国家代码

cURL
Python
JavaScript

curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["What is the best project management tool?", "Top PM software for teams"],
    "topicId": "t1u2v3w4-...",
    "country": "US"
  }'

resp = client.post(f"/projects/{project_id}/prompts", json={
    "prompts": ["What is the best project management tool?"],
    "topicId": topic_id,
    "country": "US",
})

const resp = await fetch(`${BASE}/projects/${projectId}/prompts`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompts: ["What is the best project management tool?"],
    topicId: topicId,
    country: "US",
  }),
});

响应

{
  "code": 200,
  "message": "200 OK",
  "data": {
    "projectId": "a1b2c3d4-...",
    "created": 2,
    "prompts": [
      {
        "id": "e5f6a7b8-...",
        "projectId": "a1b2c3d4-...",
        "content": "What is the best project management tool?",
        "promptType": "Active",
        "topicId": "t1u2v3w4-...",
        "country": "US",
        "createdAt": "2026-03-30T10:30:00+00:00"
      }
    ]
  }
}

错误响应

状态	原因
`400`	搜索词数组为空、内容只有空白字符，或缺少 `topicId`
`403`	API 密钥具有只读（viewer）权限
`409`	项目中已存在内容相同的搜索词
`429`	已达到您的套餐等级的搜索词配额

更新搜索词

PATCH /projects/{project_id}/prompts/{prompt_id}

更新现有搜索词的内容、国家、主题或类型。

需要管理员作用域的 API 密钥。

路径参数

参数	类型	描述
`project_id`	string (UUID)	项目 ID
`prompt_id`	string (UUID)	要更新的搜索词

请求体

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

字段	类型	描述
`content`	string	新的搜索词文本（不能为空）
`country`	string	ISO 国家代码
`topicId`	string (UUID)	重新分配到不同的主题
`promptType`	string	修改搜索词类型（`Active`、`Inactive`、`Suggested`）

cURL
Python
JavaScript

curl -X PATCH "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}" \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Best project management tools for remote teams"}'

resp = client.patch(f"/projects/{project_id}/prompts/{prompt_id}", json={
    "content": "Best project management tools for remote teams",
})

const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}`, {
  method: "PATCH",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ content: "Best project management tools for remote teams" }),
});

响应

返回更新后的搜索词及其全部字段（与获取搜索词形状相同）。

错误响应

状态	原因
`400`	请求体为空、内容只有空白字符，或没有字段被修改
`403`	API 密钥具有只读权限
`404`	在此项目中未找到搜索词

删除搜索词

DELETE /projects/{project_id}/prompts/{prompt_id}

永久删除一个搜索词并停止跟踪它。该搜索词的历史分析数据也会一并删除。

此操作不可撤销。需要管理员作用域的 API 密钥。

路径参数

参数	类型	描述
`project_id`	string (UUID)	项目 ID
`prompt_id`	string (UUID)	要删除的搜索词

cURL
Python
JavaScript

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

resp = client.delete(f"/projects/{project_id}/prompts/{prompt_id}")

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

响应

{
  "code": 200,
  "message": "200 OK",
  "data": {
    "promptId": "e5f6a7b8-...",
    "message": "Prompt deleted successfully"
  }
}

错误响应

状态	原因
`403`	API 密钥具有只读权限
`404`	在此项目中未找到搜索词

搜索词分析

GET /projects/{project_id}/prompts/{prompt_id}/analytics

返回按日期和 AI 服务商分组的可见度、位置和情感分析时间序列数据。

查询参数

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

cURL
Python
JavaScript

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

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

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

响应

{
  "success": true,
  "data": {
    "prompt_id": "e5f6a7b8-...",
    "prompt_content": "What is the best project management tool?",
    "volume": 42,
    "sentiment": 72,
    "visibility_chart": {
      "2026-03-01": [
        { "provider": "chatgpt", "value": 85.0 },
        { "provider": "perplexity", "value": 90.0 }
      ],
      "2026-03-02": [
        { "provider": "chatgpt", "value": 80.0 }
      ]
    },
    "position_chart": {
      "2026-03-01": [
        { "provider": "chatgpt", "value": 2.0 }
      ]
    },
    "sentiment_chart": {
      "2026-03-01": [
        { "provider": "chatgpt", "value": 75.0 }
      ]
    }
  }
}

响应字段

字段	类型	可空	描述
`prompt_id`	string (UUID)	No	搜索词 ID
`prompt_content`	string	No	AI 搜索查询文本
`volume`	integer	Yes	收集到的回复总数
`sentiment`	integer	Yes	该周期内的整体品牌情感分析
`visibility_chart`	object	No	以日期为键的 `ProviderMetric[]` 映射（可见度 %）
`position_chart`	object	No	以日期为键的 `ProviderMetric[]` 映射（平均位置）
`sentiment_chart`	object	No	以日期为键的 `ProviderMetric[]` 映射（平均情感分析）

ProviderMetric：

字段	类型	描述
`provider`	string	AI 服务商名称（例如 `chatgpt`）
`value`	float	该 AI 服务商在该日期的指标值

AI 回复（chats）

GET /projects/{project_id}/prompts/{prompt_id}/chats

返回原始 AI 回复，包括品牌提及、情感分析、位置和引用。

查询参数

与搜索词分析相同。

cURL
Python
JavaScript

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

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

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

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "c1d2e3f4-...",
        "date": "2026-03-01T12:00:00+00:00",
        "mentioned": true,
        "position": 2,
        "all_mentions": [
          {
            "name": "Acme Corp",
            "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"]
          }
        ],
        "chat_preview": "When it comes to project management tools...",
        "platform": "chatgpt",
        "model": "gpt-4o",
        "full_content": "When it comes to project management tools, Acme Corp stands out for...",
        "prompt_content": "What is the best project management tool?",
        "references": [
          {
            "title": "Best PM Tools 2026",
            "link": "https://techcrunch.com/best-pm-tools",
            "snippet": "Acme Corp ranked #1...",
            "reference_index": 1
          }
        ],
        "brands_mentioned": {
          "Acme Corp": { "position": 1, "count": 3 },
          "Competitor A": { "position": 2, "count": 1 }
        },
        "sentiment": 80,
        "sentiment_by_brands": {
          "Acme Corp": 80,
          "Competitor A": 60
        }
      }
    ]
  }
}

ChatItem 字段

字段	类型	可空	描述
`id`	string (UUID)	No	LLM 输出 ID
`date`	string (ISO 8601)	No	回复生成时间
`mentioned`	boolean	No	您的品牌是否被提及
`position`	integer	Yes	您的品牌在此回复中的排名位置
`all_mentions`	BrandMention[]	No	此回复中提到的所有品牌
`chat_preview`	string	No	回复的首句（最多 150 字符）
`platform`	string	No	AI 服务商（`chatgpt`、`perplexity`、`google_ai_overview`、`gemini`、`claude`）
`model`	string	No	使用的具体模型（例如 `gpt-4o`）
`full_content`	string	No	完整的 AI 回复文本
`prompt_content`	string	No	生成此回复的搜索词
`references`	ReferenceItem[]	No	回复中的引用/来源
`brands_mentioned`	object	Yes	原始品牌提取数据（品牌名称到位置/计数的映射）
`sentiment`	integer	Yes	您的品牌在此回复中的情感分析评分
`sentiment_by_brands`	object	Yes	按品牌名称为键的情感分析评分

BrandMention：

字段	类型	描述
`name`	string	出现在回复中的品牌名称
`icon_url`	string	主要 logo URL
`icon_urls`	string[]	多个 logo URL 来源

ReferenceItem：

字段	类型	描述
`title`	string	引用标题
`link`	string	引用 URL
`snippet`	string	引用摘要文本
`reference_index`	integer	引用在回复中的位置

域名

GET /projects/{project_id}/prompts/{prompt_id}/domains

返回域名级别的引用细分，按引用次数降序排列。

查询参数

与搜索词分析相同。

cURL
Python
JavaScript

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

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

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

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "domain": "techcrunch.com",
        "domain_type": 1,
        "citation_count": 15,
        "avg_citations": 2.5,
        "used_percentage": 75.0,
        "mentioned": true,
        "brands_appeared": [
          {
            "name": "Acme Corp",
            "icon_url": "https://logo.clearbit.com/acme.com",
            "icon_urls": ["https://logo.clearbit.com/acme.com"]
          }
        ],
        "favicon_url": "https://www.google.com/s2/favicons?domain=techcrunch.com&sz=64",
        "favicon_urls": [
          "https://logo.clearbit.com/techcrunch.com",
          "https://www.google.com/s2/favicons?domain=techcrunch.com&sz=64"
        ]
      }
    ]
  }
}

DomainItem 字段

字段	类型	可空	描述
`domain`	string	No	域名
`domain_type`	integer	No	来源类别 ID
`citation_count`	integer	No	在所有回复中的总引用次数
`avg_citations`	float	No	引用此域名的回复中的平均引用数
`used_percentage`	float	No	此域名出现的频率（百分比）
`mentioned`	boolean	No	您的品牌是否与此域名一起出现
`brands_appeared`	BrandInfo[]	No	在引用此域名的回复中出现的品牌
`favicon_url`	string	Yes	主要 favicon URL
`favicon_urls`	string[]	No	多个 favicon URL 来源

BrandInfo：

字段	类型	描述
`name`	string	品牌名称
`icon_url`	string	主要 logo URL
`icon_urls`	string[]	多个 logo URL 来源

URL

GET /projects/{project_id}/prompts/{prompt_id}/urls

返回 URL 级别的引用数据，按提及次数降序排列。

查询参数

与搜索词分析相同。

cURL
Python
JavaScript

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

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

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

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "url": "https://techcrunch.com/best-pm-tools-2026",
        "title": "Best PM Tools 2026",
        "domain": "techcrunch.com",
        "url_type": null,
        "url_type_name": "unknown",
        "mentioned_count": 8,
        "brands_appear": [
          {
            "name": "Acme Corp",
            "icon_url": "https://logo.clearbit.com/acme.com",
            "icon_urls": ["https://logo.clearbit.com/acme.com"]
          }
        ],
        "first_seen": "2026-02-15T00:00:00+00:00",
        "last_seen": "2026-03-01T00:00:00+00:00"
      }
    ]
  }
}

UrlItem 字段

字段	类型	可空	描述
`url`	string	No	完整 URL
`title`	string	No	页面标题
`domain`	string	No	从 URL 中提取的域名
`url_type`	integer	Yes	URL 类型 ID
`url_type_name`	string	No	URL 类型标签（例如 `unknown`）
`mentioned_count`	integer	No	此 URL 被引用的次数
`brands_appear`	BrandInfo[]	No	在引用此 URL 的回复中出现的品牌
`first_seen`	string (ISO 8601)	No	最早被引用的日期
`last_seen`	string (ISO 8601)	No	最近被引用的日期

开始使用

免费自动 AI 智能体集成

端点

列出搜索词

路径参数

响应

搜索词字段

获取搜索词

路径参数

创建搜索词

路径参数

请求体

响应

错误响应

更新搜索词

路径参数

请求体

响应

错误响应

删除搜索词

路径参数

响应

错误响应

搜索词分析

查询参数

响应

响应字段

AI 回复（chats）

查询参数

响应

ChatItem 字段

域名

查询参数

响应

DomainItem 字段

URL

查询参数

响应

UrlItem 字段

开始使用

免费自动 AI 智能体集成

端点

Documentation Index

​列出搜索词

​路径参数

​响应

​搜索词字段

​获取搜索词

​路径参数

​创建搜索词

​路径参数

​请求体

​响应

​错误响应

​更新搜索词

​路径参数

​请求体

​响应

​错误响应

​删除搜索词

​路径参数

​响应

​错误响应

​搜索词分析

​查询参数

​响应

​响应字段

​AI 回复（chats）

​查询参数

​响应

​ChatItem 字段

​域名

​查询参数

​响应

​DomainItem 字段

​URL

​查询参数

​响应

​UrlItem 字段

列出搜索词

路径参数

响应

搜索词字段

获取搜索词

路径参数

创建搜索词

路径参数

请求体

响应

错误响应

更新搜索词

路径参数

请求体

响应

错误响应

删除搜索词

路径参数

响应

错误响应

搜索词分析

查询参数

响应

响应字段

AI 回复（chats）

查询参数

响应

ChatItem 字段

域名

查询参数

响应

DomainItem 字段

URL

查询参数

响应

UrlItem 字段