Web Index

list_niche_entries

List ranking entries, optionally filtered and paginated. Returns domain, country, category, ranks, traffic, and AI fields (ai_category, ai_rating, ai_summary). web_content is excluded for brevity.

get_niche_entry

Get a single ranking entry by ID, including its cached web_content if available

update_niche_entry

Update a ranking entry's AI analysis fields: ai_category, ai_rating (1-10), ai_summary, and optionally category/notes

fetch_website_content

Fetch and extract text content from a website URL for analysis. Saves the content to the ranking entry if entry_id is provided.

get_niche_stats

Get aggregated statistics about niche entries: total count, average AI rating, rated count, and a breakdown of entries per AI category.

bulk_update_niche_entries

Bulk update AI fields for multiple niche entries by IDs

delete_niche_entry

Delete a niche entry by ID.

compare_niche_entries

Compare two or more niche entries side by side by IDs. Returns all fields for comparison.

get_ranking_overview_stats

Aggregated counts of tracked domains, services, and countries for the Overview/KPI strip.

get_top_domains

Paginated list of the top-ranked domain entries for the Overview tab.

get_top_services

Paginated list of the top-ranked online-service entries for the Overview tab.

get_trending

Entries with the largest rank changes for the given period ('daily' or 'weekly').

get_ranking_data_sources

List the available ranking feeds (sources) with entry counts and latest snapshot.

get_niche_filters

Distinct countries and categories available in the current scope, for populating filter dropdowns.

import_niche_csv

Import a rankings CSV (header row expected; required column: domain). Returns the number of rows inserted.

bulk_delete_niche_entries

Delete multiple niche entries by IDs. Returns the number of rows deleted.

bulk_update_niche_field

Bulk update a single text field (category, country, notes, ai_category, ai_summary) on multiple entries.

fetch_niche_web_content

Fetch a domain's homepage content, cache it on the entry, and return the extracted text. Used by the Data tab 'fetch content' action.

clear_niche_entries

Delete ALL niche entries in the current scope (user or workspace). Irreversible.

export_rankings_csv

Export the current scope's rankings as CSV text, optionally filtered by country/entry_type/snapshot_date.

get_domain_history

Rank-over-time series for a single domain across every snapshot in scope. Each point has snapshot_date, global_rank, country_rank, traffic_estimate, rank_change, previous_rank. Ordered oldest → newest so the chart x-axis is chronological.

get_biggest_movers

Domains with the largest aggregate rank movement across the latest N snapshots. Each row has domain, country, best_rank, latest_rank, total_change (most-recent rank_change in the window), and snapshots (how many snapshots it appeared in). Ordered by |total_change| descending.

list_explorer_rows

Browse the global website-ranking dataset (latest snapshot). For 'All countries' (country=null), collapses every country series into one row per domain: `traffic_estimate` is the SUM across all countries and `countries` is the full ordered list of countries that have the domain (biggest markets first), default-sorted by traffic DESC. When a country is selected, returns that country's full ranked series (traffic is that country's number, countries is a one-element list). Server-side paginated + sorted (the 'All countries' aggregate is cached for ~60s). Supports a multi-select category filter (categories[], — OR semantics), a category-filter-mode (not_null = has a category, null = no category), a build-target-only toggle (only rows the AI marked as viable adjacent build angles), and a min-rating threshold.

list_explorer_countries

Distinct countries present in the latest ranking snapshot, with entry counts, for the explorer's country dropdown. Ordered by entry count descending so the biggest markets surface first.

list_explorer_categories

Distinct categories present in the latest ranking snapshot, for the explorer's category filter dropdown. Ordered alphabetically. Mirrors list_explorer_countries so the dropdown only offers categories the explorer grid can actually show.

list_explorer_ai_categories

Distinct AI-assigned categories (ai_category) present in the latest ranking snapshot, for the explorer's multi-select category filter. Ordered alphabetically. Use this when the user wants to filter by the AI-derived category (e.g. 'Streaming & Video', 'Real Estate') rather than the raw imported `category`.

list_competition_entries

List scored competitor entries from the owner's competition analysis. Each row has a difficulty level (Trivial/Easy/Moderate/Hard/Very Hard), a 1-10 difficulty score, an internal rank (1 = easiest target), a category, a one-sentence 'what_it_does', the 6 scoring factors, and a rationale. Filterable by category, difficulty level, and domain search; supports a category filter mode for with-category / without-category views.

get_competition_filters

Distinct categories and difficulty levels present in the competition analysis dataset, for populating the Compete tab's filter dropdowns.

get_competition_shortlist

The owner's competable shortlist: easiest-first ranked competitors, excluding out-of-scope categories (Adult) and unwinnable Very Hard giants. This is the curated set of products the owner can realistically build a competing product against.

list_build_target_clusters

List build target clusters — prescriptive product opportunities. Each cluster = ONE product we'd build that displaces MULTIPLE existing sites (the competitor set). When country is null, aggregates same-named clusters across all countries (competitor_count becomes the SUM across markets, country_count is the number of distinct markets — a strong 'build once, ship across markets' signal). Sort: competitor_count DESC, then min_rank ASC (biggest traffic-weight clusters first). Populated by scripts/backfill_build_target_clusters.py from the raw ai_build_target flag + ai_subcategory on niche_entries.

get_build_target_cluster

Get one build target cluster by id — full detail including the FULL competitor_domains array (no 50-cap that the list endpoint applies).

list_build_target_cluster_countries

Distinct countries that have at least one build target cluster, with cluster counts. For the Build Targets tab country dropdown.