跳转到主要内容

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 提供对您的 GEO 分析数据的程序化只读访问。您可以使用它来构建仪表盘、与 BI 工具集成，或在 Topify.ai 项目之上构建自定义工作流。
AI 智能体（Claude Code、Cursor、OpenClaw）： Topify.ai 支持完全程序化的设置 —— 无需浏览器或邮箱验证。要通过三次 API 调用创建账户、获取 API 密钥并启动品牌跟踪项目，请参阅 智能体化设置。唯一需要的用户输入是邮箱地址。下方记录的端点用于在设置完成后查询数据。

​
基础 URL

https://topify-customer-api-production.up.railway.app/api/public/v1
本参考中的所有端点路径均相对于此基础 URL。

​
认证

每个请求都需要在 X-API-Key 请求头中提供 API 密钥。详情请参阅 认证。 
X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
响应封装

数据端点会将每个响应包装在标准的封装结构中： 成功： 
{
  "success": true,
  "data": { ... }
}
错误： 
{
  "detail": "Description of what went wrong"
}
智能体化设置 端点（/account/*）使用不同的封装结构：成功时为 {"code": 200, "message": "200 OK", "data": {...}}，错误时为 {"code": 400, "message": "..."}。详情请参阅智能体化设置页面。

​
HTTP 状态码

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

​
日期范围筛选

大多数分析端点接受以下查询参数：
参数类型默认值描述
duration_daysinteger7从今天起回溯的天数
date_fromstring—起始日期，格式为 YYYY-MM-DD
date_tostring—结束日期，格式为 YYYY-MM-DD
如果同时提供 duration_days 和 date_from/date_to，则显式日期范围优先。最大范围为 90 天。

​
AI 服务商筛选

分析端点接受 providers 查询参数： 
?providers=chatgpt,perplexity,gemini
支持的值：chatgpt、perplexity、google_ai_overview、gemini、claude。省略时会返回所有 AI 服务商的数据。

​
分页

返回大量结果的端点支持基于页码的分页：
参数类型默认值最大值描述
pageinteger1—页码（从 1 开始）
page_sizeinteger50100每页结果数

​
速率限制请求头

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

​
智能体化设置

智能体化设置

面向 AI 智能体的端到端程序化设置 —— 无需人工介入，即可创建账户、获取 API 密钥并配置 GEO 跟踪项目。

​
端点

项目

列出并获取已跟踪的项目。

搜索词

搜索词、分析数据、AI 回复、域名和 URL。

竞争对手

带有聚合指标的竞争对手品牌。

来源

AI 回复中引用的来源域名。

主题

用于组织搜索词的主题分组。

概览

按搜索词聚合的分析数据。

可见度趋势

随时间变化的竞争对手指标时间序列。

来源分析

类别分布、表现趋势及机会点。