API Reference

Welcome to the RSS.app API documentation! The RSS.app API is a RESTful web service designed for developers who want to interact with RSS.app programmatically. This API allows you to create, delete, and retrieve RSS feeds.

The API uses standard HTTP methods (such as GET, POST, PUT, and DELETE) to send requests and receive responses. It expects JSON-encoded request bodies and returns JSON-encoded responses, accompanied by appropriate HTTP status codes.

In this documentation, you'll find detailed information about available endpoints, required parameters, and sample code snippets to help you get started with the RSS.app API.

BASE URL

https://api.rss.app

Authentication

RSS.app uses API keys to authenticate requests, ensuring that only authorized users can access the API. To view and manage your API keys, visit the RSS.app Dashboard.

It is crucial to keep your API keys private and secure. Do not share them with anyone, and avoid including them in any publicly accessible resources, such as client-side code or GitHub repositories.

Please note that all API requests must be made over HTTPS. Any calls made over plain HTTP will fail. Additionally, API requests without proper authentication will also be rejected.

YOUR API KEY

A sample test API key is provided in all the examples throughout this documentation, allowing you to test any example right away.

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

Errors

The RSS.app API uses conventional HTTP response codes 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).

By inspecting the response and the included error attributes, you can diagnose issues with your API requests and implement appropriate error handling.

When an error occurs, the API returns a JSON object containing the following attributes.

Attributes

messagestring

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

statusCodenumber

The HTTP status code associated with the error.

errorsarray

A container for all error elements, each containing:

titlestring

A message providing more details about the specific 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.)

Feeds

Feeds represents news feeds in your RSS.app account. With the RSS.app API, you can effortlessly manage your news feeds by performing various actions such as creating, retrieving, deleting, or listing all the feeds associated with your account.

Each feed encapsulates a collection of items, including titles, images, and short descriptions of individual posts. By utilizing the API, you can efficiently organize and curate your news feeds, ensuring that you stay up-to-date with the latest content from your favorite sources.

The Feed Object

Attributes

idstring

Unique identifier for the object.

titlestring

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

source_urlstring

Source URL. The URL the feed was created from.

rss_feed_urlstring

RSS Feed URL. The URL to retrieve the RSS feed.

descriptionstring

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

iconstring

URL of the icon of the feed.

itemsarray

List that represents the articles attached to feed object.

urlstring

The URL of the resource described by the item.

titlestring

Title

description_textstring

Description in plain text format

description_htmlstring

Description in HTML format. If there is no description, this field will be empty.

thumbnailstring

Thumbnail URL

authorsarray

Array of authors as objects. If there is no author, an empty array will be returned.

authorsobject

Object represents an author

namestring

Name of the author

date_publisheddate string

Published date

ENDPOINTS

POST /v1/feeds

GET /v1/feeds/:id

GET /v1/feeds

DELETE /v1/feeds

THE FEED OBJECT

{
    "id": "cYVBYcpUEbgXfg9v",
    "title": "BBC - Homepage",
    "rss_feed_url": "https://rss.app/feeds/cYVBYcpUEbgXfg9v.xml",
    "source_url": "https://bbc.com",
    "description": "Breaking news, sport, TV, radio and a whole lot more. The BBC informs, educates and entertains - wherever you are, whatever your age.",
    "items": [
        {
            "url": "https://www.bbc.com/news/av/world-us-canada-65118507",
            "title": "Why this iconic spider sculpture faces removal",
            "description_text": "The Vancouver sculpture is made from recycled waste but is tangled up in a web of bureaucracy.",
            "description_html": "<div><div style="left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;"><iframe src="https://www.bbc.com/news/av-embeds/65118507" style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;" allowfullscreen scrolling="no" allow="encrypted-media"></iframe></div></div>",
            "thumbnail": "https://ichef.bbci.co.uk/news/1024/branded_news/8C30/production/_129188853_p0fcpll9.jpg",
            "date_published": "2023-04-08T01:09:36.000Z",
            "authors": []
        },
        {
            "url": "https://www.bbc.com/travel/article/20230407-the-real-way-to-whip-cream",
            "title": "The 'real' way to whip cream",
            "description_text": "Aptly named after its place of origin, this sweet, thick whipped cream is arguably the best of its kind the "crème de la crème" so to speak.",
            "thumbnail": "https://ychef.files.bbci.co.uk/live/624x351/p0fcxv79.jpg",
            "date_published": "2023-04-08T12:50:28.000Z",
            "authors": [{
                "name": "Angela Dansby"
            }]
        },
        {
            "url": "https://www.bbc.com/news/world-africa-65221385",
            "title": "Thabo Bester: South African murderer who faked death arrested in Tanzania",
            "description_text": "Thabo Bester, known as the "Facebook rapist", escaped from South African prison in May last year.",
            "thumbnail": "https://ichef.bbci.co.uk/news/1024/branded_news/1806B/production/_129311489_gettythumbnails-129143970.jpg",
            "date_published": "2023-04-08T15:47:06.000Z",
            "authors": []
        }
    ]
}

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": "cYVBYcpUEbgXfg9v",
    "title": "BBC - Homepage",
    "rss_feed_url": "https://rss.app/feeds/cYVBYcpUEbgXfg9v.xml",
    "source_url": "https://bbc.com",
    "description": "Breaking news, sport, TV, radio and a whole lot more. The BBC informs, educates and entertains - wherever you are, whatever your age.",
    "items": [
        {
            "url": "https://www.bbc.com/news/av/world-us-canada-65118507",
            "title": "Why this iconic spider sculpture faces removal",
            "description_text": "The Vancouver sculpture is made from recycled waste but is tangled up in a web of bureaucracy.",
            "description_html": "<div><div style="left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;"><iframe src="https://www.bbc.com/news/av-embeds/65118507" style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;" allowfullscreen scrolling="no" allow="encrypted-media"></iframe></div></div>",
            "thumbnail": "https://ichef.bbci.co.uk/news/1024/branded_news/8C30/production/_129188853_p0fcpll9.jpg",
            "date_published": "2023-04-08T01:09:36.000Z",
            "authors": []
        },
        {
            "url": "https://www.bbc.com/travel/article/20230407-the-real-way-to-whip-cream",
            "title": "The 'real' way to whip cream",
            "description_text": "Aptly named after its place of origin, this sweet, thick whipped cream is arguably the best of its kind the "crème de la crème" so to speak.",
            "thumbnail": "https://ychef.files.bbci.co.uk/live/624x351/p0fcxv79.jpg",
            "date_published": "2023-04-08T12:50:28.000Z",
            "authors": [{
                "name": "Angela Dansby"
            }]
        },
        {
            "url": "https://www.bbc.com/news/world-africa-65221385",
            "title": "Thabo Bester: South African murderer who faked death arrested in Tanzania",
            "description_text": "Thabo Bester, known as the "Facebook rapist", escaped from South African prison in May last year.",
            "thumbnail": "https://ichef.bbci.co.uk/news/1024/branded_news/1806B/production/_129311489_gettythumbnails-129143970.jpg",
            "date_published": "2023-04-08T15:47:06.000Z",
            "authors": []
        }
    ]
}

