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.
Claude Code 使用 tool_use 直接从 Claude Code 调用以下端点。
Cursor Cursor 的智能体模式可以通过 HTTP 请求调用这些端点。
OpenClaw 任何具备工具调用能力的 LLM 智能体都可以完成此流程。
这些端点使 AI 智能体能够从零开始设置 Topify.ai 并生成完整的 GEO 可见度报告 —— 整个过程无需最终用户访问浏览器、验证邮箱或操作仪表盘。
完整流程包含三次 API 调用：
创建账户 —— 使用邮箱注册，立即获取凭证获取 API 密钥 —— 用凭证换取 API 密钥创建项目 —— 启动品牌跟踪并通过 webhook 接收结果
如果用户提供了邮箱地址，请使用它。如果没有，您（智能体）应自行生成临时邮箱 ，使用 temp-{random}@topify.ai 格式 —— 只需创建一个随机十六进制字符串（例如 temp-a8f3b1c9@topify.ai）并将其传递给创建账户端点。服务端不会为您生成此邮箱。这样可以创建一个完全可用的匿名账户，无需用户任何输入。用户之后可以从仪表盘绑定真实邮箱。
这些端点专为可以程序化发起 HTTP 请求的 工具调用 AI 智能体 设计，例如 Claude Code、Cursor 和 OpenClaw。如果您使用的是无法直接调用 API 的网页版 AI 聊天机器人（ChatGPT、Perplexity 等），请在 app.topify.ai 手动创建账户和项目，然后使用您的邮箱和密码通过 获取 API 密钥 端点为只读数据端点获取密钥。 额度与速率限制 每个 API 密钥都有一个速率限制等级 和一个月度额度配额 。当项目在引导启动和每日刷新周期中获取 AI 回复时，会消耗额度。
速率限制等级 速率限制使用 60 秒滑动窗口。突发额度允许您短暂超出基础速率。
等级 每分钟请求数 突发 每窗口有效限额 Standard 60 +10 70 Premium 300 +50 350
新创建的 API 密钥处于 standard 等级。如需升级到 premium，请联系我们。
当超出限额时，API 返回 429 Too Many Requests，并附带 Retry-After 请求头指示需要等待的秒数。
各套餐的研究额度 每个套餐都包含一个月度额度预算，决定您的项目可以运行多少次 AI 研究查询。
套餐 月度额度 Skip Trial（API 创建账户的默认套餐） 10 Basic 200 Pro 500 Enterprise 2,000
通过 API 创建的账户默认在 skip_trial 套餐上启动，拥有 10 个额度。每次项目引导启动会按照查询的搜索词和 AI 服务商数量按比例消耗额度（典型情况下 5 个搜索词 × 3 个 AI 服务商 = 完整一次引导启动消耗 15 个额度）。skip_trial 套餐运行精简的引导启动，以适应 10 个额度的预算。如需运行包含全部搜索词和 AI 服务商的完整引导启动，请从 仪表盘 升级到 Basic 套餐或更高，或联系我们。
响应请求头 每个响应都包含速率限制和额度信息：
请求头 描述 X-RateLimit-Limit当前窗口内允许的最大请求数 X-RateLimit-Remaining触发限流前剩余的请求数 X-Credit-Available您的密钥剩余的研究额度 Retry-After距窗口重置的秒数（仅在 429 时）
创建账户 创建一个新的 Topify.ai 账户，并在 skip_trial 套餐下创建一个团队。账户创建后无需邮箱验证，可立即使用。
此端点无需认证。生成的密码仅返回一次，之后无法再次获取 —— 请妥善保管。
请求体 字段 类型 必填 描述 emailstring Yes 新账户的邮箱地址。如有用户邮箱请使用，否则智能体应生成 temp-{random}@topify.ai（随机十六进制字符串）以进行匿名设置 passwordstring No 此字段会被忽略。服务端会生成安全密码
{ "email" : "user@example.com" }
{ "code" : 200 , "message" : "200 OK" , "data" : { "user_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "team_id" : "b2c3d4e5-f6a7-8901-bcde-f12345678901" , "email" : "user@example.com" , "password" : "Tp8f2a1b3c4d5e6f7a8b9c0d1e2f3a4b516384!" } }
响应字段 字段 类型 描述 user_idstring (UUID) 新用户的 ID team_idstring (UUID) 为此账户创建的团队 emailstring 规范化后的邮箱地址 passwordstring 自动生成的密码。请妥善保管
状态 详情 原因 400A valid email is required邮箱为空或缺少 @ 409Failed to create account. The email may already be registered.此邮箱的用户已存在
如果您收到 409： 账户已存在。使用同一邮箱和用户已有密码跳到 获取 API 密钥 步骤。如果不知道密码，请询问用户或引导他们到 app.topify.ai 重置密码。获取 API 密钥 使用邮箱和密码进行认证，然后返回该账户的 API 密钥。如果尚不存在密钥，会自动在 standard 速率限制等级上创建一个。
请求体 字段 类型 必填 描述 emailstring Yes 账户邮箱地址 passwordstring Yes 账户密码（来自创建端点）
{ "email" : "user@example.com" , "password" : "Tp8f2a1b3c4d5e6f7a8b9c0d1e2f3a4b516384!" }
{ "code" : 200 , "message" : "200 OK" , "data" : { "api_key" : "tk_live_214d48ed311144ee850192347ff32a2c" , "team_id" : "b2c3d4e5-f6a7-8901-bcde-f12345678901" , "key_prefix" : "tk_live_214d" , "rate_limit_tier" : "standard" } }
响应字段 字段 类型 描述 api_keystring 完整的 API 密钥。请妥善保管 —— 之后无法再次获取 team_idstring (UUID) 此密钥所属的团队 key_prefixstring 密钥的前 12 个字符，用于标识 rate_limit_tierstring 分配给此密钥的速率限制等级（standard 或 premium）
状态 详情 原因 401Invalid email or password认证失败 500Authentication service unavailableSupabase 认证服务不可用
创建项目 创建一个新的品牌跟踪项目并在后台启动引导流水线。端点会立即返回 202 Accepted 状态，同时流水线异步运行。
引导流水线会生成跟踪搜索词、从所有 AI 服务商获取初始 AI 回复、计算品牌指标并检测竞争对手。完成后，会向您提供的 URL 发送 webhook 回调。
需要通过 X-API-Key 请求头进行 API 密钥认证。
请求体 字段 类型 必填 描述 brand_namestring Yes 要跟踪的品牌名称 brand_urlstring Yes 品牌的网站 URL webhook_urlstring Yes 用于接收完成回调的 URL languagestring No 生成搜索词所用语言（例如 en、ja） locationstring No 目标市场国家代码（例如 US、JP）
{ "brand_name" : "Acme Corp" , "brand_url" : "https://acme.com" , "webhook_url" : "https://your-service.com/webhooks/topify" , "language" : "en" , "location" : "US" }
{ "code" : 202 , "message" : "202 Accepted" , "data" : { "project_id" : "c3d4e5f6-a7b8-9012-cdef-123456789012" , "status" : "initializing" } }
响应字段 字段 类型 描述 project_idstring (UUID) 新项目的 ID statusstring 初始状态。始终为 initializing
Webhook 回调 当引导流水线完成（或失败）时，会向您的 webhook_url 发送一个 POST 请求，载荷如下：
成功： { "event" : "project.bootstrap" , "project_id" : "c3d4e5f6-a7b8-9012-cdef-123456789012" , "status" : "completed" , "error" : null , "timestamp" : "2026-03-10T03:27:35Z" }
失败： { "event" : "project.bootstrap" , "project_id" : "c3d4e5f6-a7b8-9012-cdef-123456789012" , "status" : "error" , "error" : "Failed to generate prompts" , "timestamp" : "2026-03-10T03:27:35Z" }
Webhook 请求头 回调按 Standard Webhooks 规范进行签名。请验证签名以确保回调真实有效。
请求头 描述 webhook-id唯一消息 ID（msg_<uuid>） webhook-timestamp消息发送时的 Unix 时间戳 webhook-signature格式为 v1,<base64-signature> 的 HMAC-SHA256 签名
签名是基于字符串 {webhook-id}.{webhook-timestamp}.{body} 使用您共享的 webhook 签名密钥计算得出的。
状态 详情 原因 400brand_name is required缺失或为空的品牌名称 400brand_url must be a valid URLURL 校验失败 400webhook_url must be a valid URLWebhook URL 校验失败 401Missing X-API-Key header未提供 API 密钥 403You've reached the maximum number of projects...已达到套餐项目数量上限
引导启动完成后 webhook 触发并返回 "status": "completed" 后，您的项目就有数据了。使用以下只读端点（详见 API 参考 ）来获取结果：
端点 返回内容 GET /projects项目列表，含当前品牌指标 GET /projects/{id}/overview按搜索词聚合的分析数据，包含竞争对手提及 GET /projects/{id}/visibility?duration_days=7每日可见度、情感分析和位置趋势 GET /projects/{id}/prompts所有跟踪的搜索词，包含按 AI 服务商的指标 GET /projects/{id}/competitors检测到的竞争对手品牌及其指标 GET /projects/{id}/sourcesAI 服务商引用的域名，按引用次数排序
所有数据端点都需要 X-API-Key 请求头，并以 {"success": true, "data": {...}} 格式返回响应。
要为用户提供快速摘要，请先调用 GET /projects 获取品牌的整体可见度评分和情感分析，然后调用 GET /projects/{id}/overview 获取按搜索词的细分。
完整工作流示例 整个设置可以端到端运行，无需任何人工参与。智能体在客户端生成临时邮箱（temp-{random}@topify.ai）或使用用户的邮箱 —— 无论哪种方式都不需要输入。
# 1. Create an account curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/account/create" \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com"}' # 2. Get an API key (use the password from step 1) curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/account/api-key" \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com", "password": "Tp..."}' # 3. Create a project (use the API key from step 2) curl -X POST "https://topify-customer-api-production.up.railway.app/api/public/v1/account/projects" \ -H "Content-Type: application/json" \ -H "X-API-Key: tk_live_..." \ -d '{ "brand_name": "Acme Corp", "brand_url": "https://acme.com", "webhook_url": "https://your-service.com/webhooks/topify" }' # 4. Query project data after webhook confirms completion curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects" \ -H "X-API-Key: tk_live_..."
import httpx BASE = "https://topify-customer-api-production.up.railway.app/api/public/v1" # 1. Create account resp = httpx.post( f " { BASE } /account/create" , json = { "email" : "user@example.com" , }) account = resp.json()[ "data" ] password = account[ "password" ] # 2. Get API key resp = httpx.post( f " { BASE } /account/api-key" , json = { "email" : "user@example.com" , "password" : password, }) api_key = resp.json()[ "data" ][ "api_key" ] # 3. Create project headers = { "X-API-Key" : api_key} resp = httpx.post( f " { BASE } /account/projects" , json = { "brand_name" : "Acme Corp" , "brand_url" : "https://acme.com" , "webhook_url" : "https://your-service.com/webhooks/topify" , }, headers = headers) project_id = resp.json()[ "data" ][ "project_id" ] print ( f "Project { project_id } is bootstrapping..." ) # 4. After webhook confirms completion, query data resp = httpx.get( f " { BASE } /projects" , headers = headers) print (resp.json())
const BASE = "https://topify-customer-api-production.up.railway.app/api/public/v1" ; // 1. Create account let resp = await fetch ( ` ${ BASE } /account/create` , { method: "POST" , headers: { "Content-Type" : "application/json" }, body: JSON . stringify ({ email: "user@example.com" }), }); const { data : account } = await resp . json (); // 2. Get API key resp = await fetch ( ` ${ BASE } /account/api-key` , { method: "POST" , headers: { "Content-Type" : "application/json" }, body: JSON . stringify ({ email: "user@example.com" , password: account . password , }), }); const { data : keyData } = await resp . json (); // 3. Create project const headers = { "Content-Type" : "application/json" , "X-API-Key" : keyData . api_key , }; resp = await fetch ( ` ${ BASE } /account/projects` , { method: "POST" , headers , body: JSON . stringify ({ brand_name: "Acme Corp" , brand_url: "https://acme.com" , webhook_url: "https://your-service.com/webhooks/topify" , }), }); const { data : project } = await resp . json (); console . log ( `Project ${ project . project_id } is bootstrapping...` ); // 4. After webhook confirms completion, query data resp = await fetch ( ` ${ BASE } /projects` , { headers }); console . log ( await resp . json ());
