FetchRSS API

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 }