
FeedBagel API Documentation
Try the API
Search by URL
Direct Feed Check
Search
GET /api/v1/search
Find feeds by URL or domain. Returns feeds discovered for a given website or page.
Example Response
{ "feeds": [ { "url": "https://blog.prototypr.io/feed", "title": "Prototypr - Medium", "description": "Prototyping, UX Design, Front-end Development and Beyond 👾 | ✍️ Write for us https://bit.ly/apply-prototypr - Medium", "site_url": "https://blog.prototypr.io", "favicon": "https://prototypr.io/icon.ico", "last_updated": "2025-04-24T20:50:10+00:00", "feed_type": "rss20" } ], "meta": { "total": 1, "page": 1, "per_page": 10 } }
GET /api/v1/keywords
Search feeds by keywords. Returns feeds matching the given keywords in title, description, or tags.
Example Response
{ "feeds": [ { "url": "https://alistapart.com/feed/", "title": "A List Apart", "description": "For people who make websites", "host": "alistapart.com", "tags": ["design", "technology", "web development"], "last_seen": "2023-08-15T14:22:10+00:00" } ], "meta": { "total": 1, "page": 1, "per_page": 10, "pages": 1, "query": "design technology" } }
GET /api/v1/direct-feed
Validate and add a direct feed URL to the database. Returns feed info and entries if valid.
Example Response
{ "feed": { "url": "https://medium.com/feed/androiddevelopers", "title": "Android Developers - Medium", "description": "News and announcements from the Android Engineering team", "site_url": "https://medium.com/androiddevelopers", "favicon": "https://medium.com/favicon.ico", "last_updated": "2023-09-12T15:32:45+00:00", "feed_type": "rss" }, "entries": [ { "title": "Announcing Android 14", "link": "https://medium.com/androiddevelopers/announcing-android-14-d6be4e42afae", "published": "Mon, 11 Sep 2023 17:00:00 GMT", "summary": "Today we're releasing Android 14, the latest version of our mobile platform..." } ], "entries_count": 10, "content_type": "rss", "source": "fetched", "message": "Successfully processed feed" }
Error Response
{ "error": "InvalidFeed", "message": "This URL doesn't appear to be a valid feed. Found HTML page with title: Example Website", "url": "https://example.com", "content_type": "html" }
Hosts
GET /api/v1/hosts
List all hosts (domains) that have feeds indexed in FeedBagel.
Example Response
{ "hosts": [ {"host": "prototypr.io", "title": "Prototypr", "description": "Design tools and news", "logo_url": "https://prototypr.io/logo.png"}, {"host": "medium.com", "title": "Medium", "description": "Stories and ideas", "logo_url": "https://medium.com/logo.png"} ] }
Get Host by Title
Retrieve a host's information by its title.
Parameters
Response
Example Request
Example Response
GET /api/v1/host/<host>/metadata
Get metadata for a specific host (domain).
Parameter | Description | Default |
---|---|---|
host | The domain to get metadata for (e.g. medium.com) | Required (in path) |
Example Response
{ "host": "medium.com", "title": "Medium", "description": "Stories and ideas", "logo_url": "https://medium.com/logo.png", "tags": ["Writing", "Technology"] }
Feeds
GET /api/v1/tag-feeds
Get feeds for a specific tag.
Parameter | Description | Default |
---|---|---|
tag | Tag name (e.g. Technology) | Required |
view | list or group | group |
page | Page number | 1 |
per_page | Feeds per page | 10 |
Example Response
{ "feeds": [ {"url": "https://prototypr.io/feed.xml", "title": "Prototypr Design Discovery Feed", "tags": ["Technology"]} ] }
GET /api/v1/feeds/most-viewed
Get the most viewed feeds, optionally filtered by category.
Parameter | Description | Default |
---|---|---|
limit | Maximum number of feeds to return | 6 |
category | Category filter | none |
offset | Result offset for pagination | 0 |
Example Response
{ "feeds": [ {"url": "https://prototypr.io/feed.xml", "title": "Prototypr Design Discovery Feed", "views": 1234} ] }
GET /api/v1/feeds/list
Get all feeds in a paginated list view.
Parameter | Description | Default |
---|---|---|
page | Page number | 1 |
per_page | Feeds per page | 10 |
sort | Sort by (last_seen, title, host) | last_seen |
Example Response
{ "feeds": [ {"url": "https://prototypr.io/feed.xml", "title": "Prototypr Design Discovery Feed"} ], "total_feeds": 100, "current_page": 1, "per_page": 10, "sort_by": "last_seen" }
GET /api/v1/feeds/group
Get all feeds grouped by site, paginated.
Parameter | Description | Default |
---|---|---|
page | Page number | 1 |
per_page | Sites per page | 6 |
sort | Sort by (last_seen, host, views) | last_seen |
Example Response
{ "sites": [ { "host": "prototypr.io", "feeds": [ {"url": "https://prototypr.io/feed.xml", "title": "Prototypr Design Discovery Feed"} ] } ], "total_sites": 10, "current_page": 1, "per_page": 6, "sort_by": "last_seen" }
Entries
List Entries
Retrieve a list of feed entries with optional filtering.
Query Parameters
Response
Get Feed Entries
Retrieve entries for a specific feed by ID.
Parameters
Query Parameters
Get Host Entries
Retrieve entries from all feeds for a specific host.
Parameters
Query Parameters
Get Tag Entries
Retrieve entries from feeds with a specific tag.
Parameters
Query Parameters
Search Entries
Search for entries across all feeds.
Query Parameters
Tags
GET /api/v1/tags
List all available tags and the number of feeds in each.
Example Response
{ "tags": ["Technology", "Design", "News"], "tag_counts": {"Technology": 123, "Design": 45, "News": 67} }