← Back to blog

Turn Any RSS or Atom Feed Into JSON With One API Call

October 31, 2026 · Eric · 6 min read

RSS never died — it just moved under the hood. Release notes, changelogs, subreddits, newsletters, job boards, and most news sites still expose a feed, and that feed is the cheapest structured data source an agent will ever get. No headless browser, no rate-limit dance, no HTML that changes shape every quarter.

The annoying part is never the feed itself. It's the XML. You get namespaced tags, CDATA blocks, four different date formats, and an Atom variant that renames half the elements. So most agents either pull in a parser dependency or burn a model turn reasoning about tags. There's a shorter path: send the feed URL to one endpoint and get normalized JSON back.

One GET request, no API key

The feed parser lives at GET /api/rss/parse. It takes a url and an optional limit, and it reads both RSS 2.0 and Atom out of the box — you don't have to tell it which one you're sending.

curl "https://agentmediatools.com/api/rss/parse?url=https://news.ycombinator.com/rss&limit=2"

Here's an actual trimmed response (real run, not a mock-up):

{
  "success": true,
  "feed": {
    "title": "Hacker News",
    "description": "Links for the intellectually curious, ranked by readers.",
    "link": "https://news.ycombinator.com/",
    "feed_url": "https://news.ycombinator.com/rss",
    "language": null,
    "last_build_date": null,
    "generator": null,
    "copyright": null,
    "image": null
  },
  "items": {
    "total": 30,
    "returned": 2,
    "entries": [
      {
        "title": "Casio Watches of the 1980s",
        "link": "https://www.casio.com/us/watches/50th/Heritage/1980s/",
        "guid": null,
        "pub_date": "Sat, 31 Oct 2026 16:00:48 +0000",
        "creator": null,
        "categories": [],
        "summary": "Comments"
      }
    ]
  },
  "elapsed_ms": 388
}

That's the whole contract. A feed object with the channel-level metadata, and an entries array where every item has been flattened into the same seven fields regardless of whether the source was RSS or Atom.

What every field actually means

FieldWhat you get
feed.title / description / linkChannel metadata. Any of them can be null if the publisher omitted it.
feed.feed_urlThe URL that was actually parsed — useful when you follow a redirect or add https:// to a bare hostname.
items.totalHow many items exist in the feed document.
items.returnedHow many you got back after limit was applied. These two differ constantly — don't report total as your result count.
entries[].title / link / guidIdentity fields. guid is your dedupe key when the publisher sets one; a lot of feeds leave it null, so fall back to link.
entries[].pub_dateThe publish date exactly as the feed wrote it — RFC 822 for RSS, ISO 8601 for Atom. It is not normalized to ISO, so parse before you sort.
entries[].creatorThe author, when the feed exposes one (commonly via dc:creator).
entries[].categoriesArray of tag strings. Empty array when the feed has no categories — not null.
entries[].summaryThe feed's own snippet, truncated to 500 characters. This is what the publisher put in the description field, which is sometimes one word.
elapsed_msServer-side fetch + parse time, handy when you're profiling a polling loop.

A Python polling loop you can actually run

This is the shape I use: fetch each feed, treat success: false as a normal error (more on that below), and dedupe on guid or link before anything reaches a model.

import json, pathlib, requests, time

API = "https://agentmediatools.com/api/rss/parse"
SEEN_PATH = pathlib.Path("seen_items.json")

def fetch_feed(url, limit=20, api_key=None):
    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
    r = requests.get(API, params={"url": url, "limit": limit},
                     headers=headers, timeout=30)
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("error", "feed parse failed"))
    return data

def new_entries(data, seen):
    out = []
    for item in data["items"]["entries"]:
        key = item.get("guid") or item.get("link")
        if not key or key in seen:
            continue
        seen.add(key)
        out.append(item)
    return out

seen = set(json.loads(SEEN_PATH.read_text())) if SEEN_PATH.exists() else set()

