> ## 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 回复中被引用的聚合来源域名。

来源是 AI 服务商在回答跟踪的搜索词时所引用的域名。此端点在域名级别聚合项目中所有搜索词的引用数据。

## 列出来源

```
GET /projects/{project_id}/sources
```

返回带有引用次数的来源域名，分页并按 `reference_count` 降序排列。

### 路径参数

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

### 查询参数

| 参数              | 类型      | 默认值  | 描述                 |
| --------------- | ------- | ---- | ------------------ |
| `page`          | integer | `1`  | 页码（从 1 开始）         |
| `page_size`     | integer | `50` | 每页结果数（最小 1，最大 100） |
| `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}/sources?page=1&page_size=50&duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/sources", params={"page": 1, "page_size": 50, "duration_days": 7})
    ```
  </Tab>

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

### 响应

```json theme={null}
{
  "success": true,
  "data": [
    {
      "source_id": "s1t2u3v4-...",
      "domain": "techcrunch.com",
      "category": 1,
      "reference_count": 127
    },
    {
      "source_id": "w5x6y7z8-...",
      "domain": "forbes.com",
      "category": 1,
      "reference_count": 89
    }
  ]
}
```

### SourceDomainResponse 字段

| 字段                | 类型            | 可空 | 描述               |
| ----------------- | ------------- | -- | ---------------- |
| `source_id`       | string (UUID) | No | 来源 ID            |
| `domain`          | string        | No | 域名               |
| `category`        | integer       | No | 域名类别 ID          |
| `reference_count` | integer       | No | 日期范围内所有搜索词的总引用次数 |

<Note>
  此端点的 `data` 字段是一个扁平数组（未包装在对象中）。分页中不包含 `total` 计数 —— 请持续获取页面直到返回空数组为止。
</Note>

***

## 获取来源详情

```http theme={null}
GET /projects/{project_id}/sources/{domain}/detail
```

返回一个来源域名的引用统计、热门被引用 URL 和引用该来源的搜索词。

### 查询参数

| 参数              | 类型      | 默认值  | 说明                 |
| --------------- | ------- | ---- | ------------------ |
| `duration_days` | integer | `7`  | 未提供明确日期时的回溯窗口      |
| `date_from`     | string  | --   | 开始日期（`YYYY-MM-DD`） |
| `date_to`       | string  | --   | 结束日期（`YYYY-MM-DD`） |
| `providers`     | string  | --   | 逗号分隔的服务商筛选条件       |
| `page`          | integer | `1`  | URL 和搜索词列表使用的页码    |
| `page_size`     | integer | `20` | 每个列表的条目数，最大 100    |

```bash theme={null}
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/sources/techcrunch.com/detail?duration_days=30" \
  -H "X-API-Key: tk_live_..."
```

响应包含 `stats`、分页的 `urls` 对象和分页的 `prompts` 对象。每个分页对象都包含 `page`、`page_size`、`total` 和 `items`。

***

## 列出来源聊天

```http theme={null}
GET /projects/{project_id}/sources/{domain}/chats
```

返回引用了指定域名的 AI 回复。

### 查询参数

| 参数              | 类型      | 默认值  | 说明                 |
| --------------- | ------- | ---- | ------------------ |
| `duration_days` | integer | `7`  | 未提供明确日期时的回溯窗口      |
| `date_from`     | string  | --   | 开始日期（`YYYY-MM-DD`） |
| `date_to`       | string  | --   | 结束日期（`YYYY-MM-DD`） |
| `providers`     | string  | --   | 逗号分隔的服务商筛选条件       |
| `page`          | integer | `1`  | 页码                 |
| `page_size`     | integer | `10` | 每页结果数，最大 50        |

```bash theme={null}
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/sources/techcrunch.com/chats?providers=chatgpt&page=1&page_size=10" \
  -H "X-API-Key: tk_live_..."
```

每条聊天记录都包含服务商、模型、搜索词、预览、完整回复内容、检测到的品牌和情感分析数据以及引用。