RSS Watch - User Guide

Overview

RSS Watch is an RSS feed aggregation and history-tracking system that lets you view multiple RSS feeds in one place and track how content changes over time.

Main Features:

Browse aggregated RSS feeds through a web interface
Track content revisions and see what changed
Access feeds via API in JSON or Atom format
Filter and search feed content
View edit history with highlighted diffs

Base URL: https://tools.tornevall.net

Public API Endpoints

All API endpoints are available at https://tools.tornevall.net/api/rss/

List Available Feeds

Get a list of all available RSS feeds.

Endpoint:

GET /api/rss/feed

Query Parameters:

protected (optional): Filter by access level
- 0 = public feeds only
- 1 = protected feeds only
- 2 = all feeds

Example Request:

curl "https://tools.tornevall.net/api/rss/feed"

Example Response:

{
  "urls": [
    {
      "urlid": 5,
      "title": "Example Blog",
      "utf8": 0,
      "interval": 600,
      "lastupdate": "2026-02-08 21:30:07",
      "explicit": 0,
      "entryCount": 1234
    }
  ]
}

Get Feed Content (Atom Format)

Retrieve feed entries in Atom XML format.

Endpoint:

GET /api/rss/feed/{feedId}

Path Parameters:

feedId - The feed ID from the feed list

Query Parameters:

limit (default: 30) - Number of entries to return (max 100)
match (optional) - Comma-separated keywords to filter entries
as=json (optional) - Return JSON instead of Atom XML
history=1 (optional) - Include version history

Examples:

Get latest 50 entries:

curl "https://tools.tornevall.net/api/rss/feed/5?limit=50"

Filter by keywords:

curl "https://tools.tornevall.net/api/rss/feed/5?match=technology,innovation"

Get JSON instead of XML:

curl "https://tools.tornevall.net/api/rss/feed/5?as=json&limit=20"

Include history:

curl "https://tools.tornevall.net/api/rss/feed/5?history=1"

Response Format (Atom):

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Example Blog</title>
  <updated>2026-02-08T21:30:07+00:00</updated>
  <link rel="alternate" href="https://example.com"/>
  <entry>
    <title>Post Title</title>
    <summary>Post description...</summary>
    <published>2026-02-08T12:00:00+00:00</published>
    <link href="https://example.com/post"/>
  </entry>
</feed>

Response Format (JSON with as=json):

[
  {
    "title": "Post Title",
    "description": "Post description...",
    "link": "https://example.com/post",
    "pubdate": 1739013600,
    "inserted": "2026-02-08 14:30:29",
    "content_hash": "abc123..."
  }
]

Web Feed Viewer

Access the web-based feed viewer at https://tools.tornevall.net/feed

Browse All Feeds

URL: /feed

Shows a list of all available feeds with:

Feed title and source URL
Last update time
Number of entries
Link to view the feed

Example:

https://tools.tornevall.net/feed

View Feed Content

URL: /feed/{feedId}

View entries from a specific feed.

Query Parameters:

per_page (default: 10) - Entries per page (1-100)
history (default: 1) - Enable/disable history tracking
- 0 = Off (show only latest version)
- 1 = On (show all versions with diffs)
history_limit (default: 10) - Max versions to show per entry
page - Page number for pagination

Examples:

View feed with 25 entries per page:

https://tools.tornevall.net/feed/5?per_page=25

Disable history mode:

https://tools.tornevall.net/feed/5?history=0

Show up to 20 versions per entry:

https://tools.tornevall.net/feed/5?history=1&history_limit=20

View Single Entry

URL: /feed/entry/{contentId}

View a single feed entry with full history.

Example:

https://tools.tornevall.net/feed/entry/881323

This shows:

Entry title, description, and content
Publication and discovery dates
All historical versions (if history is enabled)
Highlighted diffs showing what changed

Find Edited Posts

URL: /feed/{feedId}/edited

Find posts that have been edited multiple times.

Query Parameters:

min_changes (default: 3) - Minimum number of edits
per_page (default: 25) - Results per page

Example:

Find all posts edited 5 or more times:

https://tools.tornevall.net/feed/5/edited?min_changes=5

Safe External Link

URL: /out/{contentId}

Redirects to the original post URL without revealing the referrer.

Example:

https://tools.tornevall.net/out/881323

This protects your privacy by not sending a referrer header to the external site.

Understanding History Tracking

RSS Watch tracks changes to feed entries over time. When a post is edited, the system saves a new version.

How It Works

Each entry gets a unique "fingerprint" (hash) based on its content
When the same entry is fetched again with different content, a new version is created
You can see all versions and exactly what changed

