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.)

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

GET /v1/feed

GET /v1/feed/:id

POST /v1/feed

DELETE /v1/feed

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

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

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

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

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
}

API Reference

Authentication

Errors

Attributes

messagestring

statusCodenumber

errorsarray

titlestring

codestring

Pagination

Parameters

$limitoptional, default is 10

$offsetoptional, default is 0

List Response Format

dataarray

totalnumber

offsetnumber

limitnumber

Feed

Attributes

idstring

titlestring

descriptionstring

sourceobject

urlstring

iconobject

urlstring

mimeTypestring

postsarray

titlestring

urlstring

descriptionstring

authorstring

publishedAtdate string

thumbnailobject

urlstring

mimeTypestring

Feed List

Parameters

$limitoptional, default is 10

$offsetoptional, default is 0

Returns

Get Feed

Parameters

Returns

Create Feed

Parameters

urlREQUIRED

Returns

Delete Feed

Parameters

Returns