for feed in ["https://news.ycombinator.com/rss",
             "https://blog.python.org/feeds/posts/default"]:
    result = fetch_feed(feed, limit=10)
    fresh = new_entries(result, seen)
    print(f'{result["feed"]["title"]}: {len(fresh)} new of '
          f'{result["items"]["returned"]} returned')
    for item in fresh:
        print(" -", item["title"], item["pub_date"])
    time.sleep(1)

SEEN_PATH.write_text(json.dumps(sorted(seen)))

Two things worth noting in that snippet. First, it sends an API key when you have one, because a keyed call gets a higher daily ceiling than an anonymous one. Second, it keeps the dedupe set client-side — the endpoint is stateless and holds no memory of what you've already read.

Limits, measured in behavior

These are the real guards in the route, not marketing numbers:

BehaviorValue
AuthenticationNone required. Anonymous calls draw from the shared free daily pool (10/day); a free account gets 25/day, and paid agent keys get 1,000/day.
limitDefaults to 50, clamped to 1–200. Anything outside that range is silently clamped, not rejected.
Feed sizeResponse body read is capped around 1 MB, and feeds under ~50 bytes are rejected as empty.
Fetch timeout15 seconds for the upstream request; the feed parser itself is configured with a 10-second timeout.
Summary length500 characters per item.
Private networksBlocked. Loopback and private IPs are refused with Private network URLs are not allowed.
SchemeOnly http: and https:. A bare hostname gets https:// prepended for you.

The one gotcha that will bite you

Every error path in this route returns HTTP 200. A missing parameter, an unreachable host, a private URL, and an XML parse failure all come back as a normal response with success: false and a human-readable error string. If your client only checks r.status_code == 200, it will happily feed {"success": false, "error": "url parameter required"} into your pipeline and wonder why nothing works.

$ curl -s "https://agentmediatools.com/api/rss/parse"
{"success":false,"error":"url parameter required"}

$ curl -s "https://agentmediatools.com/api/rss/parse?url=http://127.0.0.1/rss"
{"success":false,"error":"Fetch failed: Private network URLs are not allowed"}

$ curl -s "https://agentmediatools.com/api/rss/parse?url=https://example.com/nope.xml"
{"success":false,"error":"Failed to parse feed: Unquoted attribute value\nLine: 0\nColumn: 27\nChar: e"}

Branch on success, and log error verbatim. The parse error text includes line and column, which is genuinely useful when a publisher ships a malformed feed.

Two more quiet ones

What this endpoint deliberately doesn't do

It is a parser, not a reader. It doesn't render pages, extract full article text, follow pagination, cache, or take an OPML file. There's no since parameter either — you ask for N items and slice by timestamp yourself.

When you need more, chain the right tool instead of stretching this one:

A workflow that stays cheap

Step 1 — Poll on a schedule

Every 15–30 minutes, fetch each feed with limit=20. That's one request per feed, and your dedupe set means you only act on genuinely new items.

Step 2 — Filter before the model

Drop items by category or title keyword in code. Anything you can decide without a model call should never become a model call.

Step 3 — Summarize only the survivors

Send the handful of new titles plus links onward. If you need the body text, fetch it per link at this stage, not for all 200 items.

Step 4 — Keep a cursor

Persist the last successful pub_date and your seen-key set. The endpoint is stateless, so continuity is your job — that's also what keeps a re-run from re-notifying you.

Why not just parse the XML yourself

You can, and for a single well-behaved feed it's fine. The cost shows up when you're watching ten feeds and three of them are Atom, one has a BOM, one returns HTML on a bad day, and one is behind a redirect. You end up writing a fetch layer, a timeout layer, an SSRF guard, and a normalizer — then maintaining them. This endpoint is that layer, already wired into the same key, usage accounting, and error shape as the rest of the API surface.

If you want to confirm it exists on the live deployment before you write code, ask the catalog directly:

curl -s https://agentmediatools.com/api/tools | python3 -c "import json,sys; print([t['id'] for t in json.load(sys.stdin)['tools'] if 'rss' in t['id']])"
# ['rss-parser']
Try it in the Toolbox

Run the feed parser in the browser, or call it from your agent with an API key.

Open toolbox

Related reading: structured scraping with CSS selectors, webhooks for agent pipelines, and what else one API key unlocks.