Skip to main content
The public API gives programmatic, read-only access to your GEO analytics data. Use it to build dashboards, integrate with BI tools, or power custom workflows on top of your Topify.ai projects.
AI agents (Claude Code, Cursor, OpenClaw): Topify.ai supports fully programmatic setup — no browser or email verification required. To create an account, get an API key, and start a brand tracking project in three API calls, see Agentic setup. The only user input needed is an email address. The endpoints documented below are for querying data after setup is complete.

​
Base URL

https://topify-customer-api-production.up.railway.app/api/public/v1
All endpoint paths in this reference are relative to this base URL.

​
Authentication

Every request requires an API key in the X-API-Key header. See authentication for details. 
X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Response envelope

Data endpoints wrap every response in a standard envelope: Success: 
{
  "success": true,
  "data": { ... }
}
Error: 
{
  "detail": "Description of what went wrong"
}
The agentic setup endpoints (/account/*) use a different envelope: {"code": 200, "message": "200 OK", "data": {...}} for success and {"code": 400, "message": "..."} for errors. See the agentic setup page for details.

​
HTTP status codes

CodeMeaning
200Success
401Unauthorized — missing, invalid, inactive, or expired API key
403Forbidden — API key does not have access to this project
404Not found — project, prompt, or resource does not exist
429Rate limit exceeded — see Retry-After header

​
Date range filtering

Most analytics endpoints accept these query parameters:
ParamTypeDefaultDescription
duration_daysinteger7Number of days to look back from today
date_fromstring—Start date in YYYY-MM-DD format
date_tostring—End date in YYYY-MM-DD format
If both duration_days and date_from/date_to are provided, the explicit date range takes precedence. Maximum range is 90 days.

​
Provider filtering

Analytics endpoints accept a providers query parameter: 
?providers=chatgpt,perplexity
Supported values: chatgpt, perplexity, google_ai_overview. Omitting returns data from all providers.

​
Pagination

Endpoints with large result sets support page-based pagination:
ParamTypeDefaultMaxDescription
pageinteger1—Page number (starts at 1)
page_sizeinteger50100Results per page

​
Rate limit headers

Every response includes these headers:
HeaderDescription
X-RateLimit-LimitTotal requests allowed per window
X-RateLimit-RemainingRequests remaining in the current window
X-Credit-AvailableAPI credits remaining on your key
Retry-AfterSeconds to wait before retrying (only on 429)

​
Agentic setup

Agentic setup

End-to-end programmatic setup for AI agents — create accounts, get API keys, and provision GEO tracking projects without human intervention.

​
Endpoints

Projects

List and retrieve tracked projects.

Prompts

Prompts, analytics, AI responses, domains, and URLs.

Competitors

Competitor brands with aggregated metrics.

Sources

Source domains cited in AI responses.

Topics

Topic groups that organize prompts.

Overview

Per-prompt aggregated analysis.

Visibility trends

Time-series competitor metrics over time.

Sources analytics

Category breakdown, performance trends, and opportunities.