> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜索词

> 创建、更新并获取已跟踪的搜索词及其分析数据、AI 回复、域名和 URL。

搜索词是 Topify.ai 每天在所有 AI 服务商上跟踪的 AI 搜索查询。每个搜索词会生成回复，并被分析以衡量品牌可见度、情感分析、引用和竞争对手提及情况。

API 支持创建、更新和获取搜索词。公共 API 有意不提供删除搜索词的端点。API 密钥由团队管理员签发。

## 列出搜索词

```
GET /projects/{project_id}/prompts
```

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

### 路径参数

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts")
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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 |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/prompts/{prompt_id}" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}")
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}`, { headers });
    ```
  </Tab>
</Tabs>

***

## 创建搜索词

```
POST /projects/{project_id}/prompts
```

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

<Warning>
  API 密钥由管理员创建，目前对整个团队拥有完整权限。创建搜索词前请确认项目和搜索词文本。
</Warning>

### 路径参数

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

### 请求体

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.post(f"/projects/{project_id}/prompts", json={
        "prompts": ["What is the best project management tool?"],
        "topicId": topic_id,
        "country": "US",
    })
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    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",
      }),
    });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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}
```

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

<Warning>
  API 密钥由管理员创建，目前对整个团队拥有完整权限。更新搜索词前请确认项目和字段。
</Warning>

### 路径参数

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

### 请求体

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

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.patch(f"/projects/{project_id}/prompts/{prompt_id}", json={
        "content": "Best project management tools for remote teams",
    })
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    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" }),
    });
    ```
  </Tab>
</Tabs>

### 响应

返回更新后的搜索词及其全部字段（与 [获取搜索词](#get-prompt) 形状相同）。

### 错误响应

| 状态    | 原因                      |
| ----- | ----------------------- |
| `400` | 请求体为空、内容只有空白字符，或没有字段被修改 |
| `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 服务商筛选    |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/analytics", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/analytics?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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 服务商在该日期的指标值       |

***

## 单个 Prompt 的竞品指标

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

返回某一个 Prompt 下所有 active 竞品的指标。这个接口适合导出单个 Prompt 里的各品牌 visibility、sentiment、position 和 share of voice，不需要在控制台里逐个打开 Prompt 详情页。

结果会根据所选 Prompt 和时间范围内的原始 AI 回复实时计算。

### 路径参数

| 参数           | 类型            | 描述        |
| ------------ | ------------- | --------- |
| `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` 返回每个日期、每个竞品一行。 |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(
        f"/projects/{project_id}/prompts/{prompt_id}/competitors",
        params={"duration_days": 7, "aggregate_over_time": False},
    )
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(
      `${BASE}/projects/${projectId}/prompts/${promptId}/competitors?duration_days=7&aggregate_over_time=false`,
      { headers }
    );
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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 回复的天数                                             |

<Note>
  当 `aggregate_over_time=true` 时，`date` 为 `null`，每一行代表整个 `period` 的聚合结果。当 `aggregate_over_time=false` 时，`items` 会包含每个日期、每个竞品各一行。如果该日期或周期内有 Prompt 回复但某竞品未被提及，`visibility` 为 `0.0`；如果该日期或周期内没有 Prompt 回复，`visibility` 为 `null`。`sentiment`、`position` 和 `sov` 在没有可用观测或分母时为 `null`。
</Note>

***

## AI 回复（chats）

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

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

### 查询参数

与 [搜索词分析](#prompt-analytics) 相同。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/chats", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/chats?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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
```

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

### 查询参数

与 [搜索词分析](#prompt-analytics) 相同。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/domains", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/domains?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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 级别的引用数据，按提及次数降序排列。

### 查询参数

与 [搜索词分析](#prompt-analytics) 相同。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/prompts/{prompt_id}/urls", params={"duration_days": 7})
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/prompts/${promptId}/urls?duration_days=7`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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  | 最近被引用的日期               |

***

## 生成建议搜索词

```http theme={null}
POST /projects/{project_id}/prompts/suggested
```

立即创建占位搜索词，并通过后台 Semrush、DataForSEO 和 LLM 流程填充内容。生成通常需要 30-90 秒。

### 请求体

<Note>
  此生成端点当前使用 camelCase 请求和响应字段。
</Note>

| 字段                 | 类型      | 必填 | 说明                     |
| ------------------ | ------- | -- | ---------------------- |
| `count`            | integer | 否  | 生成数量，范围 1-50；默认为项目批次大小 |
| `generationMethod` | string  | 否  | 目前仅支持 `keyword_seo_v1` |
| `idempotencyKey`   | string  | 否  | 重试时复用相同值以避免重复创建        |
| `functionAnalysis` | string  | 否  | 用于引导生成的预计算站点分析         |

```bash theme={null}
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"}'
```

### 响应

```json theme={null}
{
  "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 推荐

```http theme={null}
POST /projects/{project_id}/prompts/url-recommendations
```

为一到五个目标 URL 创建搜索词推荐。返回占位搜索词后，现有匹配检查和新候选生成会继续在后台运行。

### 请求体

| 字段      | 类型        | 必填 | 说明                |
| ------- | --------- | -- | ----------------- |
| `urls`  | string\[] | 是  | 一到五个目标 URL        |
| `count` | integer   | 否  | 推荐数量，范围 1-20；默认 5 |

```bash theme={null}
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}'
```

### 响应

```json theme={null}
{
  "code": 200,
  "message": "200 OK",
  "data": {
    "projectId": "a1b2c3d4-...",
    "urlsProvided": 1,
    "dbMatches": 0,
    "placeholdersCreated": 5,
    "message": "URL-recommendations generation started."
  }
}
```

轮询搜索词列表并筛选 `promptType=UrlRecommended`。公共 API 有意不提供搜索词删除和占位清理操作。