> ## 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 lets you read GEO analytics and run approved project workflows, including prompt creation, competitor review, action execution, recorded URL management, reports, and integration checks.

<Tip>
  **AI agents (Claude Code, Cursor, OpenClaw):** Use account information explicitly supplied or authorized by the user. API keys can only be created by team admins and currently grant access to the full team. See [Agentic setup](/api-reference/agentic-setup).
</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.

<Warning>
  Use API keys only from trusted server-side code. Current keys grant access to every project owned by the team, so never expose them in a browser, client application, log, prompt, or chat history.
</Warning>

```
X-API-Key: tk_live_<your-key>
```

## Response envelope

Most customer API endpoints use this envelope:

**Success:**

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

**Error:**

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

<Note>
  Some setup and write operations, including `/account/*`, prompt writes and generation, and recorded URLs, use `{"code": 200, "message": "200 OK", "data": {...}}`. The report endpoint returns HTML. Check each endpoint's response example before parsing it.
</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">
    Set up an account and project after the user explicitly authorizes the identity, team, and project details.
  </Card>
</Columns>

## Endpoints

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

  <Card title="Brand aliases" icon="link" href="/api-reference/aliases">
    Manage alternative names used for brand recognition.
  </Card>

  <Card title="Recorded URLs" icon="bookmark" href="/api-reference/recordings">
    Manage URL inputs used for prompt discovery.
  </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>

  <Card title="Reports" icon="file-lines" href="/api-reference/reports">
    Generate self-contained HTML visibility reports.
  </Card>

  <Card title="Actions" icon="list-check" href="/api-reference/actions">
    Review recommendations, execute workflows, and fetch artifacts.
  </Card>

  <Card title="Agent settings" icon="robot" href="/api-reference/agent-settings">
    Test publishing integration credentials.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Receive action and project lifecycle events.
  </Card>
</Columns>