API Reference

The RSS.app API is based on the RESTful API. The API accepts JSON-encoded request bodies and returns JSON-encoded responses with HTTP response codes.

BASE URL

https://api.rss.app

Authentication

RSS.app uses API keys to authenticate requests. You can view and manage your API keys in the RSS.app API Document.

Your API keys should be kept private and secure and not shared with anyone or in any publicly accessible resources such as client-side code, GitHub, etc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

YOUR API KEY

A sample test API key is included in all the examples here, so you can test any example right away. Do not submit any personally identifiable information in requests made with this key.

To test requests using your account, replace the sample API key with your actual API key or sign in.


Errors

Conventional HTTP response codes are used to indicate the success or failure of a request.

Codes in the 200 range indicate success.

Codes in the 400 range indicate an error with the given information.

Codes in the 500 range indicate an error with RSS.app’s servers (these are rare).

Attributes

messagestring

A human-readable message providing more details about the error.


statusCodenumber

HTTP Status Code.


errorsarray

Container for all error elements.


titlestring

Message providing more details about the error.


codestring

A short string indicating the error code

HTTP STATUS CODE SUMMERY

200 - OK

Everything worked as expected.

400 - Bad Request

The request was unacceptable, often due to missing a required parameter.

401 - Unauthorized

No valid API key provided.

402 - Request Failed

The parameters were valid but the request failed.

403 - Forbidden

The API key doesn't have permissions to perform the request.

404 - Not Found

The requested resource doesn't exist.

409 - Conflict

The request conflicts with another request (perhaps due to using the same idempotent key).

429 - Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

500, 502, 503, 504 - Server Errors

Something went wrong on RSS.app's end. (These are rare.)

200 - OK

Everything worked as expected.


400 - Bad Request

The request was unacceptable, often due to missing a required parameter.


401 - Unauthorized

No valid API key provided.


402 - Request Failed

The parameters were valid but the request failed.


403 - Forbidden

The API key doesn't have permissions to perform the request.


404 - Not Found

The requested resource doesn't exist.


409 - Conflict

The request conflicts with another request (perhaps due to using the same idempotent key).


429 - Too Many Requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.


500, 502, 503, 504 - Server Errors

Something went wrong on RSS.app's end. (These are rare.)


Pagination

API resources that provide the ability to fetch multiple items such as 'Feed List' can be paginated using offset-based pagination via the $offset and $limit parameters. Both parameters take an integer value and return objects in reverse chronological order.

Parameters

$limitoptional, default is 10

A limit on the number of objects to be returned, between 1 and 100.


$offsetoptional, default is 0

Determines the starting point.

List Response Format

dataarray

An array containing the actual response elements, paginated by any request parameters.


totalnumber

Total elements count.


offsetnumber

Determines the starting point.


limitnumber

A limit on the number of objects.

RESPONSE