Viewing History

In the web viewer, history mode shows:

How many versions exist for each entry
A timeline of changes
Highlighted diffs showing additions (green) and deletions (red)
Side-by-side comparison of old vs new content

Enable history mode:

https://tools.tornevall.net/feed/5?history=1

Disable history mode:

https://tools.tornevall.net/feed/5?history=0

Keyword Filtering

Filter feed entries by searching for specific keywords.

API Usage:

curl "https://tools.tornevall.net/api/rss/feed/5?match=technology,innovation"

This returns only entries containing at least one of the keywords.

How it works:

Searches both title and description
Case-insensitive matching
Multiple keywords separated by commas
Entry matches if ANY keyword is found

Protected Feeds

Some feeds may be restricted to specific domains. If you try to access a protected feed from an unauthorized domain, you'll receive a 403 error.

Error message:

{
  "error": {
    "code": 403,
    "message": "Feed is protected by its hostname..."
  }
}

Protected feeds are only accessible when requested from allowed domains.

Rate Limiting and Performance

API Throttling

The API has high rate limits:

9000 requests per minute for RSS endpoints
Sufficient for most applications

Best Practices

For optimal performance:

Use appropriate limit values (don't request 1000 entries if you only need 10)
Cache responses when possible
Use the match parameter to filter data server-side instead of client-side
Enable history only when needed (it increases response size)

Pagination

For large feeds, use pagination:

/feed/5?per_page=25&page=1  # First page
/feed/5?per_page=25&page=2  # Second page

Common Use Cases

Build Your Own RSS Reader

// Fetch available feeds
fetch('https://tools.tornevall.net/api/rss/feed')
  .then(r => r.json())
  .then(data => {
    data.urls.forEach(feed => {
      console.log(feed.title, feed.entryCount);
    });
  });

// Get feed content
fetch('https://tools.tornevall.net/api/rss/feed/5?as=json&limit=20')
  .then(r => r.json())
  .then(entries => {
    entries.forEach(entry => {
      console.log(entry.title, entry.link);
    });
  });

Monitor Content Changes

Use history tracking to monitor when posts are edited:

# Find posts that have been edited 5+ times
curl "https://tools.tornevall.net/feed/5/edited?min_changes=5"

Filter by Topic

Get only entries about specific topics:

# Get technology-related posts
curl "https://tools.tornevall.net/api/rss/feed/5?match=tech,software,ai&limit=50"

Embed Feed on Your Site

<div id="feed"></div>
<script>
fetch('https://tools.tornevall.net/api/rss/feed/5?as=json&limit=10')
  .then(r => r.json())
  .then(entries => {
    const html = entries.map(e => `
      <article>
        <h3><a href="${e.link}">${e.title}</a></h3>
        <p>${e.description}</p>
        <small>${new Date(e.pubdate * 1000).toLocaleDateString()}</small>
      </article>
    `).join('');
    document.getElementById('feed').innerHTML = html;
  });
</script>

Troubleshooting

Feed Not Found (404)

Problem: Trying to access a feed that doesn't exist.

Solution: Check the feed list at /api/rss/feed for valid feed IDs.

Access Denied (403)

Problem: Feed is protected and you're accessing from wrong domain.

Solution: Protected feeds can only be accessed from authorized domains. Contact the administrator if you need access.

Empty Results

Problem: Feed returns no entries.

Solution:

Check if feed actually has content: /api/rss/feed shows entryCount
Try removing filters (match parameter)
Check if feed was recently added (may not have content yet)

Encoding Issues

Problem: Special characters appear garbled.

Solution: The API handles UTF-8 automatically. If you still see issues, ensure your client is interpreting responses as UTF-8.

Support

For issues or questions:

Check this documentation
Visit the feed viewer at https://tools.tornevall.net/feed
Contact the system administrator

Last Updated: 2026-02-09
API Version: 1.0

Tornevall Networks

rsswatch

RSS Watch - User Guide

Overview

Public API Endpoints

List Available Feeds

Get Feed Content (Atom Format)

Web Feed Viewer

Browse All Feeds

View Feed Content

View Single Entry

Find Edited Posts

Safe External Link

Understanding History Tracking

How It Works

Viewing History

Keyword Filtering

Protected Feeds

Rate Limiting and Performance

API Throttling

Best Practices

Pagination

Common Use Cases

Build Your Own RSS Reader

Monitor Content Changes

Filter by Topic

Embed Feed on Your Site

Troubleshooting

Feed Not Found (404)

Access Denied (403)

Empty Results

Encoding Issues

Support