Retrieve 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": "cYVBYcpUEbgXfg9v",
    "title": "BBC - Homepage",
    "rss_feed_url": "https://rss.app/feeds/cYVBYcpUEbgXfg9v.xml",
    "source_url": "https://bbc.com",
    "description": "Breaking news, sport, TV, radio and a whole lot more. The BBC informs, educates and entertains - wherever you are, whatever your age.",
    "items": [
        {
            "url": "https://www.bbc.com/news/av/world-us-canada-65118507",
            "title": "Why this iconic spider sculpture faces removal",
            "description_text": "The Vancouver sculpture is made from recycled waste but is tangled up in a web of bureaucracy.",
            "description_html": "<div><div style="left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;"><iframe src="https://www.bbc.com/news/av-embeds/65118507" style="border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;" allowfullscreen scrolling="no" allow="encrypted-media"></iframe></div></div>",
            "thumbnail": "https://ichef.bbci.co.uk/news/1024/branded_news/8C30/production/_129188853_p0fcpll9.jpg",
            "date_published": "2023-04-08T01:09:36.000Z",
            "authors": []
        },
        {
            "url": "https://www.bbc.com/travel/article/20230407-the-real-way-to-whip-cream",
            "title": "The 'real' way to whip cream",
            "description_text": "Aptly named after its place of origin, this sweet, thick whipped cream is arguably the best of its kind the "crème de la crème" so to speak.",
            "thumbnail": "https://ychef.files.bbci.co.uk/live/624x351/p0fcxv79.jpg",
            "date_published": "2023-04-08T12:50:28.000Z",
            "authors": [{
                "name": "Angela Dansby"
            }]
        },
        {
            "url": "https://www.bbc.com/news/world-africa-65221385",
            "title": "Thabo Bester: South African murderer who faked death arrested in Tanzania",
            "description_text": "Thabo Bester, known as the "Facebook rapist", escaped from South African prison in May last year.",
            "thumbnail": "https://ichef.bbci.co.uk/news/1024/branded_news/1806B/production/_129311489_gettythumbnails-129143970.jpg",
            "date_published": "2023-04-08T15:47:06.000Z",
            "authors": []
        }
    ]
}

List All Feeds

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": 0,
    "limit": 10,
    "data": [
        {
            "id": "cYVBYcpUEbgXfg9v",
            "title": "BBC - Homepage",
            "source_url": "http://bbc.com",
            "rss_feed_url": "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.",
            "url": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg"
        },
        {
            "id": "tRB1VRwysSuwnHlJ",
            "title": "Bitcoin",
            "source_url": "https://rss.app/rss-feed?keyword=vanadzor"
            "rss_feed_url": "https://rss.app/feeds/tRB1VRwysSuwnHlJ.xml",
            "description": "#Bitcoin generated by RSS.app"
        },
        {
            "id": "tq7X9v2dKgkTre59",
            "source_url": "https://rss.app/rss-feed?topicId=technology"
            "rss_feed_url": "https://rss.app/feeds/tq7X9v2dKgkTre59.xml",
            "title": "Technology",
            "description": "#Technology generated by RSS.app"
        },
        {...}
    ]
}

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

Feeds

The Feed Object

Attributes

idstring

titlestring

source_urlstring

rss_feed_urlstring

descriptionstring

iconstring

itemsarray

urlstring

titlestring

description_textstring

description_htmlstring

thumbnailstring

authorsarray

authorsobject

namestring

date_publisheddate string

Create Feed

Parameters

urlREQUIRED

Returns

Retrieve Feed

Parameters

Returns

List All Feeds

Parameters

$limitoptional, default is 10

$offsetoptional, default is 0

Returns

Delete Feed

Parameters

Returns