US Top 8 API and agent documentation
US Top 8 is a comparison site for people researching products and services. This public API exposes the same published articles that readers can see on the website. It supports search and retrieval; it cannot submit forms, create accounts, send messages or purchase products.
Public access
No API key, login, OAuth token or payment is required. Use HTTPS GET requests. The API is versioned under /api/v1/. Read the access guide and OpenAPI 3.1 specification for complete request and response schemas.
Search and list articles
GET https://www.ustop8.com/api/v1/articles?q=AI&limit=10&offset=0The optional q searches titles and published article text, up to 200 characters. category filters by category slug. limit is 1–50 (default 10), and offset starts at 0. Responses provide items, total, limit, offset and nextOffset. Continue with nextOffset until it is null.
Read an article
GET https://www.ustop8.com/api/v1/articles/best-geo-aeo-toolsThe response includes the canonical URL, title, description, dates, category information, visible content HTML, rankings and FAQs when present. Product links intentionally absent from an article are not invented by the API.
Markdown and discovery
Use /index.md for a concise homepage, append .md to a page path for its Markdown version, or send Accept: text/markdown to a public page URL. Missing pages return HTTP 404 with a Markdown explanation when that format is requested. Discover resources through ARD, the agent instructions index, llms.txt, the sitemap and RSS feed.
Browser tools
Where supported, WebMCP exposes read-only article-list, search and retrieval tools. Browser tools return the same public data as the API. They do not submit requests for editorial review or newsletter signup.
Errors, caching and versioning
Invalid parameters return HTTP 400, unknown articles return HTTP 404, and unsupported methods return HTTP 405. Errors use application/problem+json. Read cache headers before repeating requests. Compatible fields may be added to v1; a breaking request or response change will use a new API version. This API does not offer writes, private data, payment operations or long-running jobs.
Editorial context
Recommendations reflect the methodology, dates, limitations and preferred-placement disclosures in each article. The API does not turn editorial rankings into independent benchmarks or guarantees. Read the linked article and its sources before relying on a recommendation.
Cursor pagination
For stable continuation, pass the response nextCursor as cursor on the next request, using the same q and category filters. Do not combine cursor with offset. The cursor is an opaque public pagination marker, not a credential. If an article used as a cursor anchor is removed, restart from the first page.
Request limits
The hosted public article API applies an approximate limit of 120 GET or HEAD requests per 60 seconds per client network address at each Cloudflare location. Shared networks share this allowance. RateLimit-Policy and RateLimit-Limit describe the policy; RateLimit-Reset supplies a conservative 60-second wait window. The hosting limiter does not expose an exact remaining counter, so successful responses do not invent one. A blocked request returns HTTP 429, an application/problem+json body, RateLimit-Remaining: 0 and Retry-After: 60. HTML pages and static agent resources are outside this API limit.
Versioning and retirement policy
The current public API is v1. Breaking contract changes use a new major version in the URL; additive fields can be introduced within v1. No endpoints are currently deprecated. API responses link this policy using rel="deprecation". Future deprecations will name the affected major version and announce a retirement date here before removal. A deprecated endpoint will include Deprecation and Sunset headers when a retirement is scheduled; active endpoints do not send misleading deprecation timestamps. All current operations complete synchronously and read public content; there are no write operations, queued jobs, payment actions, or idempotency keys to manage.
Source repository
The site source and contributor instructions are available in the public US Top 8 repository.