{ "total": 372, "offset": 1, "limit": 1, "data": [ { "id": "cYVBYcpUEbgXfg9v", "rssFeedUrl": "https://rss.app/feeds/cYVBYcpUEbgXfg9v.xml", "description": "Breaking news, sport, TV, radio and a whole lot more. The BBC informs, educates and entertains - wherever you are, whatever your age.", "title": "BBC - Homepage", "sourceUrl": "http://bbc.com", "icon": { "url": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg", "mimeType": "image/jpeg" } }, ] }

Feed

Create, retrieve, or delete your news feeds as well as view a list of all the feeds in your account. Each feed contains items such as headlines, images, and a short description of each post.

Attributes

idstring

Unique identifier for the object.


titlestring

Feed title. This can be edited from the RSS.app dashboard.


descriptionstring

Feed description. This can be edited from the RSS.app dashboard.


sourceobject

Source of the feed.


urlstring

Source url


iconobject

Feed icon. This can be modified in the RSS.app dashboard.


urlstring

Icon url


mimeTypestring

Icon image mimeType


postsarray

Articles attached to feed object.


titlestring

Article title


urlstring

Article link


descriptionstring

Article text without the html


authorstring

Article author


publishedAtdate string

Article creation date


thumbnailobject

Article thumbnail


urlstring

Thumbnail url


mimeTypestring

Thumbnail image mimeType

ENDPOINTS

THE FEED OBJECT

{ "id": "tq7X9v2dKgkTre59", "title": "bmw", "description": "#bmw generated by RSS.app", "source": { "url": "https://rss.app/rss-feed?keyword=bmw" }, "items": [ { "title": "BMW Brings Alpina Performance Brand into the Fold", "url": "https://www.caranddriver.com/news/a39396769/bmw-alpina-performance-brand-added/", "description": "After 57 years, the highly respected small tuning firm is being acquired by the automaker, and after 2025 we can expect all future Alpina models to come straight from BMW.", "author": "Mike Duff", "publishedAt": "2022-03-10T09:36:00.000Z", "thumbnail": { "url": "https://hips.hearstapps.com/hmg-prod.s3.amazonaws.com/images/2022-bmw-alpina-b8-gran-coupe-4-1646929819.jpg?crop=0.702xw:0.527xh;0.126xw,0.284xh&resize=640:*", "mimeType": "image/jpeg" } }, { "title": "Quick Look: 2022 BMW M 1000 RR—Ultimate Evolution, In The April Issue", "url": "https://www.roadracingworld.com/news/quick-look-2022-bmw-m-1000-rr-ultimate-evolution-in-the-april-issue/", "description": "BMW's M 1000 RR, the company's most advanced and highest-performing streetbike, on track in the April 2022 issue of Roadracing World magazine.", "publishedAt": "2022-04-08T18:30:57.000Z", "thumbnail": { "url": "https://www.roadracingworld.com/wp-content/uploads/2022/04/0422_QL_BMW_A_Toye-8-M1000RR-DSC_0699_P_WEB-A_1649440221.jpg", "mimeType": "image/jpeg" } }, { "title": "BMW M2 G87 Seats Leak Might not be the Original Ones", "url": "https://www.bmwblog.com/2022/04/07/bmw-m2-g87-seats-leak/", "description": "BMW community quickly reposted the new seats as a leak of the carbon bucket seats found in the upcoming BMW M2 G87.", "publishedAt": "2022-04-07T21:35:51.000Z", "thumbnail": { "url": "https://cdn.bmwblog.com/wp-content/uploads/2022/03/2023-bmw-m8-carbon-bucket-seats-00-scaled.jpg", "mimeType": "image/jpeg" } } ] }

Feed List

View a list of feeds created in the account.

Parameters

$limitoptional, default is 10

A limit on the number of feeds to be returned, between 1 and 100.


$offsetoptional, default is 0

Determines the starting point.

Returns

Returns a list of feeds in the account.

Each entry in the array is a separate Feed object. If no more feeds are available, the resulting array is empty.

GET /v1/feed

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 var axios = require('axios'); var config = { method: 'get', url: 'https://rss.app/api/v1/feed?$limit=10', headers: { 'Authorization': 'Bearer YOUR_API_KEY:YOUR_API_SECRET' } }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); });

RESPONSE

{ "total": 373, "offset": 5, "limit": 0, "data": [ { "id": "Bbdo4uIuij3aUhNy", "description": "See posts, photos and more on Facebook.", "title": "Log in or sign up to view", "source": { "url": "http://fb.com" }, "icon": { "url": "https://static.xx.fbcdn.net/rsrc.php/yb/r/hLRJ1GG_y0J.ico", "mimeType": "image/x-icon" } }, { "id": "cYVBYcpUEbgXfg9v", "description": "Breaking news, sport, TV, radio and a whole lot more. The BBC informs, educates and entertains - wherever you are, whatever your age.", "title": "BBC - Homepage", "source": { "url": "http://bbc.com" }, "icon": { "url": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg", "mimeType": "image/jpeg" } }, { "id": "t5lxgVkWqYrrZ37v", "description": "#vanadzor generated by RSS.app", "title": "vanadzor", "source": { "url": "https://rss.app/rss-feed?keyword=vanadzor" }, "icon": {} }, { "id": "tq7X9v2dKgkTre59", "description": "#bmw generated by RSS.app", "title": "bmw", "source": { "url": "https://rss.app/rss-feed?keyword=bmw" }, "icon": {} }, {...} ] }

Get Feed

Retrieve the details of an existing feed by providing its unique feed ID.

The feed ID can be found from the ‘Create Feed’ request or the ‘Feed List’ request.

Parameters

No parameters

Returns

A feed is returned. Otherwise, an error is returned.

GET /v1/feed/:id

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 var axios = require('axios') var config = { method: 'get', url: 'https://rss.app/api/v1/feed/FEED_ID', headers: { 'Authorization': 'Bearer YOUR_API_KEY:YOUR_API_SECRET' } }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); });

RESPONSE

{ "id": "tq7X9v2dKgkTre59", "title": "bmw", "description": "#bmw generated by RSS.app", "source": { "url": "https://rss.app/rss-feed?keyword=bmw" }, "items": [ { "title": "BMW Brings Alpina Performance Brand into the Fold", "url": "https://www.caranddriver.com/news/a39396769/bmw-alpina-performance-brand-added/", "description": "After 57 years, the highly respected small tuning firm is being acquired by the automaker, and after 2025 we can expect all future Alpina models to come straight from BMW.", "author": "Mike Duff", "publishedAt": "2022-03-10T09:36:00.000Z", "thumbnail": { "url": "https://hips.hearstapps.com/hmg-prod.s3.amazonaws.com/images/2022-bmw-alpina-b8-gran-coupe-4-1646929819.jpg?crop=0.702xw:0.527xh;0.126xw,0.284xh&resize=640:*", "mimeType": "image/jpeg" } }, { "title": "Quick Look: 2022 BMW M 1000 RR—Ultimate Evolution, In The April Issue", "url": "https://www.roadracingworld.com/news/quick-look-2022-bmw-m-1000-rr-ultimate-evolution-in-the-april-issue/", "description": "BMW's M 1000 RR, the company's most advanced and highest-performing streetbike, on track in the April 2022 issue of Roadracing World magazine.", "publishedAt": "2022-04-08T18:30:57.000Z", "thumbnail": { "url": "https://www.roadracingworld.com/wp-content/uploads/2022/04/0422_QL_BMW_A_Toye-8-M1000RR-DSC_0699_P_WEB-A_1649440221.jpg", "mimeType": "image/jpeg" } }, { "title": "BMW M2 G87 Seats Leak Might not be the Original Ones", "url": "https://www.bmwblog.com/2022/04/07/bmw-m2-g87-seats-leak/", "description": "BMW community quickly reposted the new seats as a leak of the carbon bucket seats found in the upcoming BMW M2 G87.", "publishedAt": "2022-04-07T21:35:51.000Z", "thumbnail": { "url": "https://cdn.bmwblog.com/wp-content/uploads/2022/03/2023-bmw-m8-carbon-bucket-seats-00-scaled.jpg", "mimeType": "image/jpeg" } } ] }

Create Feed

Create feeds from websites by using the following parameters:

Parameters

urlREQUIRED

A valid website URL is required (example: https://bbc.com)

Returns

A feed with posts is returned. Otherwise, an error is returned.

POST /v1/feed

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 var axios = require('axios'); var data = JSON.stringify({"url":"https://bbc.com"}); var config = { method: 'post', url: 'https://rss.app/api/v1/feed', headers: { 'Authorization': 'Bearer c_ciwogLkIa8rJQ9:s_i12EVmZ4D5d3ZZ7Q8OLQ21', 'Content-Type': 'application/json' }, data : data }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); });

