FeedBagel

FeedBagel API Documentation

Find and integrate RSS feeds in your applications

Try the API

Search by URL

Search by Keywords

Direct Feed Check

Only https:// URLs are accepted.

Search

GET /api/v1/keywords

Search feeds by keywords. Returns feeds matching the given keywords in title, description, or tags.

curl -X GET "https://api.feedbagel.com/api/v1/keywords?q=design"
Try ↗

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.

curl -X GET "https://api.feedbagel.com/api/v1/direct-feed?url=https://medium.com/feed/androiddevelopers"
Try ↗

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.

curl -X GET "https://api.feedbagel.com/api/v1/hosts"
Try ↗

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.

Endpoint
GET
/api/v1/host/title/<host_title>

Parameters

Parameter
Description
host_title
The title of the host to retrieve (case-insensitive)

Response

{ "host": { "id": "integer", "host": "string", "title": "string", "description": "string", "metadata": "object", "last_crawled": "datetime", "feeds_count": "integer", "enabled": "boolean", "created_at": "datetime", "updated_at": "datetime", "categories": "array", "favicon": "string", "tls_valid": "boolean", "ttfb_ms": "integer", "status_code": "integer", "http_error": "string", "last_fetch_date": "datetime", "featured": "boolean", "favicon_url": "string", "tags": "array", "feed_count": "integer" } }

Example Request

curl -X GET "https://api.feedbagel.com/api/v1/host/title/Example%20Site"

Example Response

{ "host": { "id": 123, "host": "example.com", "title": "Example Site", "description": "A sample website", "metadata": {}, "last_crawled": "2024-03-20T10:00:00Z", "feeds_count": 5, "enabled": true, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-03-20T10:00:00Z", "categories": ["Technology", "News"], "favicon": "https://example.com/favicon.ico", "tls_valid": true, "ttfb_ms": 150, "status_code": 200, "http_error": null, "last_fetch_date": "2024-03-20T10:00:00Z", "featured": false, "favicon_url": "https://example.com/favicon.ico", "tags": ["tech", "news"], "feed_count": 5 } }

GET /api/v1/host/<host>/metadata

Get metadata for a specific host (domain).

ParameterDescriptionDefault
hostThe domain to get metadata for (e.g. medium.com)Required (in path)
curl -X GET "https://api.feedbagel.com/api/v1/host/medium.com/metadata"
Try ↗

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.

ParameterDescriptionDefault
tagTag name (e.g. Technology)Required
viewlist or groupgroup
pagePage number1
per_pageFeeds per page10
curl -X GET "https://api.feedbagel.com/api/v1/tag-feeds?tag=Technology"
Try ↗

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.

ParameterDescriptionDefault
limitMaximum number of feeds to return6
categoryCategory filternone
offsetResult offset for pagination0
curl -X GET "https://api.feedbagel.com/api/v1/feeds/most-viewed?limit=3"
Try ↗

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.

ParameterDescriptionDefault
pagePage number1
per_pageFeeds per page10
sortSort by (last_seen, title, host)last_seen
curl -X GET "https://api.feedbagel.com/api/v1/feeds/list?page=1&per_page=10"
Try ↗

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.

ParameterDescriptionDefault
pagePage number1
per_pageSites per page6
sortSort by (last_seen, host, views)last_seen
curl -X GET "https://api.feedbagel.com/api/v1/feeds/group?page=1&per_page=6"
Try ↗

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.

Endpoint
GET
/api/v1/entries

Query Parameters

Parameter
Description
page
Page number for pagination (default: 1)
per_page
Number of entries per page (default: 20, max: 50)
sort_by
Sort order (default: "published", options: "published", "updated")

Response

{ "entries": [ { "id": "string", "title": "string", "link": "string", "description": "string", "content": "string", "published": "datetime", "updated": "datetime", "author": "string", "feed": { "id": "integer", "url": "string", "title": "string", "host": "string" } } ], "meta": { "total": "integer", "page": "integer", "per_page": "integer", "total_pages": "integer" } }

Get Feed Entries

Retrieve entries for a specific feed by ID.

Endpoint
GET
/api/v1/entries/feed/<feed_id>

Parameters

Parameter
Description
feed_id
The ID of the feed to retrieve entries for

Query Parameters

Parameter
Description
page
Page number for pagination (default: 1)
per_page
Number of entries per page (default: 20, max: 50)

Get Host Entries

Retrieve entries from all feeds for a specific host.

Endpoint
GET
/api/v1/entries/host/<host_domain>

Parameters

Parameter
Description
host_domain
The domain of the host to retrieve entries for

Query Parameters

Parameter
Description
page
Page number for pagination (default: 1)
per_page
Number of entries per page (default: 20, max: 50)

Get Tag Entries

Retrieve entries from feeds with a specific tag.

Endpoint
GET
/api/v1/entries/tag/<tag_name>

Parameters

Parameter
Description
tag_name
The tag to retrieve entries for

Query Parameters

Parameter
Description
page
Page number for pagination (default: 1)
per_page
Number of entries per page (default: 20, max: 50)

Tags

GET /api/v1/tags

List all available tags and the number of feeds in each.

curl -X GET "https://api.feedbagel.com/api/v1/tags"
Try ↗

Example Response

{
  "tags": ["Technology", "Design", "News"],
  "tag_counts": {"Technology": 123, "Design": 45, "News": 67}
}