FetchRSS API Developers documentation

This API provides programmatic access to basic FetchRSS functionality.

All API requests must be sent via HTTP(S) protocol to specific endpoints using the GET method. The requested URL should look like this: http://fetchrss.com/api/v1/ENDPOINT?auth=YOUR-API-AUTH-KEY&OTHER-PARAMETERS

Each API request must be authenticated by adding ?auth=YOUR-API-AUTH-KEY to a query parameters.
YOUR-API-AUTH-KEY - is your personal key. You can get your key in your account section.

The API returns JSON-encoded objects. And every response body always has a status field with a "success: true/false" value indicating any errors. If errors occur, the response will also contain an "error" object with "message" and "code" fields.

Example:

{ "success": false, "error": { "message": "Not authorised", "code": 401 } }

Limitation: All API endpoints have 1 request per second rate limit. For example, if you make multiple calls to the /feed/create endpoint at the same time, then only the first call will work. And the rest will be declined.

End-Points

/feed/create

Create an RSS feed. Returns a link to created feed.
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: If you continue trying to create the same feed too many times, our system may block your API key. To prevent this from happening please follow two simple steps:
  • Don't send a new "create" request if you already have a feed for this URL (consider keeping track of exists feeds on your side or check your feeds list with /feed/list endpoint to prevent unnecessary requests.)
  • Stop attempts to create a feed for the same URL after a few fail responses.

Query parameters:

Key Required Description Example
url
required
required
Target URL https://www.youtube.com/c/vsauce1
title
optional
optional
Set custom feed title. 120 characters max. Leave empty to fetch it from a source page automatically Vsauce on YouTube
description
optional
optional
Set custom feed description. 500 characters max. Leave empty to fetch it from a source page automatically Vsauce recently uploaded videos
items-per-rss
optional
optional
Limit the number of posts in the RSS 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 web page, you'll also need to specify HTML parsing rules.
Key Required Description Example
news-selector
required
required
News DOM CSS selector
Note: All other selectors must be inside of this DOM		 div.article
title-selector
required
required
News title CSS selector div.article > h2
content-selector
required
required
News summery CSS selector div.article > p
pic-selector
optional
optional
News illustration CSS selector div.article > img
date-selector
optional
optional
News publish date CSS selector div.article > time
author-selector
optional
optional
News author CSS selector div.article > .author
link-selector
optional
optional
News link CSS selector div.article > a:first
pic-src-param
optional
optional
Image URL attribute.
In case the page uses lazy loading images.
And the required URL is not in "src" attribute		 data-src
date-format-param
optional
optional
Date parsing pattern
See http://fetchrss.com/docs/dateParse for more details		 Y/M/D

Additional Facebook parameters:

In addition to generic feed parameters, you can specify extra Facebook feed options. If you want to set any of these options, you must always include a "provider" parameter. Otherwise, API will ignore it.
Key Required Description Example
provider
required
required
Must be "facebook" facebook
shared-to-original
optional
optional
Link shared posts to the original URL
Accepted values: true / false
Default value: true		 true

Additional YouTube parameters:

In addition to generic feed parameters, you can specify extra YouTube feed options. If you want to set any of these options, you must always include a "provider" parameter. Otherwise, API will ignore it.
Key Required Description Example
provider
required
required
Must be "youtube" youtube
video
optional
optional
Video in feed
Accepted values: image / player / link / none
Default value: player		 player

Example cURL request:

curl http://fetchrss.com/api/v1/feed/create?auth=YOUR-API-AUTH-KEY&url=https%3A%2F%2Fwww.youtube.com%2Fc%2Fvsauce1&news-selector=div.article&title-selector=div.article+%3E+h2&content-selector=div.article+%3E+p&provider=youtube

Example response:

{ "success": true, "feed": { "id": "6304a8c9431bef7af66eb704", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml" }, "target_url": "https://www.youtube.com/c/vsauce1" }

/feed/list

Get a list of all user feeds

Example cURL request:

curl http://fetchrss.com/api/v1/feed/list?auth=YOUR-API-AUTH-KEY

Example response:

{ "success": true, "feeds": [ { "id": "6304a8c9431bef7af66eb704", "title": "Vsauce - YouTube", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f467587692067.xml", "src_url": "http://facebook.com/cnn" }, { "id": "587601d3446072e9628a9249", "title": "Nobelprize.org", "rss_url": "http://fetchrss.com/rss/566b1cbb8a93f85e53b226f496051329546.xml", "src_url": "https://www.nobelprize.org/" } ] }

/feed/delete

Delete user feed
Limitation: creating and then deleting the same feed too many times is forbidden. Our system may block your API key if it detects such activity.

Query parameters:

Key Required Description Example
id
required
required
RSS ID 6304a8c9431bef7af66eb704

Example cURL request:

curl http://fetchrss.com/api/v1/feed/delete?auth=YOUR-API-AUTH-KEY&id=6304a8c9431bef7af66eb704

Example response:

{ "success": true }