FetchRSS API

Your API auth key will be here after registration.

General information

This API provides a 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. It can be found at the top of this page.

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	Target URL	https://www.youtube.com/c/vsauce1
`title`	optional	Set custom feed title. 120 characters max. Leave empty to fetch it from a source page automatically	Vsauce on YouTube
`description`	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	Limit the number of posts in the RSS file at a time. Accepted values: 1 - 5. Default value: maximum number allowed by the current plan	3

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

Example response:

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

HTML parser

If you need to create a feed out of a general web page. You'll need to add a target page parsing selectors. It must be a CSS selectors.

Query parameters:

Key	Required	Description	Example
`url`	required	Target URL	https://www.nobelprize.org/
`news-selector`	required	News DOM selector Note: All other selectors must be inside of this DOM	div.row > div.columns
`title-selector`	required	News title selector	div.row > div.columns > h2
`content-selector`	required	News summery selector	div.row > div.columns > p
`pic-selector`	optional	News illustration selector
`date-selector`	optional	News publish date selector
`author-selector`	optional	News author selector
`link-selector`	optional	News link selector
`pic-src-param`	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	Date parsing pattern See http://fetchrss.com/docs/dateParse for more details	Y/M/D

Example cURL request:

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

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.

Query parameters:

Key	Required	Description	Example
`provider`	required	Must be "facebook"	facebook
`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 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.

Query parameters:

Key	Required	Description	Example
`provider`	required	Must be "youtube"	youtube
`video`	optional	Video in feed Accepted values: image / player / link / none Default value: player	player

/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 is forbidden. Our system may block your API key if it detects such activity.

Query parameters:

Key	Required	Description	Example
`id`	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 }