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

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

<Tip>
  **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](/api-reference/agentic-setup). The only user input needed is an email address. The endpoints documented below are for querying data after setup is complete.
</Tip>

## 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](/api-reference/authentication) for details.

```
X-API-Key: tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Response envelope

Data endpoints wrap every response in a standard envelope:

**Success:**

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

**Error:**

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

<Note>
  The [agentic setup](/api-reference/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.
</Note>

## 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,gemini
```

Supported values: `chatgpt`, `perplexity`, `google_ai_overview`, `gemini`, `claude`. 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

<Columns cols={2}>
  <Card title="Agentic setup" icon="robot" href="/api-reference/agentic-setup" tag="AI Agents">
    End-to-end programmatic setup for AI agents -- create accounts, get API keys, and provision GEO tracking projects without human intervention.
  </Card>
</Columns>

## Endpoints

<Columns cols={2}>
  <Card title="Projects" icon="folder" href="/api-reference/projects">
    List and retrieve tracked projects.
  </Card>

  <Card title="Prompts" icon="message-lines" href="/api-reference/prompts">
    Prompts, analytics, AI responses, domains, and URLs.
  </Card>

  <Card title="Competitors" icon="users" href="/api-reference/competitors">
    Competitor brands with aggregated metrics.
  </Card>

  <Card title="Sources" icon="newspaper" href="/api-reference/sources">
    Source domains cited in AI responses.
  </Card>

  <Card title="Topics" icon="tags" href="/api-reference/topics">
    Topic groups that organize prompts.
  </Card>

  <Card title="Overview" icon="chart-mixed" href="/api-reference/overview">
    Per-prompt aggregated analysis.
  </Card>

  <Card title="Visibility trends" icon="chart-line" href="/api-reference/visibility">
    Time-series competitor metrics over time.
  </Card>

  <Card title="Sources analytics" icon="chart-pie" href="/api-reference/sources-analytics">
    Category breakdown, performance trends, and opportunities.
  </Card>
</Columns>