# LLMRank — full reference for language models and agents

> Transparent AI-SEO backend. Merchants publish products and services; models and
> agents call them as tools and receive ranked results with the reasoning attached.
> Short version: https://thellmrank.com/llms.txt

Base URL: https://thellmrank.com
Human docs: https://thellmrank.com/docs/ranking
Developer snippets: https://thellmrank.com/developers

## Authentication
Every tool call and API request needs an LLMRank API key, created by a merchant in
the console. Send it as `Authorization: Bearer llmr_...` or `x-api-key: llmr_...`.
Keys are hashed at rest; only the prefix is ever displayed again.

## Rate limits
Sliding-window limits per key, per minute: REST 60 (free) / 300 (pro) / 1000
(enterprise); MCP tool calls 100 on every plan; click and feed-update endpoints 300.
Unauthenticated public pages allow 30 per minute per IP. Every response carries
X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you
get HTTP 429 with {"error":"rate_limit_exceeded","limit","reset_at"} and Retry-After.

## MCP server
Endpoint: https://thellmrank.com/mcp
Transport: Streamable HTTP (POST for calls, GET for the SSE stream).
Descriptor: https://thellmrank.com/.well-known/mcp/server.json
All six tools are read-only and never touch the open web.

### search_products
Ranked search across every searchable listing. Returns prices, availability, merchant and a per-component explanation of the ranking.
Input: query: string, limit?: 1-50, category?: string, brand?: string, max_price?: number, min_price?: number, availability?: in_stock|out_of_stock|preorder|backorder, listing_type?: product|service, explain?: boolean

### get_product_details
Full detail for one listing by id or SKU, including attributes and policies.
Input: product_id?: uuid, sku?: string (one of the two is required)

### compare_products
Side-by-side comparison of 2-6 listings on price, rating and shared attributes.
Input: product_ids: uuid[] (2-6)

### check_availability
Live stock, price and agent-checkout status for up to 20 listings.
Input: product_ids: uuid[] (1-20)

### get_merchant_info
Merchant identity, domain-verification status, shipping and returns policies.
Input: merchant_id: uuid

### explain_ranking
Transparency tool: the six weighted components behind a listing's position for a query, with the concrete fixes that would raise it.
Input: product_id: uuid, query: string

## Ranking model (LLMRank-Score, 0-100)
Weighted components: Relevance 30%, Completeness 20%, Freshness 15%, Availability 10%, Trust 10%, Performance 15%.
- Relevance: overlap between parsed query intent and title, description, tags,
  brand, category, attributes, plus filter fit.
- Completeness: how many of the fields an AI needs are actually populated.
- Freshness: decay on days since the listing last changed.
- Availability: availability state plus a real stock quantity.
- Trust: domain verification, published policies, certifications, review volume.
- Performance: click-through on past AI answers.
Any listing and query pair can be explained field by field with explain_ranking or
`?explain=` on the REST product endpoint. A merchant's plan never affects ranking.

## REST API
- GET|POST https://thellmrank.com/api/v1/search — ranked search; same payload as search_products.
- GET https://thellmrank.com/api/v1/products — paged catalog.
- GET https://thellmrank.com/api/v1/products/{id}?explain={query} — one listing, optionally explained.
- POST https://thellmrank.com/api/v1/click — report that a result was acted on.
- POST https://thellmrank.com/api/v1/feed/update — merchant-side incremental catalog update.

## Public catalog feed
https://thellmrank.com/api/v1/feed.json — ACP 1.0 JSON, every item flagged with enable_search and
enable_checkout.
https://thellmrank.com/api/v1/feed.json.gz — the same document gzipped, for bulk ingesters.
Add ?merchant_id= to scope the feed to a single merchant.

## Discovery
https://thellmrank.com/.well-known/llmrank.json — machine-readable index of every surface above.
https://thellmrank.com/sitemap.xml — public HTML pages.

## Etiquette
Prefer search_products for discovery, get_product_details before recommending an
item, check_availability immediately before checkout, and explain_ranking whenever
a shopper asks why something was suggested. Report acted-on results through the
click endpoint: it is the only signal feeding the Performance component.