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
}