列出搜索词
GET /projects/{project_id}/prompts
路径参数
| 参数 | 类型 | 描述 |
|---|---|---|
project_id | string (UUID) | 项目 ID |
- cURL
- Python
- Node.js(服务端)
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
- Node.js(服务端)
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
API 密钥由管理员创建,目前对整个团队拥有完整权限。创建搜索词前请确认项目和搜索词文本。
路径参数
| 参数 | 类型 | 描述 |
|---|---|---|
project_id | string (UUID) | 要添加搜索词的项目 |
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
prompts | string[] | Yes | 要跟踪的搜索词文本数组(每次请求 1—50 个) |
topicId | string (UUID) | Yes | 要将搜索词分配到的主题 |
country | string | No | 用于本地化回复的 ISO 国家代码 |
- cURL
- Python
- Node.js(服务端)
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 |
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
- Node.js(服务端)
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 | 在此项目中未找到搜索词 |
搜索词分析
GET /projects/{project_id}/prompts/{prompt_id}/analytics
查询参数
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
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}/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[] 映射(平均情感分析) |
| 字段 | 类型 | 描述 |
|---|---|---|
provider | string | AI 服务商名称(例如 chatgpt) |
value | float | 该 AI 服务商在该日期的指标值 |
单个 Prompt 的竞品指标
GET /projects/{project_id}/prompts/{prompt_id}/competitors
路径参数
| 参数 | 类型 | 描述 |
|---|---|---|
project_id | string (UUID) | 项目 ID |
prompt_id | string (UUID) | Prompt ID |
查询参数
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
duration_days | integer | 30 | 未传明确日期范围时,向前回溯的天数 |
date_from | string | — | 开始日期(YYYY-MM-DD) |
date_to | string | — | 结束日期(YYYY-MM-DD) |
providers | string | — | 用逗号分隔的 AI 服务商过滤条件 |
aggregate_over_time | boolean | true | true 返回整个周期内每个竞品一行;false 返回每个日期、每个竞品一行。 |
- cURL
- Python
- Node.js(服务端)
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}/competitors?duration_days=7&aggregate_over_time=false" \
-H "X-API-Key: tk_live_..."
resp = client.get(
f"/projects/{project_id}/prompts/{prompt_id}/competitors",
params={"duration_days": 7, "aggregate_over_time": False},
)
const resp = await fetch(
`${BASE}/projects/${projectId}/prompts/${promptId}/competitors?duration_days=7&aggregate_over_time=false`,
{ headers }
);
响应
{
"success": true,
"data": {
"prompt_id": "e5f6a7b8-...",
"prompt_content": "What are the best luxury cake brands for gifting online?",
"period": {
"date_from": "2026-03-01",
"date_to": "2026-03-07"
},
"aggregate_over_time": false,
"granularity": "day",
"items": [
{
"date": "2026-03-01",
"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,
"visibility": 54.55,
"sentiment": 76.9,
"position": 2.83,
"sov": 9.3,
"mention_count": 12,
"total_responses": 22,
"total_brand_mentions": 129,
"sentiment_count": 10,
"position_count": 12,
"days_with_data": 1,
"days_with_responses": 1
}
],
"total_items": 77,
"total_competitors": 11
}
}
PromptCompetitorsResponse 字段
| 字段 | 类型 | 可为空 | 描述 |
|---|---|---|---|
prompt_id | string (UUID) | No | Prompt ID |
prompt_content | string | No | AI 搜索查询文本 |
period | object | No | 本次计算使用的日期范围 |
aggregate_over_time | boolean | No | 是否按整个周期聚合 |
granularity | string | No | 聚合时为 period;按天返回时为 day |
items | PromptCompetitorMetricItem[] | No | 竞品指标行 |
total_items | integer | No | items 中的行数 |
total_competitors | integer | No | 返回的 active 竞品数量 |
PromptCompetitorMetricItem 字段
| 字段 | 类型 | 可为空 | 描述 |
|---|---|---|---|
date | string | Yes | 日期,格式为 YYYY-MM-DD。当 aggregate_over_time=true 时为 null |
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 来源 |
state | string | Yes | 竞品状态,通常为 active |
is_own_brand | boolean | No | 是否为你的自有品牌 |
visibility | float | Yes | 该竞品在 Prompt 回复中被提及的百分比 |
sentiment | float | Yes | 该竞品的平均情感分 |
position | float | Yes | 该竞品被提及时的平均排名位置 |
sov | float | Yes | Share of voice:该竞品提及次数占所有品牌提及次数的比例 |
mention_count | integer | No | 该竞品被提及的 Prompt 回复数量 |
total_responses | integer | No | 该日期或周期内的 Prompt 回复总数 |
total_brand_mentions | integer | No | 该日期或周期内的全部品牌提及总数 |
sentiment_count | integer | No | 参与计算 sentiment 的观测数量 |
position_count | integer | No | 参与计算 position 的观测数量 |
days_with_data | integer | No | 该竞品被提及的天数 |
days_with_responses | integer | No | 有 Prompt 回复的天数 |
当
aggregate_over_time=true 时,date 为 null,每一行代表整个 period 的聚合结果。当 aggregate_over_time=false 时,items 会包含每个日期、每个竞品各一行。如果该日期或周期内有 Prompt 回复但某竞品未被提及,visibility 为 0.0;如果该日期或周期内没有 Prompt 回复,visibility 为 null。sentiment、position 和 sov 在没有可用观测或分母时为 null。AI 回复(chats)
GET /projects/{project_id}/prompts/{prompt_id}/chats
查询参数
与 搜索词分析 相同。- cURL
- Python
- Node.js(服务端)
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 | 按品牌名称为键的情感分析评分 |
| 字段 | 类型 | 描述 |
|---|---|---|
name | string | 出现在回复中的品牌名称 |
icon_url | string | 主要 logo URL |
icon_urls | string[] | 多个 logo URL 来源 |
| 字段 | 类型 | 描述 |
|---|---|---|
title | string | 引用标题 |
link | string | 引用 URL |
snippet | string | 引用摘要文本 |
reference_index | integer | 引用在回复中的位置 |
域名
GET /projects/{project_id}/prompts/{prompt_id}/domains
查询参数
与 搜索词分析 相同。- cURL
- Python
- Node.js(服务端)
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 来源 |
| 字段 | 类型 | 描述 |
|---|---|---|
name | string | 品牌名称 |
icon_url | string | 主要 logo URL |
icon_urls | string[] | 多个 logo URL 来源 |
URL
GET /projects/{project_id}/prompts/{prompt_id}/urls
查询参数
与 搜索词分析 相同。- cURL
- Python
- Node.js(服务端)
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 | 最近被引用的日期 |
生成建议搜索词
POST /projects/{project_id}/prompts/suggested
请求体
此生成端点当前使用 camelCase 请求和响应字段。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
count | integer | 否 | 生成数量,范围 1-50;默认为项目批次大小 |
generationMethod | string | 否 | 目前仅支持 keyword_seo_v1 |
idempotencyKey | string | 否 | 重试时复用相同值以避免重复创建 |
functionAnalysis | string | 否 | 用于引导生成的预计算站点分析 |
curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/suggested" \
-H "X-API-Key: tk_live_..." \
-H "Content-Type: application/json" \
-d '{"count":10,"generationMethod":"keyword_seo_v1","idempotencyKey":"suggest-2026-07-13"}'
响应
{
"code": 200,
"message": "200 OK",
"data": {
"projectId": "a1b2c3d4-...",
"queuedCount": 10,
"createdCount": 10,
"totalSuggested": 10,
"prompts": [
{
"promptId": "e5f6a7b8-...",
"content": "",
"promptType": "Suggested",
"generationMethod": "keyword_seo_v1",
"createdAt": "2026-07-13T12:00:00+00:00"
}
],
"message": "10 suggested prompt generation(s) queued."
}
}
GET /projects/{project_id}/prompts,并筛选 promptType=Suggested 以观察占位内容填充进度。
生成 URL 推荐
POST /projects/{project_id}/prompts/url-recommendations
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
urls | string[] | 是 | 一到五个目标 URL |
count | integer | 否 | 推荐数量,范围 1-20;默认 5 |
curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/url-recommendations" \
-H "X-API-Key: tk_live_..." \
-H "Content-Type: application/json" \
-d '{"urls":["https://acme.com/pricing"],"count":5}'
响应
{
"code": 200,
"message": "200 OK",
"data": {
"projectId": "a1b2c3d4-...",
"urlsProvided": 1,
"dbMatches": 0,
"placeholdersCreated": 5,
"message": "URL-recommendations generation started."
}
}
promptType=UrlRecommended。公共 API 有意不提供搜索词删除和占位清理操作。