←Back

Topfeed API

Overview

The Topfeed API exposes the public RSS and Atom feed directory as JSON. Use it to discover curated feeds by topic, check how active a feed is, and read its latest entries. Base URL: https://topfeed.xyz.

Read endpoints are free and require no authentication or API key. Entries link to articles on the original publishers' websites.

List and search feeds

GET /api/feeds — a paginated list of approved feeds.

  • q— case-insensitive search over title, description, feed URL, and website URL
  • sort— users (default, most readers), latest(newest post), title (A–Z), activity(most new entries)
  • stale— any (default), exclude (healthy feeds only), only (failing feeds only)
  • page— 1-based page number, default 1
  • pageSize— default 30, maximum 250

Returns { items, page, pageSize, total }. Each feed includes slug, title, url, websiteUrl, tags,userCount, totalEntriesCount, and fetch health.

Get a feed and its entries

GET /api/feeds/{slug}— one feed plus its latest entries, newest first. The slug comes from directory URLs such as /feeds/simon-willisonor from the list endpoint.

  • page— 1-based page number, default 1
  • pageSize— default 30, maximum 100

Returns { feed, entries }. Each entry includes title, url, author, publishedAt(Unix milliseconds), and contentSnippet.

Examples

curl "https://topfeed.xyz/api/feeds?q=design&sort=users&pageSize=2"
curl "https://topfeed.xyz/api/feeds/simon-willison?pageSize=5"

Errors

Errors are JSON with an HTTP status: 400 (invalid input), 403 (admin-only filter), 404 (unknown slug).

{ "error": "Feed not found" }

Markdown for agents

Send Accept: text/markdown to the homepage to receive the feed directory as Markdown with Vary: Accept. Missing pages return 404/410 with a Markdown error body when Markdown is requested. Browsers keep receiving HTML.

curl -H "Accept: text/markdown" https://topfeed.xyz/

Machine-readable files