RESPONSE

{ "id": "tq7X9v2dKgkTre59", "title": "bmw", "description": "#bmw generated by RSS.app", "source": { "url": "https://rss.app/rss-feed?keyword=bmw" }, "items": [ { "title": "BMW Brings Alpina Performance Brand into the Fold", "url": "https://www.caranddriver.com/news/a39396769/bmw-alpina-performance-brand-added/", "description": "After 57 years, the highly respected small tuning firm is being acquired by the automaker, and after 2025 we can expect all future Alpina models to come straight from BMW.", "author": "Mike Duff", "publishedAt": "2022-03-10T09:36:00.000Z", "thumbnail": { "url": "https://hips.hearstapps.com/hmg-prod.s3.amazonaws.com/images/2022-bmw-alpina-b8-gran-coupe-4-1646929819.jpg?crop=0.702xw:0.527xh;0.126xw,0.284xh&resize=640:*", "mimeType": "image/jpeg" } }, { "title": "Quick Look: 2022 BMW M 1000 RR—Ultimate Evolution, In The April Issue", "url": "https://www.roadracingworld.com/news/quick-look-2022-bmw-m-1000-rr-ultimate-evolution-in-the-april-issue/", "description": "BMW's M 1000 RR, the company's most advanced and highest-performing streetbike, on track in the April 2022 issue of Roadracing World magazine.", "publishedAt": "2022-04-08T18:30:57.000Z", "thumbnail": { "url": "https://www.roadracingworld.com/wp-content/uploads/2022/04/0422_QL_BMW_A_Toye-8-M1000RR-DSC_0699_P_WEB-A_1649440221.jpg", "mimeType": "image/jpeg" } }, { "title": "BMW M2 G87 Seats Leak Might not be the Original Ones", "url": "https://www.bmwblog.com/2022/04/07/bmw-m2-g87-seats-leak/", "description": "BMW community quickly reposted the new seats as a leak of the carbon bucket seats found in the upcoming BMW M2 G87.", "publishedAt": "2022-04-07T21:35:51.000Z", "thumbnail": { "url": "https://cdn.bmwblog.com/wp-content/uploads/2022/03/2023-bmw-m8-carbon-bucket-seats-00-scaled.jpg", "mimeType": "image/jpeg" } } ] }

Delete Feed

You can delete feeds via the feed management page of the RSS.app dashboard. Deleted feeds will be removed from the bundles. Feeds can also be deleted via the API.

Parameters

No parameters

Returns

The feed id and the deletion flag is returned. If the feed has already been deleted, an error message is returned stating ‘feed has already been deleted’.

DELETE /v1/feed/:id

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 var axios = require('axios'); var config = { method: 'delete', url: 'https://rss.app/api/v1/feed/{{feedId}}', headers: { 'Authorization': 'Bearer YOUR_API_KEY:YOUR_API_SECRET' } }; axios(config) .then(function (response) { console.log(JSON.stringify(response.data)); }) .catch(function (error) { console.log(error); });

RESPONSE

{ "id": "zScdlc0QIdfuBNA6", "deleted": true }