FetchRSS API
Developers documentation

Introduction

The FetchRSS API allows programmatic access to create, retrieve, and manage RSS feeds from various sources such as Web pages, Facebook, YouTube, and more.

Authentication

All API requests must include your personal API key in the request header:

API-KEY: {YOUR_API_KEY}

Please replace "{YOUR_API_KEY}" with your actual API key, which you can obtain from your account settings. If a request does not include a valid API key, it will result in a 401 Unauthorized error.

Base URL

All endpoints are accessed via:

https://fetchrss.com/api/v2/

Rate Limiting

To ensure fair usage, the API enforces a rate limit of 1 request per second per endpoint. Exceeding this limit may result in request failures or temporary blocking of your API key.

Request Format

The API requests are structured around REST principles and CRUD operations. It features predictable, resource-oriented URLs, accepts form-encoded request bodies.

Example cURL request
curl --request POST "https://fetchrss.com/api/v2/{endpoint}" \
--header "API-KEY: {YOUR_API_KEY}" \
--form "param_1=val_1" \
--form "param_N=val_N"

Response Format

Responses are JSON-encoded and include a success field indicating the operation's outcome. In case of errors, an error object provides details.

Success Response Example
{ "success": true, // ... Response-specific data ... }
Error Response Example
{ "success": false, "error": { "code": 401, "message": "Not authorized" } }

Endpoints

Create a New Feed
POST /feeds

Creates a new RSS feed based on the provided parameters.

Once you've created a feed, you don't need to call this endpoint to update it. The feed is updating automatically and available at the "rss_url" address.
If you have a feed and try to create a new one with the same parameters, it won't be created. Our API will return the feed id and the rss_url of the previously created feed in this case.

Limitation
To prevent API abuse, there are certain limitations in place. If you repeatedly attempt to create the same feed, our system may block your API key. To avoid this, please follow these two simple steps:
  • Avoid sending a new "create" request if you already have a feed for the given URL. It's a good idea to keep track of existing feeds on your end or to check your feed list using the /feeds endpoint to prevent unnecessary requests.
  • Cease attempts to create a feed for the same URL after receiving a few failed responses.

Request parameters
Key Description Example
url
required 		Target URL https://example.com/
title
optional 		Set custom feed title. 120 characters max.
Leave empty to fetch it from a source page automatically		 Example Feed
description
optional 		Set custom feed description. 500 characters max.
Leave empty to fetch it from a source page automatically		 Simple API demo
items_per_feed
optional 		Limit the number of posts in the Feed file at a time.
Accepted values: 1 - [plan max].
Default value: maximum number allowed by the current plan		 3

Additional HTML parameters
If you need to create a feed out of a generic HTML page, you'll also need to specify content parsing rules.
Key Description Example
news_selector
required 		Root CSS selector for each news item.
Serves as the parent scope for all other selectors.
Each match is a separate news item		 div
title_selector
required 		CSS selector within the news_selector for the item’s title.
At least title_selector or content_selector is required		 h1
content_selector
required 		CSS selector within the news_selector for the item’s summary or main content.
At least title_selector or content_selector is required		 p:first-child
pic_selector
optional 		CSS selector within the news_selector for the featured image .media__image
date_selector
optional 		CSS selector within the news_selector for the publication date time
author_selector
optional 		CSS selector within the news_selector for the author’s name .author
link_selector
optional 		CSS selector within the news_selector for the URL leading to the full article p > a
pic_src
optional 		If images are lazy-loaded, specify the image URL attribute data-src
date_format
optional 		Define the date format to properly parse publication dates.
See https://fetchrss.com/docs/dateParse for more details		 Y/M/D

Additional Facebook parameters
In addition to general feed parameters, you can specify extra Facebook feed options.
Key Description Example
shared_to_original
optional 		Link shared posts to the original URL.
Accepted values: true / false
Default value: true		 true

Additional YouTube parameters
In addition to general feed parameters, you can specify extra YouTube feed options.
Key Description Example
video
optional 		Video in feed.
Accepted values: image / player / link / none
Default value: player		 player
Example cURL request
curl --request POST "https://fetchrss.com/api/v2/feeds" \
--header "API-KEY: {YOUR_API_KEY}" \
--form "url=https://example.com/" \
--form "news_selector=div" \
--form "title_selector=h1" \
--form "content_selector=p:first-child"
Example response
{ "success": true, "feed": { "id": "6304a8c9431bef7af66eb704", "title": "Example Domain", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml", "src_url": "https://example.com/" } }

Retrieve All feeds info
GET /feeds

Fetches a list of all feeds associated with your account.
This endpoint returns a limited number of results per request. Use the page and per_page query parameters to navigate through paginated results.

Request parameters
Key Description Example
page
optional 		Page number to retrieve (1-based index).
Default: 1		 1
per_page
optional 		Number of feeds to return per page.
Default: 10 Maximum: 100		 10
Example cURL request
curl --request GET "https://fetchrss.com/api/v2/feeds?page=1" \
--header "API-KEY: {YOUR_API_KEY}"
Example response
{ "success": true, "feeds": [ { "id": "6304a8c9431bef7af66eb704", "title": "Example Domain", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml", "src_url": "https://example.com/" }, { "id": "587601d3446072e9628a9249", "title": "Nobelprize.org", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f496051329546.xml", "src_url": "https://www.nobelprize.org/" } ], "pagination": { "page": 1, "per_page": 10, "total_pages": 1, "total_items": 2 } }

Delete feed
DELETE /feeds/{id}

Deletes the specified feed.

Limitation
Repeatedly creating and deleting the same feed in a short period may lead to your API key being blocked.

Request parameters
Key Description Example
id
required 		Feed ID 6304a8c9431bef7af66eb704
Example cURL request
curl --request DELETE "https://fetchrss.com/api/v2/feeds/6304a8c9431bef7af66eb704" \
--header "API-KEY: {YOUR_API_KEY}"
Example response
{ "success": true }