# GenRank — AI Visibility Index by Category

> GenRank measures how strongly leading AI models recommend brands, products,
> people, and other entities. A curated set of ranking questions per category
> is sent monthly to web-search-capable models — one per major provider
> (OpenAI, Anthropic, Google, xAI, Perplexity) — with web search enabled so
> answers reflect up-to-date information. GenRank aggregates them into a
> weighted visibility score so you can see, per category, what AI recommends.
> Methodology & versioned changelog: https://www.genrank.com/methodology

This is a read-only public API. No API key, no signup — just GET.

## Key Concepts

- **Category**: A hierarchical bucket (e.g., Software > Developer Tools) that
  holds a curated set of ranking questions. Builders pick a category and read
  its rankings.
- **Entity**: Anything rankable — a company, product, person, place, etc.
- **GenRank Score**: A weighted visibility score. Higher rank position in AI
  answers and higher model market share => higher score.
- **Refresh cadence**: AI models are polled **once per month** (1st, UTC).
  Treat this as a monthly index, not real-time. `last_polled_at` in
  `/api/rankings` tells you the latest poll time.

Questions are curated per category by GenRank — there is no public question
submission and no comment/reply API. This API is strictly read-only.

Each language is a fully independent ecosystem: questions, entities, and
scores never mix across languages. Supported languages: English, Korean.
Use the `language` param to select one; results are that language only.

## Base URL

    https://www.genrank.com

Note: "www.genrank.com" is canonical. The apex "genrank.com" redirects (HTTP
307) to "www" with the path preserved, so it also works for any client that
follows redirects — but prefer "www" to skip the extra hop.

## Authentication

None. All endpoints below are public GET requests. Responses are cached, and
CORS is open (`Access-Control-Allow-Origin: *`) so you can call directly from
browsers (badges, widgets, dashboards).

## Endpoints

### GET /api/categories
Category tree — the entrypoint. Discover category ids/slugs to query rankings.
Params:
- locale (optional): translate category names (e.g., ko, ja)
- tree (true|false, default true): nested tree vs flat list

Response: { categories: [{ id, slug, name, level, parent_id, display_order,
children? }], count }

### GET /api/categories/{id_or_slug}/questions
List the curated questions polled inside a category. Useful for drilling from
a category into its individual ranked questions.
Params:
- id_or_slug (path, required): category UUID **or** slug

Response: { questions: [{ id, text, slug, language, description }] }

### GET /api/rankings
Entities ranked by GenRank score for a category (aggregated across its
sub-categories). Omit `category` for an all-categories view.
Params:
- category (optional): category UUID **or** slug
- language (optional): filter entities by language (e.g., en, ko)
- page (default 1), limit (1-100, default 50)

Response: { categoryId, last_polled_at, rankings: [{ entity_id, entity_name,
entity_type, genrank_score, rank, change }], pagination: { page, limit,
totalCount, totalPages, hasNextPage, hasPreviousPage } }

### GET /api/rankings/history
Weekly leaderboard history for a single question — every entity that was in
the top N in any week, with their rank/score per week. For per-question
trend charts.
Params:
- question (required): question UUID
- limit (1-20, default 10): top N entities to track across weeks

Response: { questionId, weeks: [{ id, date, label }], entities: [{ entityId,
entityName, history: [{ weekId, weekDate, rank, genrankScore }], currentRank,
currentScore, rankChange }] }

### GET /api/search
Look up entities (and published questions) by name. **Start here when you
only have a brand name and need its entity id.**
Params:
- q (required): substring, 1-200 chars (case-insensitive)
- limit (1-20, default 5)
- language (optional): restrict question results to one language

Response: { questions: [{ id, text, slug, type: "question" }],
entities: [{ id, name, entityType, type: "entity" }] }

### GET /api/entities/{id}
Entity details and its GenRank score per published question.

Response: { entity: { id, name, type, description, canonical_name },
rankings: [{ question_id, question_text, question_slug, score }] }

### GET /api/entities/{id}/history
Monthly ranking history for an entity — for trend / "movers" analysis.
Params:
- question (optional): limit history to one question

Response: { entityId, entityName, history: [{ pollRunId, pollDate, rank,
genrankScore, weightedScore, rawScore, questionId }], stats: { currentRank,
currentScore, rankChange, scoreChange, totalDataPoints } }

### GET /api/questions/{id}
Question detail: the question itself plus the latest raw AI responses (with
the extracted entities and their scores per model).

Response: { question: { id, text, slug, language, ... },
responses: [{ id, response_text, polled_at, model_name,
entities: [{ id, name, type, rank, score }] }] }

### GET /api/questions/{id}/related
Related questions surfaced by shared category and shared top entities.
Params:
- limit (1-10, default 5)

Response: { related: [{ id, text, slug, vote_score, comment_count, created_at,
language }] }

### GET /api/docs
This documentation as structured JSON. (Also at /api/agent/docs.)

## Typical Workflow

1. **Find your brand**: GET /api/search?q=<name> — get its entity id
2. **See where it ranks**: GET /api/entities/{id} — score per question
3. **Track over time**: GET /api/entities/{id}/history — monthly change
4. **Or start from a category**: GET /api/categories →
   /api/rankings?category=<id|slug> → /api/categories/{id|slug}/questions
   for the questions feeding that ranking

## What You Can Build

- AI visibility / GEO monitor: track a brand's rank per category over time
- Competitive share-of-AI-voice dashboards
- "Does AI recommend my product?" checker bots / widgets
- Market-research brief generators (category => AI-consensus top entities)
- Trend / movers agents using the monthly history endpoint
- Embeddable "AI Rank" badges for company sites

## Error Format

All errors return: { "error": "message", "code": "ERROR_CODE" }
Codes: VALIDATION_ERROR (400), NOT_FOUND (404), GONE (410), INTERNAL_ERROR (500)