Public API

Reference documentation for the Topify.ai public API.

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

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

Date range filtering

Most analytics endpoints accept these query parameters:

Param	Type	Default	Description
duration_days	integer	7	Number of days to look back from today
date_from	string	—	Start date in YYYY-MM-DD format
date_to	string	—	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:

Param	Type	Default	Max	Description
page	integer	1	—	Page number (starts at 1)
page_size	integer	50	100	Results per page

Rate limit headers

Every response includes these headers:

Header	Description
X-RateLimit-Limit	Total requests allowed per window
X-RateLimit-Remaining	Requests remaining in the current window
X-Credit-Available	API credits remaining on your key
Retry-After	Seconds 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.