> ## 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.

# 公共 API

> Topify.ai 公共 API 的参考文档。

公共 API 可用于读取 GEO 分析数据并运行经授权的项目工作流，包括创建搜索词、审核竞争对手、执行操作、管理记录的 URL、生成报告和测试集成。

<Tip>
  **AI 智能体（Claude Code、Cursor、OpenClaw）：** 请使用用户明确提供或授权的账户信息。API 密钥只能由团队管理员创建，并且目前对整个团队拥有完整权限。请参阅 [智能体化设置](/api-reference/agentic-setup)。
</Tip>

## 基础 URL

```
https://topify-customer-api-production.up.railway.app/api/public/v1
```

本参考中的所有端点路径均相对于此基础 URL。

## 认证

每个请求都需要在 `X-API-Key` 请求头中提供 API 密钥。详情请参阅 [认证](/api-reference/authentication)。

<Warning>
  仅从受信任的服务端代码使用 API 密钥。当前密钥可以访问团队拥有的所有项目，因此切勿在浏览器、客户端应用、日志、提示词或聊天记录中暴露密钥。
</Warning>

```
X-API-Key: tk_live_<your-key>
```

## 响应封装

大多数客户 API 端点使用以下响应封装：

**成功：**

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

**错误：**

```json theme={null}
{
  "detail": "Description of what went wrong"
}
```

<Note>
  某些设置和写入操作（包括 `/account/*`、搜索词写入和生成、记录的 URL）使用 `{"code": 200, "message": "200 OK", "data": {...}}`。报告端点返回 HTML。解析响应前请查看各端点的响应示例。
</Note>

## HTTP 状态码

| 状态码   | 含义                              |
| ----- | ------------------------------- |
| `200` | 成功                              |
| `401` | 未授权 —— API 密钥缺失、无效、未激活或已过期      |
| `403` | 禁止访问 —— API 密钥无权访问此项目           |
| `404` | 未找到 —— 项目、搜索词或资源不存在             |
| `429` | 超出速率限制 —— 请参阅 `Retry-After` 请求头 |

## 日期范围筛选

大多数分析端点接受以下查询参数：

| 参数              | 类型      | 默认值 | 描述                    |
| --------------- | ------- | --- | --------------------- |
| `duration_days` | integer | `7` | 从今天起回溯的天数             |
| `date_from`     | string  | --  | 起始日期，格式为 `YYYY-MM-DD` |
| `date_to`       | string  | --  | 结束日期，格式为 `YYYY-MM-DD` |

如果同时提供 `duration_days` 和 `date_from`/`date_to`，则显式日期范围优先。最大范围为 90 天。

## AI 服务商筛选

分析端点接受 `providers` 查询参数：

```
?providers=chatgpt,perplexity,gemini
```

支持的值：`chatgpt`、`perplexity`、`google_ai_overview`、`gemini`、`claude`。省略时会返回所有 AI 服务商的数据。

## 分页

返回大量结果的端点支持基于页码的分页：

| 参数          | 类型      | 默认值  | 最大值   | 描述         |
| ----------- | ------- | ---- | ----- | ---------- |
| `page`      | integer | `1`  | --    | 页码（从 1 开始） |
| `page_size` | integer | `50` | `100` | 每页结果数      |

## 速率限制请求头

每个响应都会包含以下请求头：

| 请求头                     | 描述                      |
| ----------------------- | ----------------------- |
| `X-RateLimit-Limit`     | 每个时间窗口内允许的总请求数          |
| `X-RateLimit-Remaining` | 当前窗口内剩余的请求数             |
| `X-Credit-Available`    | 您的密钥剩余的 API 额度          |
| `Retry-After`           | 重试前需等待的秒数（仅在 `429` 时返回） |

## 智能体化设置

<Columns cols={2}>
  <Card title="智能体化设置" icon="robot" href="/api-reference/agentic-setup" tag="AI 智能体">
    用户明确授权身份、团队和项目详情后，设置账户与项目。
  </Card>
</Columns>

## 端点

<Columns cols={2}>
  <Card title="项目" icon="folder" href="/api-reference/projects">
    列出并获取已跟踪的项目。
  </Card>

  <Card title="品牌别名" icon="link" href="/api-reference/aliases">
    管理用于品牌识别的备用名称。
  </Card>

  <Card title="记录的 URL" icon="bookmark" href="/api-reference/recordings">
    管理用于搜索词发现的 URL 输入。
  </Card>

  <Card title="搜索词" icon="message-lines" href="/api-reference/prompts">
    搜索词、分析数据、AI 回复、域名和 URL。
  </Card>

  <Card title="竞争对手" icon="users" href="/api-reference/competitors">
    带有聚合指标的竞争对手品牌。
  </Card>

  <Card title="来源" icon="newspaper" href="/api-reference/sources">
    AI 回复中引用的来源域名。
  </Card>

  <Card title="主题" icon="tags" href="/api-reference/topics">
    用于组织搜索词的主题分组。
  </Card>

  <Card title="概览" icon="chart-mixed" href="/api-reference/overview">
    按搜索词聚合的分析数据。
  </Card>

  <Card title="可见度趋势" icon="chart-line" href="/api-reference/visibility">
    随时间变化的竞争对手指标时间序列。
  </Card>

  <Card title="来源分析" icon="chart-pie" href="/api-reference/sources-analytics">
    类别分布、表现趋势及机会点。
  </Card>

  <Card title="报告" icon="file-lines" href="/api-reference/reports">
    生成独立的 HTML 可见度报告。
  </Card>

  <Card title="操作" icon="list-check" href="/api-reference/actions">
    审核建议、执行工作流并获取产物。
  </Card>

  <Card title="智能体设置" icon="robot" href="/api-reference/agent-settings">
    测试发布集成凭证。
  </Card>

  <Card title="Webhook" icon="webhook" href="/api-reference/webhooks">
    接收操作和项目生命周期事件。
  </Card>
</Columns>