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

Examples show YOUR_API_KEY and YOUR_API_SECRET placeholders. Replace both with your own credentials before running a request.

To test requests using your account, replace both placeholders with your own key and secret, 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.

Send only writable fields in PATCH; effective and limits are read-only. Invalid requests return 400 without partial configuration writes. Missing or other-workspace resources return 404. Plan and demo restrictions return 403. Unsupported filter resource types and locked filters return 409.

CONFIGURATION_BUSY (409) includes Retry-After: 1; retry with backoff. OUTPUT_REFRESH_FAILED (503) means configuration was saved but refresh or queue admission failed. Read the saved state and retry the same update. Workspace writes return after queue admission. Their output refresh runs in the background; the response confirms saved state, not publication. Resource writes await origin cache clearing and conversion calls. Edge cache purges converge separately.

The legacy demo feed-settings GET still returns its author-only response. Other configuration operations require a non-demo key. Concurrent dashboard and API writes use last-write-wins. A global settings request and a global filter request are separate operations.

Attributes

messagestring

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

statusCodenumber

The HTTP status code associated with the error.

errorsarray of objects

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 SUMMARY

200 - OK	The request succeeded.
201 - Created	An advanced filter rule was created or recovered with the same idempotency key.
401 - Unauthorized	Some existing bundle operations use this status when the user is not authorized. Invalid API key credentials return 403.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
403 - Forbidden	Credentials are missing, invalid or inactive, or your account, demo key or plan does not allow this operation.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (for example, locked filters, a busy configuration update, or an idempotency key reused with different data).
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

The request succeeded.

201 - Created

An advanced filter rule was created or recovered with the same idempotency key.

401 - Unauthorized

Some existing bundle operations use this status when the user is not authorized. Invalid API key credentials return 403.

400 - Bad Request

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

403 - Forbidden

Credentials are missing, invalid or inactive, or your account, demo key or plan does not allow this operation.

404 - Not Found

The requested resource doesn't exist.

409 - Conflict

The request conflicts with another request (for example, locked filters, a busy configuration update, or an idempotency key reused with different data).

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.

is_activeboolean

Indicates whether the feed is active.

itemsarray of objects

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 of objects

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

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/:id

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.",
    "icon": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg",
    "is_active": true,
    "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 By URL

Each successful feed creation uses one monthly API operation. See Errors for limits and retry behavior.

Create feeds from websites by using the following parameters:

Parameters

`url`stringrequired

The website URL to create a feed from, for example https://bbc.com.

Returns

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

POST/v1/feeds

curl --location --request POST 'https://api.rss.app/v1/feeds' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "url": "https://bbc.com"
}'

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.",
    "icon": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg",
    "is_active": true,
    "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 feeds from Native RSS Feed by using the following parameters:

Parameters

`url`stringrequired

The native RSS feed URL, for example https://www.bbc.com/future/feed.rss.

Returns

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

POST/v1/feeds

curl --location --request POST 'https://api.rss.app/v1/feeds' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "url": "https://www.bbc.com/future/feed.rss"
}'

RESPONSE

{
    "id": "DMFNG33hY7EFHtw6",
    "title": "BBC Home - Breaking News, World News, U.S. News, Sports, Business, Innovation, Climate, Culture, Travel, Video & Audio",
    "source_url": "https://www.bbc.com/future/feed.rss",
    "rss_feed_url": "https://rss.app/feeds/DMFNG33hY7EFHtw6.xml",
    "description": "Visit BBC for trusted reporting on the latest world and U.S. news, sports, business, climate, innovation, culture and much more.",
    "icon": "https://www.bbc.com/apple-touch-icon.png",
    "is_active": true,
    "items": [
        {
            "url": "https://www.bbc.com/future/article/20231122-the-genes-that-made-us-truly-human-may-also-make-us-ill?ocid=global_future_rss",
            "title": "The genes that make us ill",
            "description_text": "Evolutionary jumpstarts sometimes have far-reaching effects",
            "thumbnail": "https://ychef.files.bbci.co.uk/144x81/p0gv08bz.jpg",
            "date_published": "2023-11-22T14:00:00.000Z",
            "authors": []
        },
        {
            "url": "https://www.bbc.com/future/article/20231120-the-black-mambas-south-africas-all-female-anti-poaching-unit?ocid=global_future_rss",
            "title": "The unarmed women fighting poachers",
            "description_text": "South Africa's all-female anti-poaching unit",
            "thumbnail": "https://ychef.files.bbci.co.uk/144x81/p0gtrzd2.jpg",
            "date_published": "2023-11-21T14:00:00.000Z",
            "authors": []
        },
        {
            "url": "https://www.bbc.com/future/article/20231120-wildebeest-and-wolves-a-secret-weapon-against-climate-change?ocid=global_future_rss",
            "title": "Why wildebeest are good for the climate",
            "description_text": "Animals may be a secret weapon in the fight against climate change",
            "thumbnail": "https://ychef.files.bbci.co.uk/144x81/p0gtspvv.jpg",
            "date_published": "2023-11-20T14:00:00.000Z",
            "authors": []
        }
    ]
}

Create Feed By Keyword

Each successful feed creation uses one monthly API operation. See Errors for limits and retry behavior.

Create feeds from keywords by using the following parameters:

Parameters

`keyword`stringrequired

A valid website keyword is required (example: marketing)

`region`stringrequired

A valid region is required (example: US:en)

Returns

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

POST/v1/feeds

curl --location --request POST 'https://api.rss.app/v1/feeds' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "keyword": "marketing",
  "region": "US:en"
}'

RESPONSE

{
    "id": "tTVYAQfX2VhPOHiv",
    "title": "marketing",
    "source_url": "https://rss.app/rss-feed?keyword=marketing&region=&lang=en",
    "rss_feed_url": "https://rss.app/feeds/tTVYAQfX2VhPOHiv.xml",
    "description": "#marketing generated by RSS.app",
    "icon": "https://rss.app/favicon.ico",
    "is_active": true,
    "items": [
        {
            "url": "https://www.farmprogress.com/commentary/grain-marketing-strategies-meet-tammy-two-step",
            "title": "Grain marketing strategies: Meet Tammy Two-step",
            "description_text": "Advanced Marketing Class: Tammy’s complete approach to marketing grain offers impressive results.",
            "thumbnail": "https://eu-images.contentstack.com/v3/assets/bltdd43779342bd9107/blt5fd6e4e410b872f3/64fa0809fc70f537bed01bda/Market_chart_led_screen_at_price_peak_Getty.jpg?disable=upscale&width=1200&height=630&fit=crop",
            "date_published": "2023-09-08T11:30:00.000Z",
            "authors": []
        },
        {
            "url": "https://campusrecmag.com/how-marketing-keeps-programs-afloat/",
            "title": "How Marketing Keeps Programs Afloat",
            "description_text": "It goes without saying that it takes money to run any athletic program, and programs with larger budgets tend to",
            "thumbnail": "https://campusrecmag.com/wp-content/uploads/2023/09/CR-SepOct-2023-ISTimeSolutions-1.jpg",
            "date_published": "2023-09-08T11:02:32.000Z",
            "authors": []
        },
        {
            "url": "https://www.marketingweek.com/three-steps-to-developing-a-marketing-effectiveness-framework-that-lands-with-the-c-suite/",
            "title": "Three steps to an effectiveness framework the C-suite understands",
            "description_text": "New research from Kantar and Google reveals the actions the most advanced organisations are undertaking to demonstrate marketing effectiveness.",
            "thumbnail": "https://marketingweek.imgix.net/content/uploads/2023/08/29113059/Shutterstock_2218785363.jpg",
            "date_published": "2023-09-08T10:43:00.000Z",
            "authors": [
                {
                    "name": "Richard McLeod"
                }
            ]
        }
    ]
}

Create feeds News headlines from keywords by using the following parameters:

Parameters

`keyword`stringrequired

A valid website keyword is required (example: AI Breakthrough: Quantum Leap in Neural Networks Unveiled)

`region`stringrequired

A valid region is required (example: US:en)

Returns

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

POST/v1/feeds

curl --location --request POST 'https://api.rss.app/v1/feeds' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "keyword": "AI Breakthrough: Quantum Leap in Neural Networks",
  "region": "US:en"
}'

RESPONSE

{
    "id": "tYi56jxVNO1Yqksx",
    "title": "AI Breakthrough: Quantum Leap in Neural Networks Unveiled",
    "source_url": "https://rss.app/rss-feed?keyword=AI%20Breakthrough%3A%20Quantum%20Leap%20in%20Neural%20Networks%20Unveiled&region=US&lang=en",
    "rss_feed_url": "https://rss.app/feeds/tYi56jxVNO1Yqksx.xml",
    "description": "#AI Breakthrough: Quantum Leap in Neural Networks Unveiled generated by RSS.app",
    "icon": "https://rss.app/favicon.ico",
    "is_active": true,
    "items": [
        {
            "url": "https://science.slashdot.org/story/23/10/23/004220/nasa-transmits-patches-to-the-two-voyager-probes-launched-in-1977?utm_source=rss1.0mainlinkanon&utm_medium=feed",
            "title": "NASA Transmits Patches to the Two Voyager Probes Launched in 1977 - Slashdot",
            "description_text": "It's not every day that you get to update the firmware on a device that was produced in the 1970s, writes Hackaday, and rarely is said device well beyond the boundaries of our solar system. This is however exactly what the JPL team in charge of the Voyager 1 & 2 missions are facing, as they...",
            "thumbnail": "https://a.fsdn.com/sd/topics/nasa_64.png",
            "date_published": "2023-10-22T12:00:00.000Z",
            "authors": []
        },
        {
            "url": "https://science.slashdot.org/story/23/10/20/1225206/pfizer-hikes-price-of-covid-antiviral-paxlovid-from-530-to-nearly-1400",
            "title": "Pfizer Hikes Price of COVID Antiviral Paxlovid From $530 To Nearly $1,400 - Slashdot",
            "description_text": "Pfizer this week revealed that it raised the list price of a course of Paxlovid -- its lifesaving antiviral drug used to reduce the risk of severe COVID-19 in those most vulnerable -- to nearly $1,400, more than double the roughly $530 the US government has paid for the treatment in the emergency ph...",
            "thumbnail": "https://a.fsdn.com/sd/topics/business_64.png",
            "date_published": "2023-10-20T12:00:00.000Z",
            "authors": []
        },
        {
            "url": "https://www.scientific-computing.com/article/can-photonics-deliver-next-breakthrough-research-computing-0",
            "title": "Can photonics deliver the next breakthrough in research computing? | Scientific Computing World",
            "description_text": "How will this new computing revolution impact scientists and engineers' research capabilities?",
            "thumbnail": null,
            "date_published": "2023-10-16T13:34:26.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

sortenum

Sorts the articles in the feed.
Available values: last_added, date.
If omitted, the feed uses the sort preference set in the dashboard.

Returns

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

GET/v1/feeds/:feed_id

curl --location --request GET 'https://api.rss.app/v1/feeds/:feed_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

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.",
    "icon": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg",
    "is_active": true,
    "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

limitinteger · default is 10

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

offsetinteger · 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/feeds

curl --location --request GET 'https://api.rss.app/v1/feeds?limit=10' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

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.",
            "icon": "https://gn-web-assets.api.bbc.com/wwhp/20220322-0833-37491ec2b6e5b4c43bda3673e521e8164a789b87/responsive/img/apple-touch/apple-touch-180.jpg",
            "is_active": true
        },
        {
            "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",
            "icon": "https://rss.app/favicon.ico",
            "is_active": true
        },
        {
            "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",
            "icon": "https://rss.app/favicon.ico",
            "is_active": true
        },
        {...}
    ]
}

Update Feed

Update an existing feed by its unique feed ID.

Parameters

`id`stringrequired

Unique identifier for the object.

More parameters

titlestring

Feed title. The title of the feed.

descriptionstring

Description. The description of the feed.

iconstring

URL of the icon of the feed.

PATCH/v1/feeds/:feed_id

curl --location --request PATCH 'https://api.rss.app/v1/feeds/:feed_id' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "New title for Feed"
}'

RESPONSE

{
    "id": "ty0efZXfUX3BQoh8",
    "title": "New title for Feed",
    "source_url": "https://rss.app/rss-feed?topicId=technology",
    "rss_feed_url": "https://rss.app/feeds/ty0efZXfUX3BQoh8.xml",
    "description": "#Technology generated by RSS.app",
    "icon": "https://rss.app/favicon.ico",
    "is_active": true
}

Feeds / settings

Get Feed Settings

Retrieve output settings for an existing feed.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

Fallback HTTP(S) image URL, up to 2048 characters. A non-null write requires enable_placeholder_for_image to be true. Credentials in the URL are not allowed. Set null only while the fallback is disabled.

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

Author mode: author, website_name, hostname or custom. On bundles custom uses each member feed’s author settings and has no bundle-wide name. On feeds/workspace custom requires a string custom_author; an empty string is supported for compatibility.

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

customAuthorstring | null

Legacy production alias of custom_author. Retained for existing clients; use custom_author in new integrations.

overridesobject

Which saved local sections are active.

post_limitboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

image_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

title_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

description_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

date_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

guid_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

twitterboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

youtubeboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

facebookboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

author_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

instagramboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

effectiveobject

Resolved output settings after workspace inheritance. Read-only; this does not confirm publication is complete.

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the response

Additional output settings

Description, date, GUID, author and social-media fields use the same section overrides as the dashboard. Author modes are author, website_name, hostname and custom; set active_display_author to false for automatic output.

{ "is_limit_in_description": true, "char_limit_in_description": 200, "active_display_author": true, "display_author_type": "website_name" }

Resize, translation, UTM and affiliate settings have separate precedence rules. Enabled workspace resizing takes priority. Translation is local to a feed or bundle and needs a target language. Use enable_global_utm_tags to choose workspace UTM values. Disabled local affiliate tags may still use workspace affiliate rules.

Translation, UTM and affiliate tags require their plan entitlements. Resizing requires a paid plan; workspace resizing and estimated dates also require their workspace features. Widget allowed_domains is workspace-only. External translator API keys are never included in this reference or returned by these endpoints.

The top-level fields are saved local values. Read effective to see the values actually used in the output.

No include query parameter is needed. Effective values describe resolved configuration, not completed publication.

Local values or workspace defaults?

Each section has an overrides switch:

true — use the saved local values.
false — use the workspace defaults.

post_limit: Post count.
image_tag: Image tags and fallback image.
title_tag: Title length.

Value limits

Post counts must be positive integers within your plan limit.
Title length: char_limit_in_title accepts 0–1000 characters.
Fallback image: placeholder_for_image accepts an HTTP(S) URL up to 2048 characters.
Custom author: up to 255 characters. Send custom_author: null to reset it.

Response: 200 OK

GET/v1/feeds/:feed_id/settings

curl --location --request GET 'https://api.rss.app/v1/feeds/:feed_id/settings' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "post_limit": 50,
  "image_in_media": true,
  "image_in_enclosure": true,
  "enable_placeholder_for_image": false,
  "placeholder_for_image": null,
  "is_limit_in_title": false,
  "char_limit_in_title": null,
  "cache_bust_placeholder_image": false,
  "remove_all_html_from_description": false,
  "keep_line_breaks_in_description": false,
  "image_in_description": false,
  "remove_all_images_in_description": false,
  "include_iframes_when_possible": false,
  "is_limit_in_description": false,
  "read_more_in_description": false,
  "only_ascii": false,
  "ellipsis_in_description": false,
  "allow_future_dates": false,
  "estimated_article_dates": false,
  "force_estimated_article_dates": false,
  "permalink_for_xml": false,
  "twitter_include_replies": false,
  "twitter_embeds": false,
  "twitter_html_description": false,
  "twitter_prefix_with_username": false,
  "twitter_remove_url_from_title": false,
  "youtube_video_iframe": false,
  "youtube_description": false,
  "facebook_original_source": false,
  "instagram_videos": false,
  "char_limit_in_description": null,
  "timezone_offset": null,
  "active_display_author": false,
  "display_author_type": "hostname",
  "custom_author": null,
  "customAuthor": null,
  "overrides": {
    "post_limit": true,
    "image_tag": true,
    "title_tag": false,
    "description_tag": false,
    "date_tag": false,
    "guid_tag": false,
    "twitter": false,
    "youtube": false,
    "facebook": false,
    "author_tag": false,
    "instagram": false
  },
  "effective": {
    "post_limit": 50,
    "image_in_media": true,
    "image_in_enclosure": true,
    "enable_placeholder_for_image": false,
    "placeholder_for_image": null,
    "is_limit_in_title": false,
    "char_limit_in_title": null,
    "cache_bust_placeholder_image": false,
    "remove_all_html_from_description": false,
    "keep_line_breaks_in_description": false,
    "image_in_description": false,
    "remove_all_images_in_description": false,
    "include_iframes_when_possible": false,
    "is_limit_in_description": false,
    "read_more_in_description": false,
    "only_ascii": false,
    "ellipsis_in_description": false,
    "allow_future_dates": false,
    "estimated_article_dates": false,
    "force_estimated_article_dates": false,
    "permalink_for_xml": false,
    "twitter_include_replies": false,
    "twitter_embeds": false,
    "twitter_html_description": false,
    "twitter_prefix_with_username": false,
    "twitter_remove_url_from_title": false,
    "youtube_video_iframe": false,
    "youtube_description": false,
    "facebook_original_source": false,
    "instagram_videos": false,
    "char_limit_in_description": null,
    "timezone_offset": null,
    "active_display_author": false,
    "display_author_type": "hostname",
    "custom_author": null
  }
}

Feeds / settings

Update Feed Settings

Update output settings for an existing feed. Omitted fields stay unchanged.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

overridesobject

Partial section switches. False resumes workspace inheritance without erasing saved local values. Do not disable a section and write its fields in the same request.

post_limitboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

image_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

title_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

description_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

date_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

guid_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

twitterboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

youtubeboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

facebookboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

author_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

instagramboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

customAuthorstring | null

Legacy production alias of custom_author. Retained for existing clients; use custom_author in new integrations.

overridesobject

Which saved local sections are active.

post_limitboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

image_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

title_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

description_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

date_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

guid_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

twitterboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

youtubeboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

facebookboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

author_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

instagramboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

effectiveobject

Resolved output settings after workspace inheritance. Read-only; this does not confirm publication is complete.

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Changing settings

Send only the fields you want to change. Other fields keep their current values.

{ "post_limit": 50 }

This sets the output to at most 50 posts, within your plan limit. It does not change API list pagination.

Local values or workspace defaults?

Each section has an overrides switch:

true — use the saved local values.
false — use the workspace defaults.

post_limit: Post count.
image_tag: Image tags and fallback image.
title_tag: Title length.

Editing a field turns on its whole local section. When a section was inherited, its other fields start with the current workspace defaults.

To use the workspace image settings again, send:

{ "overrides": { "image_tag": false } }

Do not send image fields in that same request. Setting the switch to true alone restores the currently saved local section, not an older dashboard version.

Value limits

Post counts must be positive integers within your plan limit.
Title length: char_limit_in_title accepts 0–1000 characters.
Fallback image: placeholder_for_image accepts an HTTP(S) URL up to 2048 characters.
Custom author: up to 255 characters. Send custom_author: null to reset it.

false disables a flag. null clears the title limit or fallback URL only when that feature is disabled; it does not turn on inheritance.

Response: 200 OK

PATCH/v1/feeds/:feed_id/settings

curl --location --request PATCH 'https://api.rss.app/v1/feeds/:feed_id/settings' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "post_limit": 50,
  "image_in_media": true
}'

Response · 200 OK

{
  "post_limit": 50,
  "image_in_media": true,
  "image_in_enclosure": true,
  "enable_placeholder_for_image": false,
  "placeholder_for_image": null,
  "is_limit_in_title": false,
  "char_limit_in_title": null,
  "cache_bust_placeholder_image": false,
  "remove_all_html_from_description": false,
  "keep_line_breaks_in_description": false,
  "image_in_description": false,
  "remove_all_images_in_description": false,
  "include_iframes_when_possible": false,
  "is_limit_in_description": false,
  "read_more_in_description": false,
  "only_ascii": false,
  "ellipsis_in_description": false,
  "allow_future_dates": false,
  "estimated_article_dates": false,
  "force_estimated_article_dates": false,
  "permalink_for_xml": false,
  "twitter_include_replies": false,
  "twitter_embeds": false,
  "twitter_html_description": false,
  "twitter_prefix_with_username": false,
  "twitter_remove_url_from_title": false,
  "youtube_video_iframe": false,
  "youtube_description": false,
  "facebook_original_source": false,
  "instagram_videos": false,
  "char_limit_in_description": null,
  "timezone_offset": null,
  "active_display_author": false,
  "display_author_type": "hostname",
  "custom_author": null,
  "customAuthor": null,
  "overrides": {
    "post_limit": true,
    "image_tag": true,
    "title_tag": false,
    "description_tag": false,
    "date_tag": false,
    "guid_tag": false,
    "twitter": false,
    "youtube": false,
    "facebook": false,
    "author_tag": false,
    "instagram": false
  },
  "effective": {
    "post_limit": 50,
    "image_in_media": true,
    "image_in_enclosure": true,
    "enable_placeholder_for_image": false,
    "placeholder_for_image": null,
    "is_limit_in_title": false,
    "char_limit_in_title": null,
    "cache_bust_placeholder_image": false,
    "remove_all_html_from_description": false,
    "keep_line_breaks_in_description": false,
    "image_in_description": false,
    "remove_all_images_in_description": false,
    "include_iframes_when_possible": false,
    "is_limit_in_description": false,
    "read_more_in_description": false,
    "only_ascii": false,
    "ellipsis_in_description": false,
    "allow_future_dates": false,
    "estimated_article_dates": false,
    "force_estimated_article_dates": false,
    "permalink_for_xml": false,
    "twitter_include_replies": false,
    "twitter_embeds": false,
    "twitter_html_description": false,
    "twitter_prefix_with_username": false,
    "twitter_remove_url_from_title": false,
    "youtube_video_iframe": false,
    "youtube_description": false,
    "facebook_original_source": false,
    "instagram_videos": false,
    "char_limit_in_description": null,
    "timezone_offset": null,
    "active_display_author": false,
    "display_author_type": "hostname",
    "custom_author": null
  }
}

Feeds / filter

Get Feed Filter

Retrieve the filter for an existing feed.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

effectiveobject

Filter after workspace lists and flags are combined. Read-only.

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

limitsobject

Read-only keyword counts and plan limits.

max_keywords_per_listinteger

Plan limit for each combined keyword list.

local_whitelist_countinteger

Number of saved whitelist keywords.

local_blacklist_countinteger

Number of saved blacklist keywords.

inherited_whitelist_countinteger

Workspace whitelist keywords included in the effective filter.

inherited_blacklist_countinteger

Workspace blacklist keywords included in the effective filter.

exceeds_current_limitboolean

Whether the current combined list exceeds the plan limit. Existing keywords remain active; new growth is refused.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the response

Top-level fields show the saved local filter. effective shows the filter after workspace defaults are applied. limits reports local and inherited keyword counts.

Combining local and global filters

When a local filter has default_filter: true:

Global and local keyword lists are combined. Their enabled matching fields apply to every word in the combined list. The whitelist is checked as one combined list.
An enabled global flag stays enabled even if its local value is false.
The more aggressive enabled similar-title setting takes priority.

For example, global blacklist ["ads"] plus local blacklist ["sponsored"] blocks both keywords. Clearing the local list still leaves “ads” blocked.

To use only the local filter, its default_filter must be false.

Filtering order

no_images hides posts without an original image, even when a fallback image is configured.
Blacklist checks run before text replacements and title truncation.

Keyword limits

Your plan limits each keyword list. Inherited keywords count toward the local total.

If a global change or plan downgrade puts an existing list over the limit, its keywords remain active. You can shrink it, but cannot grow it further. Check limits.exceeds_current_limit for this state.

Targeting and other filter options

Where keywords are matched

Use whitelist_by_title, whitelist_by_description, whitelist_by_link or whitelist_by_image_url. Blacklist options use the same endings with blackList.

whitelist_contains_word and blacklist_contains_word enable partial matching.

For categories, use whitelist_by_keywords or blacklist_by_keywords.

Missing content and duplicates

no_images, no_date and no_description hide posts missing that content. hide_non_secure_links hides insecure links.

Use duplicate_titles, duplicate_descriptions or duplicate_similar_titles to remove duplicates. The similar-title threshold accepts balanced, strict or aggressive.

Title cleanup and date window

Use title_auto_cleaner and title_replace_keywords for title cleanup.

For a date window, set enable_date_filter, date_period (DAY or HOUR) and seconds_until. The enabled window must equal 1–100000 whole days or hours.

Response: 200 OK

GET/v1/feeds/:feed_id/filter

curl --location --request GET 'https://api.rss.app/v1/feeds/:feed_id/filter' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "whitelist": [],
  "blacklist": [
    "sponsored"
  ],
  "whitelist_by_title": false,
  "whitelist_by_description": false,
  "whitelist_by_link": false,
  "whitelist_by_image_url": false,
  "whitelist_contains_word": false,
  "blacklist_by_title": true,
  "blacklist_by_description": false,
  "blacklist_by_link": false,
  "blacklist_by_image_url": false,
  "blacklist_contains_word": false,
  "no_images": true,
  "no_date": false,
  "no_description": false,
  "hide_non_secure_links": false,
  "duplicate_titles": false,
  "duplicate_descriptions": false,
  "duplicate_similar_titles": false,
  "duplicate_similar_titles_threshold": "balanced",
  "default_filter": true,
  "whitelist_by_keywords": false,
  "blacklist_by_keywords": false,
  "enable_date_filter": false,
  "seconds_until": 604800,
  "date_period": "DAY",
  "title_auto_cleaner": false,
  "title_replace_keywords": [],
  "effective": {
    "whitelist": [],
    "blacklist": [
      "sponsored"
    ],
    "whitelist_by_title": false,
    "whitelist_by_description": false,
    "whitelist_by_link": false,
    "whitelist_by_image_url": false,
    "whitelist_contains_word": false,
    "blacklist_by_title": true,
    "blacklist_by_description": false,
    "blacklist_by_link": false,
    "blacklist_by_image_url": false,
    "blacklist_contains_word": false,
    "no_images": true,
    "no_date": false,
    "no_description": false,
    "hide_non_secure_links": false,
    "duplicate_titles": false,
    "duplicate_descriptions": false,
    "duplicate_similar_titles": false,
    "duplicate_similar_titles_threshold": "balanced",
    "default_filter": true,
    "whitelist_by_keywords": false,
    "blacklist_by_keywords": false,
    "enable_date_filter": false,
    "seconds_until": 604800,
    "date_period": "DAY",
    "title_auto_cleaner": false,
    "title_replace_keywords": []
  },
  "limits": {
    "max_keywords_per_list": 50,
    "local_whitelist_count": 0,
    "local_blacklist_count": 1,
    "inherited_whitelist_count": 0,
    "inherited_blacklist_count": 0,
    "exceeds_current_limit": false
  }
}

Feeds / filter

Update Feed Filter

Update the filter for an existing feed. Omitted fields stay unchanged.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

effectiveobject

Filter after workspace lists and flags are combined. Read-only.

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

limitsobject

Read-only keyword counts and plan limits.

max_keywords_per_listinteger

Plan limit for each combined keyword list.

local_whitelist_countinteger

Number of saved whitelist keywords.

local_blacklist_countinteger

Number of saved blacklist keywords.

inherited_whitelist_countinteger

Workspace whitelist keywords included in the effective filter.

inherited_blacklist_countinteger

Workspace blacklist keywords included in the effective filter.

exceeds_current_limitboolean

Whether the current combined list exceeds the plan limit. Existing keywords remain active; new growth is refused.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Changing a keyword list

A supplied list replaces the saved list. Send [] to clear it. Spaces around keywords are removed.

{
  "blacklist": ["sponsored"],
  "blacklist_by_title": true
}

This hides posts whose title matches “sponsored”. Other filter fields stay unchanged.

Combining local and global filters

When a local filter has default_filter: true:

Global and local keyword lists are combined. Their enabled matching fields apply to every word in the combined list. The whitelist is checked as one combined list.
An enabled global flag stays enabled even if its local value is false.
The more aggressive enabled similar-title setting takes priority.

For example, global blacklist ["ads"] plus local blacklist ["sponsored"] blocks both keywords. Clearing the local list still leaves “ads” blocked.

To use only the local filter, send default_filter:

{ "default_filter": false }

Filtering order

no_images hides posts without an original image, even when a fallback image is configured.
Blacklist checks run before text replacements and title truncation.

Keyword limits

Your plan limits each keyword list. Inherited keywords count toward the local total.

Targeting and other filter options

Where keywords are matched

Use whitelist_by_title, whitelist_by_description, whitelist_by_link or whitelist_by_image_url. Blacklist options use the same endings with blackList.

whitelist_contains_word and blacklist_contains_word enable partial matching.

For categories, use whitelist_by_keywords or blacklist_by_keywords.

Missing content and duplicates

no_images, no_date and no_description hide posts missing that content. hide_non_secure_links hides insecure links.

Use duplicate_titles, duplicate_descriptions or duplicate_similar_titles to remove duplicates. The similar-title threshold accepts balanced, strict or aggressive.

Title cleanup and date window

Use title_auto_cleaner and title_replace_keywords for title cleanup.

For a date window, set enable_date_filter, date_period (DAY or HOUR) and seconds_until. The enabled window must equal 1–100000 whole days or hours.

Response: 200 OK

PATCH/v1/feeds/:feed_id/filter

curl --location --request PATCH 'https://api.rss.app/v1/feeds/:feed_id/filter' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "blacklist": [
    "sponsored"
  ],
  "blacklist_by_title": true,
  "no_images": true
}'

Response · 200 OK

{
  "whitelist": [],
  "blacklist": [
    "sponsored"
  ],
  "whitelist_by_title": false,
  "whitelist_by_description": false,
  "whitelist_by_link": false,
  "whitelist_by_image_url": false,
  "whitelist_contains_word": false,
  "blacklist_by_title": true,
  "blacklist_by_description": false,
  "blacklist_by_link": false,
  "blacklist_by_image_url": false,
  "blacklist_contains_word": false,
  "no_images": true,
  "no_date": false,
  "no_description": false,
  "hide_non_secure_links": false,
  "duplicate_titles": false,
  "duplicate_descriptions": false,
  "duplicate_similar_titles": false,
  "duplicate_similar_titles_threshold": "balanced",
  "default_filter": true,
  "whitelist_by_keywords": false,
  "blacklist_by_keywords": false,
  "enable_date_filter": false,
  "seconds_until": 604800,
  "date_period": "DAY",
  "title_auto_cleaner": false,
  "title_replace_keywords": [],
  "effective": {
    "whitelist": [],
    "blacklist": [
      "sponsored"
    ],
    "whitelist_by_title": false,
    "whitelist_by_description": false,
    "whitelist_by_link": false,
    "whitelist_by_image_url": false,
    "whitelist_contains_word": false,
    "blacklist_by_title": true,
    "blacklist_by_description": false,
    "blacklist_by_link": false,
    "blacklist_by_image_url": false,
    "blacklist_contains_word": false,
    "no_images": true,
    "no_date": false,
    "no_description": false,
    "hide_non_secure_links": false,
    "duplicate_titles": false,
    "duplicate_descriptions": false,
    "duplicate_similar_titles": false,
    "duplicate_similar_titles_threshold": "balanced",
    "default_filter": true,
    "whitelist_by_keywords": false,
    "blacklist_by_keywords": false,
    "enable_date_filter": false,
    "seconds_until": 604800,
    "date_period": "DAY",
    "title_auto_cleaner": false,
    "title_replace_keywords": []
  },
  "limits": {
    "max_keywords_per_list": 50,
    "local_whitelist_count": 0,
    "local_blacklist_count": 1,
    "inherited_whitelist_count": 0,
    "inherited_blacklist_count": 0,
    "exceeds_current_limit": false
  }
}

Feeds / Filter rules

List Feed Filter Rules

Retrieve advanced filter rules for an existing feed.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A list of rules in execution order.

Response attributes

dataarray of objects

Rules in creation and execution order. This list is not paginated; at most 21 rules are allowed.

idstring

Rule identifier used for update and delete requests.

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the list

The data array contains the rules in execution order. Use each rule’s id to update or delete it. Rules run in creation order. Each filter allows up to 21 rules and only one text_case rule.

Available rule types

Text: replace, remove, add_prefix, add_suffix, text_case
Links: replace_url, remove_url, remove_all_urls, replace_url_by_condition
Images: replace_image_by_condition
Visibility: hide_post

Targets, replacements and regular expressions

Choose a target

Text rules use search_title or search_description. hide_post also supports search_url, search_image and search_author. URL removal rules require a text target.

Type-specific values

Prefix, suffix and replace_url use take as the added text or full HTTP(S) URL.
Conditional URL/image replacements accept an empty take to replace the whole value.
text_case_mode: uppercase_all, capitalize_first, capitalize_every_word or lowercase_all.
take and put accept at most 255 characters.

Regular expressions

add_reg_exp is supported by replace, remove, replace_url_by_condition, replace_image_by_condition and hide_post. Patterns must compile and contain 1–200 characters. The response contains the saved pattern after safety normalization.

Response: 200 OK

GET/v1/feeds/:feed_id/filter/rules

curl --location --request GET 'https://api.rss.app/v1/feeds/:feed_id/filter/rules' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "data": [
    {
      "id": "RULE_ID",
      "type": "replace",
      "take": "Old brand",
      "put": "New brand",
      "search_title": true,
      "search_description": false,
      "search_url": false,
      "search_image": false,
      "search_author": false,
      "add_reg_exp": false,
      "text_case_mode": "uppercase_all"
    }
  ]
}

Feeds / Filter rules

Create Feed Filter Rule

Create advanced filter rules for an existing feed.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

`type`enumrequired

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

More parameters

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

More parameters

Idempotency-Keystring

A stable 1–128 character key for retrying creation. Reuse the same key and body to get the same live rule. Deleting the rule releases the key.

Returns

201 Created · A JSON object with the following attributes.

Response attributes

idstring

Rule identifier used for update and delete requests.

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Rule order and limits

Rules run in creation order. Each filter allows up to 21 rules and only one text_case rule.

Example: replace text in a title

{
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true
}

take is the text to find; put is its replacement. Each accepts up to 255 characters.

Available rule types

Text: replace, remove, add_prefix, add_suffix, text_case
Links: replace_url, remove_url, remove_all_urls, replace_url_by_condition
Images: replace_image_by_condition
Visibility: hide_post

Retrying creation safely

Send an Idempotency-Key header when creating a rule. Repeating the same key and body returns the existing rule. A conflicting body returns 409.

Keys contain 1–128 letters, digits, dots, underscores, colons or dashes. Protection lasts while the rule exists.

Targets, replacements and regular expressions

Choose a target

Text rules use search_title or search_description. hide_post also supports search_url, search_image and search_author. URL removal rules require a text target.

Type-specific values

Prefix, suffix and replace_url use take as the added text or full HTTP(S) URL.
Conditional URL/image replacements accept an empty take to replace the whole value.
text_case_mode: uppercase_all, capitalize_first, capitalize_every_word or lowercase_all.
take and put accept at most 255 characters.

Regular expressions

Response: 201 Created

POST/v1/feeds/:feed_id/filter/rules

curl --location --request POST 'https://api.rss.app/v1/feeds/:feed_id/filter/rules' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true
}'

Response · 201 Created

{
  "id": "RULE_ID",
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true,
  "search_description": false,
  "search_url": false,
  "search_image": false,
  "search_author": false,
  "add_reg_exp": false,
  "text_case_mode": "uppercase_all"
}

Feeds / Filter rules

Update Feed Filter Rule

Update advanced filter rules for an existing feed. Omitted fields stay unchanged.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

`rule_id`stringrequired

Identifier returned when creating or listing filter rules.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

idstring

Rule identifier used for update and delete requests.

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Rule order and limits

Rules run in creation order. Each filter allows up to 21 rules and only one text_case rule.

Send only the fields to change. Updating a rule keeps its position in the execution order.

Example: replace text in a title

{
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true
}

take is the text to find; put is its replacement. Each accepts up to 255 characters.

Available rule types

Text: replace, remove, add_prefix, add_suffix, text_case
Links: replace_url, remove_url, remove_all_urls, replace_url_by_condition
Images: replace_image_by_condition
Visibility: hide_post

Targets, replacements and regular expressions

Choose a target

Text rules use search_title or search_description. hide_post also supports search_url, search_image and search_author. URL removal rules require a text target.

Type-specific values

Prefix, suffix and replace_url use take as the added text or full HTTP(S) URL.
Conditional URL/image replacements accept an empty take to replace the whole value.
text_case_mode: uppercase_all, capitalize_first, capitalize_every_word or lowercase_all.
take and put accept at most 255 characters.

Regular expressions

Response: 200 OK

PATCH/v1/feeds/:feed_id/filter/rules/:rule_id

curl --location --request PATCH 'https://api.rss.app/v1/feeds/:feed_id/filter/rules/:rule_id' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "put": "Updated brand"
}'

Response · 200 OK

{
  "id": "RULE_ID",
  "type": "replace",
  "take": "Old brand",
  "put": "Updated brand",
  "search_title": true,
  "search_description": false,
  "search_url": false,
  "search_image": false,
  "search_author": false,
  "add_reg_exp": false,
  "text_case_mode": "uppercase_all"
}

Feeds / Filter rules

Delete Feed Filter Rule

Delete advanced filter rules for an existing feed.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

`rule_id`stringrequired

Identifier returned when creating or listing filter rules.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

idstring

Deleted rule identifier.

deletedboolean

True when the rule was deleted.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

After deletion

The rule stops applying. A repeated delete returns 404 RULE_NOT_FOUND. Deleting a rule also releases its creation idempotency key.

Response: 200 OK

DELETE/v1/feeds/:feed_id/filter/rules/:rule_id

curl --location --request DELETE 'https://api.rss.app/v1/feeds/:feed_id/filter/rules/:rule_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

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

Feeds / inheritance

Get Feed Filter Inheritance

Retrieve filter inheritance into bundles for an existing feed.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

inherit_in_bundlesboolean

Use the feed’s processed output in every containing bundle. Enabling locks local filter/rule edits; disable before changing them.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the switch

inherit_in_bundles: true means every bundle containing this feed receives its filtered output.

Editing a filter while inheritance is enabled

Local filter and rule changes return 409 FILTER_LOCKED. The current API requires disabling inheritance before editing and enabling it again afterward. Disabling temporarily changes the source used by every containing bundle; a failed sequence can leave it off. Global filter changes can still affect a locked feed.

Other inheritance switches

This switch is independent of default_filter, which combines workspace and local filters. A bundle’s is_bundle_inherit_feed_filter_rules option separately applies supported member-feed rules, including hide-post rules, when enabled for the workspace. It is not needed to use the feed’s processed output. Exactly-once rule execution is not guaranteed when both mechanisms are combined.

Response: 200 OK

GET/v1/feeds/:feed_id/filter/inheritance

curl --location --request GET 'https://api.rss.app/v1/feeds/:feed_id/filter/inheritance' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "inherit_in_bundles": true
}

Feeds / inheritance

Update Feed Filter Inheritance

Update filter inheritance into bundles for an existing feed. Omitted fields stay unchanged.

Path parameters

`feed_id`stringrequired

Feed identifier. Replace the placeholder in the request URL.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

`inherit_in_bundles`booleanrequired

Use the feed’s processed output in every containing bundle. Enabling locks local filter/rule edits; disable before changing them.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

inherit_in_bundlesboolean

Use the feed’s processed output in every containing bundle. Enabling locks local filter/rule edits; disable before changing them.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Enable or disable inheritance

inherit_in_bundles: true means every bundle containing this feed receives its filtered output.

{ "inherit_in_bundles": true }

Send false to disable it. Your plan must support filter inheritance.

Editing a filter while inheritance is enabled

Other inheritance switches

Response: 200 OK

PATCH/v1/feeds/:feed_id/filter/inheritance

curl --location --request PATCH 'https://api.rss.app/v1/feeds/:feed_id/filter/inheritance' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inherit_in_bundles": true
}'

Response · 200 OK

{
  "inherit_in_bundles": true
}

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/feeds/:feed_id

curl --location --request DELETE 'https://api.rss.app/v1/feeds/:feed_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

RESPONSE

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

Bundles

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

The Bundle Object

Attributes

idstring

Unique identifier for the object.

namestring

Bundle name. This can be edited from the RSS.app dashboard.

descriptionstring

Description. The description of the bundle.

iconstring

URL of the icon of the bundle.

feedsarray

Array of id feeds

itemsarray of objects

Array of feeds

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 of objects

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

Object represents an author

namestring

Name of the author

date_publisheddate string

Published date

ENDPOINTS

POST /v1/bundles

GET /v1/bundles/:bundle_id

PATCH /v1/bundles/:bundle_id

PUT/v1/bundles/:bundle_id/feeds/:feed_id

DELETE /v1/bundles/:bundle_id/feeds/:feed_id

DELETE /v1/bundles/:bundle_id

THE BUNDLE OBJECT

{
   "id": "_Jraf3tbwCJZGfJus",
   "name": "Sports",
   "rss_feed_url": "https://rss.app/feeds/_Jraf3tbwCJZGfJus.xml",
   "description": "",
   "icon": "",
   "feeds": [
      "SQ27oAt2BI9Rcf8p",
      "t4f8yuPcD6iyfdXK"
   ],
   "items": [
      {
         "url": "https://www.bbc.com/sport/av/football/67592514",
         "title": "'He's the second best keeper in the league' - Ten Hag on Onana",
         "description_text": "Manchester United manager Erik ten Hag praises Andre Onana's 'strong character' following a series of high-profile errors from the keeper.",
         "thumbnail": "https://ichef.bbci.co.uk/news/1024/cpsprodpb/66BB/production/_131899262_p0gx2m8y.jpg",
         "date_published": "2023-12-01T13:54:46.000Z",
         "authors": []
      },
      {
         "url": "https://olympics.com/en/news/fans-iconic-olympic-moments",
         "title": "'Magical,'  'goosebumps', 'poignant' – sports fans describe watching iconic moments at an Olympic Games",
         "description_text": "From Cathy Freeman's raucously-supported historic run to a dramatic upset in curling that left the arena silent, fans share what it's like to be in the stands at an Olympic Games, as more tickets go on sale for Paris 2024.",
         "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://olympics.com/en/video/nastia-liukin-wins-individual-all-around-gold-beijing-2008-replays\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
         "thumbnail": "https://img.olympics.com/images/image/private/t_social_share_thumb/f_auto/primary/qxiei4gtcnzygvy2zxqm",
         "date_published": "2023-12-01T13:22:02.000Z",
         "authors": [
            {
               "name": "Maggie Hendricks"
            }
         ]
      },
      {
         "url": "https://www.nbcsports.com/nfl/profootballtalk/rumor-mill/news/brock-purdy-im-not-really-sentimental-returning-to-philly",
         "title": "Brock Purdy: I'm not really sentimental returning to Philly",
         "description_text": "One of the most anticipated games of the year will kick off in Philadelphia on Sunday afternoon and one of the reasons everyone has been looking forward to the 49ers' visit is what happened the last time they were in town.",
         "thumbnail": "https://nbcsports.brightspotcdn.com/dims4/default/a21a908/2147483647/strip/true/crop/3000x1688+0+0/resize/1440x810!/quality/90/?url=https%3A%2F%2Fnbc-sports-production-nbc-sports.s3.us-east-1.amazonaws.com%2Fbrightspot%2F89%2F4f%2F0435182e46de8b7c2c9149c504a8%2Fhttps-delivery-gettyimages.com%2Fdownloads%2F1813898176",
         "date_published": "2023-12-01T13:21:02.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/cricket/67590974",
         "title": "Pakistan's Butt given first role since spot-fixing",
         "description_text": "The former Pakistan captain was banned from cricket in 2010 for his part in a spot-fixing scandal.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/C59D/production/_131898505_gettyimages-129525390.jpg",
         "date_published": "2023-12-01T13:19:25.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/tennis/67587319",
         "title": "Nadal to return at January's Brisbane International",
         "description_text": "Former world number one Rafael Nadal will return to tennis at the Brisbane International after nearly a year out with injury.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/11787/production/_124395517_bbcbreakingnewsgraphic.jpg",
         "date_published": "2023-12-01T13:03:50.000Z",
         "authors": []
      }
   ]
}

Create Bundle

Create bundle from your feeds by using the following parameters:

Parameters

`name`stringrequired

A bundle name

`feeds`array of stringsrequired

Array of feeds example ['iVlcKYisg2g3bSwp', 'XRNElr63Q6RQuCNk']

Returns

A bundle returned. Otherwise, an error is returned.

POST/v1/bundles

curl --location --request POST 'https://api.rss.app/v1/bundles' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "New Bundle",
  "feeds": [
    "cYVBYcpUEbgXfg9v"
  ]
}'

RESPONSE

{
   "id": "_Jraf3tbwCJZGfJus",
   "name": "Sports",
   "rss_feed_url": "https://rss.app/feeds/_Jraf3tbwCJZGfJus.xml",
   "description": "",
   "icon": "",
   "feeds": [
      "SQ27oAt2BI9Rcf8p",
      "t4f8yuPcD6iyfdXK"
   ],
   "items": [
      {
         "url": "https://www.bbc.com/sport/av/football/67592514",
         "title": "'He's the second best keeper in the league' - Ten Hag on Onana",
         "description_text": "Manchester United manager Erik ten Hag praises Andre Onana's 'strong character' following a series of high-profile errors from the keeper.",
         "thumbnail": "https://ichef.bbci.co.uk/news/1024/cpsprodpb/66BB/production/_131899262_p0gx2m8y.jpg",
         "date_published": "2023-12-01T13:54:46.000Z",
         "authors": []
      },
      {
         "url": "https://olympics.com/en/news/fans-iconic-olympic-moments",
         "title": "'Magical,'  'goosebumps', 'poignant' – sports fans describe watching iconic moments at an Olympic Games",
         "description_text": "From Cathy Freeman's raucously-supported historic run to a dramatic upset in curling that left the arena silent, fans share what it's like to be in the stands at an Olympic Games, as more tickets go on sale for Paris 2024.",
         "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://olympics.com/en/video/nastia-liukin-wins-individual-all-around-gold-beijing-2008-replays\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
         "thumbnail": "https://img.olympics.com/images/image/private/t_social_share_thumb/f_auto/primary/qxiei4gtcnzygvy2zxqm",
         "date_published": "2023-12-01T13:22:02.000Z",
         "authors": [
            {
               "name": "Maggie Hendricks"
            }
         ]
      },
      {
         "url": "https://www.nbcsports.com/nfl/profootballtalk/rumor-mill/news/brock-purdy-im-not-really-sentimental-returning-to-philly",
         "title": "Brock Purdy: I'm not really sentimental returning to Philly",
         "description_text": "One of the most anticipated games of the year will kick off in Philadelphia on Sunday afternoon and one of the reasons everyone has been looking forward to the 49ers' visit is what happened the last time they were in town.",
         "thumbnail": "https://nbcsports.brightspotcdn.com/dims4/default/a21a908/2147483647/strip/true/crop/3000x1688+0+0/resize/1440x810!/quality/90/?url=https%3A%2F%2Fnbc-sports-production-nbc-sports.s3.us-east-1.amazonaws.com%2Fbrightspot%2F89%2F4f%2F0435182e46de8b7c2c9149c504a8%2Fhttps-delivery-gettyimages.com%2Fdownloads%2F1813898176",
         "date_published": "2023-12-01T13:21:02.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/cricket/67590974",
         "title": "Pakistan's Butt given first role since spot-fixing",
         "description_text": "The former Pakistan captain was banned from cricket in 2010 for his part in a spot-fixing scandal.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/C59D/production/_131898505_gettyimages-129525390.jpg",
         "date_published": "2023-12-01T13:19:25.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/tennis/67587319",
         "title": "Nadal to return at January's Brisbane International",
         "description_text": "Former world number one Rafael Nadal will return to tennis at the Brisbane International after nearly a year out with injury.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/11787/production/_124395517_bbcbreakingnewsgraphic.jpg",
         "date_published": "2023-12-01T13:03:50.000Z",
         "authors": []
      }
   ]
}

Retrieve Bundle

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

The bundle ID can be found from the ‘Create Bundle’ request or the Bundle List’ request.

Parameters

sortenum

Sorts the articles in the bundle.
Available values: last_added, date.
If omitted, the bundle uses the sort preference set in the dashboard.

Returns

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

GET/v1/bundles/:bundle_id

curl --location --request GET 'https://api.rss.app/v1/bundles/:bundle_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

RESPONSE

{
   "id": "_Jraf3tbwCJZGfJus",
   "name": "Sports",
   "rss_feed_url": "https://rss.app/feeds/_Jraf3tbwCJZGfJus.xml",
   "description": "",
   "icon": "",
   "feeds": [
      "SQ27oAt2BI9Rcf8p",
      "t4f8yuPcD6iyfdXK"
   ],
   "items": [
      {
         "url": "https://www.bbc.com/sport/av/football/67592514",
         "title": "'He's the second best keeper in the league' - Ten Hag on Onana",
         "description_text": "Manchester United manager Erik ten Hag praises Andre Onana's 'strong character' following a series of high-profile errors from the keeper.",
         "thumbnail": "https://ichef.bbci.co.uk/news/1024/cpsprodpb/66BB/production/_131899262_p0gx2m8y.jpg",
         "date_published": "2023-12-01T13:54:46.000Z",
         "authors": []
      },
      {
         "url": "https://olympics.com/en/news/fans-iconic-olympic-moments",
         "title": "'Magical,'  'goosebumps', 'poignant' – sports fans describe watching iconic moments at an Olympic Games",
         "description_text": "From Cathy Freeman's raucously-supported historic run to a dramatic upset in curling that left the arena silent, fans share what it's like to be in the stands at an Olympic Games, as more tickets go on sale for Paris 2024.",
         "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://olympics.com/en/video/nastia-liukin-wins-individual-all-around-gold-beijing-2008-replays\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
         "thumbnail": "https://img.olympics.com/images/image/private/t_social_share_thumb/f_auto/primary/qxiei4gtcnzygvy2zxqm",
         "date_published": "2023-12-01T13:22:02.000Z",
         "authors": [
            {
               "name": "Maggie Hendricks"
            }
         ]
      },
      {
         "url": "https://www.nbcsports.com/nfl/profootballtalk/rumor-mill/news/brock-purdy-im-not-really-sentimental-returning-to-philly",
         "title": "Brock Purdy: I'm not really sentimental returning to Philly",
         "description_text": "One of the most anticipated games of the year will kick off in Philadelphia on Sunday afternoon and one of the reasons everyone has been looking forward to the 49ers' visit is what happened the last time they were in town.",
         "thumbnail": "https://nbcsports.brightspotcdn.com/dims4/default/a21a908/2147483647/strip/true/crop/3000x1688+0+0/resize/1440x810!/quality/90/?url=https%3A%2F%2Fnbc-sports-production-nbc-sports.s3.us-east-1.amazonaws.com%2Fbrightspot%2F89%2F4f%2F0435182e46de8b7c2c9149c504a8%2Fhttps-delivery-gettyimages.com%2Fdownloads%2F1813898176",
         "date_published": "2023-12-01T13:21:02.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/cricket/67590974",
         "title": "Pakistan's Butt given first role since spot-fixing",
         "description_text": "The former Pakistan captain was banned from cricket in 2010 for his part in a spot-fixing scandal.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/C59D/production/_131898505_gettyimages-129525390.jpg",
         "date_published": "2023-12-01T13:19:25.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/tennis/67587319",
         "title": "Nadal to return at January's Brisbane International",
         "description_text": "Former world number one Rafael Nadal will return to tennis at the Brisbane International after nearly a year out with injury.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/11787/production/_124395517_bbcbreakingnewsgraphic.jpg",
         "date_published": "2023-12-01T13:03:50.000Z",
         "authors": []
      }
   ]
}

List All Bundles

View a list of bundles created in the account.

Parameters

limitinteger · default is 10

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

offsetinteger · default is 0

Determines the starting point.

Returns

Returns a list of bundles in the account.

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

GET/v1/bundles

curl --location --request GET 'https://api.rss.app/v1/bundles?limit=10' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

RESPONSE

{
    "total": 373,
    "offset": 0,
    "limit": 10,
    "data": [
        {
            "id": "_joPepQ4OTzwPFhNl",
            "name": "BUNDLE API",
            "rss_feed_url": "https://rss.app/feeds/_joPepQ4OTzwPFhNl.xml",
            "description": "",
            "icon": "https://th.bing.com/th/id/OIP.4siKIW3oZ4kEo0vkEVQ5hgHaLH?pid=ImgDet&rs=1",
            "feeds": ["cYVBYcpUEbgXfg9v", "tRB1VRwysSuwnHlJ", "tq7X9v2dKgkTre59"]
        },
        {
            "id": "_tRB1VRwysSuwnHlJ",
            "name": "Sport bundle",
            "description": "Bundle with sport events",
            "rss_feed_url": "https://rss.app/feeds/_tRB1VRwysSuwnHlJ.xml",
            "feeds": []
        },
        {
            "id": "_tq7X9v2dKgkTre59",
            "name": "Logs bundle",
            "rss_feed_url": "https://rss.app/feeds/_tq7X9v2dKgkTre59.xml",
            "description": "Bundle for logs detections",
        },
        {...}
    ]
}

Update Bundle

Update an existing bundle by its unique bundle ID.

Parameters

`id`stringrequired

Unique identifier for the object.

More parameters

namestring

Bundle name. This can be edited from the RSS.app dashboard.

descriptionstring

Description. The description of the bundle.

iconstring

URL of the icon of the bundle.

PATCH/v1/bundles/:bundle_id

curl --location --request PATCH 'https://api.rss.app/v1/bundles/:bundle_id' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "New Bundle"
}'

RESPONSE

{
   "id": "_Jraf3tbwCJZGfJus",
   "name": "Sports",
   "rss_feed_url": "https://rss.app/feeds/_Jraf3tbwCJZGfJus.xml",
   "description": "",
   "icon": "",
   "feeds": [
      "SQ27oAt2BI9Rcf8p",
      "t4f8yuPcD6iyfdXK"
   ],
   "items": [
      {
         "url": "https://www.bbc.com/sport/av/football/67592514",
         "title": "'He's the second best keeper in the league' - Ten Hag on Onana",
         "description_text": "Manchester United manager Erik ten Hag praises Andre Onana's 'strong character' following a series of high-profile errors from the keeper.",
         "thumbnail": "https://ichef.bbci.co.uk/news/1024/cpsprodpb/66BB/production/_131899262_p0gx2m8y.jpg",
         "date_published": "2023-12-01T13:54:46.000Z",
         "authors": []
      },
      {
         "url": "https://olympics.com/en/news/fans-iconic-olympic-moments",
         "title": "'Magical,'  'goosebumps', 'poignant' – sports fans describe watching iconic moments at an Olympic Games",
         "description_text": "From Cathy Freeman's raucously-supported historic run to a dramatic upset in curling that left the arena silent, fans share what it's like to be in the stands at an Olympic Games, as more tickets go on sale for Paris 2024.",
         "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://olympics.com/en/video/nastia-liukin-wins-individual-all-around-gold-beijing-2008-replays\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
         "thumbnail": "https://img.olympics.com/images/image/private/t_social_share_thumb/f_auto/primary/qxiei4gtcnzygvy2zxqm",
         "date_published": "2023-12-01T13:22:02.000Z",
         "authors": [
            {
               "name": "Maggie Hendricks"
            }
         ]
      },
      {
         "url": "https://www.nbcsports.com/nfl/profootballtalk/rumor-mill/news/brock-purdy-im-not-really-sentimental-returning-to-philly",
         "title": "Brock Purdy: I'm not really sentimental returning to Philly",
         "description_text": "One of the most anticipated games of the year will kick off in Philadelphia on Sunday afternoon and one of the reasons everyone has been looking forward to the 49ers' visit is what happened the last time they were in town.",
         "thumbnail": "https://nbcsports.brightspotcdn.com/dims4/default/a21a908/2147483647/strip/true/crop/3000x1688+0+0/resize/1440x810!/quality/90/?url=https%3A%2F%2Fnbc-sports-production-nbc-sports.s3.us-east-1.amazonaws.com%2Fbrightspot%2F89%2F4f%2F0435182e46de8b7c2c9149c504a8%2Fhttps-delivery-gettyimages.com%2Fdownloads%2F1813898176",
         "date_published": "2023-12-01T13:21:02.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/cricket/67590974",
         "title": "Pakistan's Butt given first role since spot-fixing",
         "description_text": "The former Pakistan captain was banned from cricket in 2010 for his part in a spot-fixing scandal.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/C59D/production/_131898505_gettyimages-129525390.jpg",
         "date_published": "2023-12-01T13:19:25.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/tennis/67587319",
         "title": "Nadal to return at January's Brisbane International",
         "description_text": "Former world number one Rafael Nadal will return to tennis at the Brisbane International after nearly a year out with injury.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/11787/production/_124395517_bbcbreakingnewsgraphic.jpg",
         "date_published": "2023-12-01T13:03:50.000Z",
         "authors": []
      }
   ]
}

Add Bundle Feed

You can add feed 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

A bundle returned. Otherwise, an error is returned.

PUT/v1/bundles/:bundle_id/feeds/:feed_id

curl --location --request PUT 'https://api.rss.app/v1/bundles/:bundle_id/feeds/:feed_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

RESPONSE

{
   "id": "_Jraf3tbwCJZGfJus",
   "name": "Sports",
   "rss_feed_url": "https://rss.app/feeds/_Jraf3tbwCJZGfJus.xml",
   "description": "",
   "icon": "",
   "feeds": [
      "SQ27oAt2BI9Rcf8p",
      "t4f8yuPcD6iyfdXK"
   ],
   "items": [
      {
         "url": "https://www.bbc.com/sport/av/football/67592514",
         "title": "'He's the second best keeper in the league' - Ten Hag on Onana",
         "description_text": "Manchester United manager Erik ten Hag praises Andre Onana's 'strong character' following a series of high-profile errors from the keeper.",
         "thumbnail": "https://ichef.bbci.co.uk/news/1024/cpsprodpb/66BB/production/_131899262_p0gx2m8y.jpg",
         "date_published": "2023-12-01T13:54:46.000Z",
         "authors": []
      },
      {
         "url": "https://olympics.com/en/news/fans-iconic-olympic-moments",
         "title": "'Magical,'  'goosebumps', 'poignant' – sports fans describe watching iconic moments at an Olympic Games",
         "description_text": "From Cathy Freeman's raucously-supported historic run to a dramatic upset in curling that left the arena silent, fans share what it's like to be in the stands at an Olympic Games, as more tickets go on sale for Paris 2024.",
         "description_html": "<div><div style=\"left: 0; width: 100%; height: 0; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://olympics.com/en/video/nastia-liukin-wins-individual-all-around-gold-beijing-2008-replays\" style=\"border: 0; top: 0; left: 0; width: 100%; height: 100%; position: absolute;\" allowfullscreen scrolling=\"no\" allow=\"encrypted-media\"></iframe></div></div>",
         "thumbnail": "https://img.olympics.com/images/image/private/t_social_share_thumb/f_auto/primary/qxiei4gtcnzygvy2zxqm",
         "date_published": "2023-12-01T13:22:02.000Z",
         "authors": [
            {
               "name": "Maggie Hendricks"
            }
         ]
      },
      {
         "url": "https://www.nbcsports.com/nfl/profootballtalk/rumor-mill/news/brock-purdy-im-not-really-sentimental-returning-to-philly",
         "title": "Brock Purdy: I'm not really sentimental returning to Philly",
         "description_text": "One of the most anticipated games of the year will kick off in Philadelphia on Sunday afternoon and one of the reasons everyone has been looking forward to the 49ers' visit is what happened the last time they were in town.",
         "thumbnail": "https://nbcsports.brightspotcdn.com/dims4/default/a21a908/2147483647/strip/true/crop/3000x1688+0+0/resize/1440x810!/quality/90/?url=https%3A%2F%2Fnbc-sports-production-nbc-sports.s3.us-east-1.amazonaws.com%2Fbrightspot%2F89%2F4f%2F0435182e46de8b7c2c9149c504a8%2Fhttps-delivery-gettyimages.com%2Fdownloads%2F1813898176",
         "date_published": "2023-12-01T13:21:02.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/cricket/67590974",
         "title": "Pakistan's Butt given first role since spot-fixing",
         "description_text": "The former Pakistan captain was banned from cricket in 2010 for his part in a spot-fixing scandal.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/C59D/production/_131898505_gettyimages-129525390.jpg",
         "date_published": "2023-12-01T13:19:25.000Z",
         "authors": []
      },
      {
         "url": "https://www.bbc.com/sport/tennis/67587319",
         "title": "Nadal to return at January's Brisbane International",
         "description_text": "Former world number one Rafael Nadal will return to tennis at the Brisbane International after nearly a year out with injury.",
         "thumbnail": "https://ichef.bbci.co.uk/live-experience/cps/624/cpsprodpb/11787/production/_124395517_bbcbreakingnewsgraphic.jpg",
         "date_published": "2023-12-01T13:03:50.000Z",
         "authors": []
      }
   ]
}

Bundle 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

A bundle returned. Otherwise, an error is returned.

DELETE/v1/bundles/:bundle_id/feeds/:feed_id

curl --location --request DELETE 'https://api.rss.app/v1/bundles/:bundle_id/feeds/:feed_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

RESPONSE

{
    "id": "_joPepQ4OTzwPFhNl",
    "name": "BUNDLE API",
    "rss_feed_url": "https://rss.app/feeds/_joPepQ4OTzwPFhNl.xml",
    "description": "",
    "icon": "https://th.bing.com/th/id/OIP.4siKIW3oZ4kEo0vkEVQ5hgHaLH?pid=ImgDet&rs=1",
    "feeds": ["cYVBYcpUEbgXfg9v", "tRB1VRwysSuwnHlJ", "tq7X9v2dKgkTre59"]
}

Bundles / settings

Get Bundle Settings

Retrieve output settings for an existing bundle.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

overridesobject

Which saved local sections are active.

post_limitboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

image_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

title_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

description_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

date_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

guid_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

twitterboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

youtubeboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

facebookboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

author_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

instagramboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

effectiveobject

Resolved output settings after workspace inheritance. Read-only; this does not confirm publication is complete.

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the response

Additional output settings

{ "is_limit_in_description": true, "char_limit_in_description": 200, "active_display_author": true, "display_author_type": "website_name" }

The top-level fields are saved local values. Read effective to see the values actually used in the output.

No include query parameter is needed. Effective values describe resolved configuration, not completed publication.

Local values or workspace defaults?

Each section has an overrides switch:

true — use the saved local values.
false — use the workspace defaults.

post_limit: Post count — controls bundle_post_limit.
image_tag: Image tags and fallback image.
title_tag: Title length.

Value limits

Post counts must be positive integers within your plan limit.
Title length: char_limit_in_title accepts 0–1000 characters.
Fallback image: placeholder_for_image accepts an HTTP(S) URL up to 2048 characters.

Response: 200 OK

GET/v1/bundles/:bundle_id/settings

curl --location --request GET 'https://api.rss.app/v1/bundles/:bundle_id/settings' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "bundle_post_limit": 50,
  "image_in_media": true,
  "image_in_enclosure": true,
  "enable_placeholder_for_image": false,
  "placeholder_for_image": null,
  "is_limit_in_title": false,
  "char_limit_in_title": null,
  "cache_bust_placeholder_image": false,
  "remove_all_html_from_description": false,
  "keep_line_breaks_in_description": false,
  "image_in_description": false,
  "remove_all_images_in_description": false,
  "include_iframes_when_possible": false,
  "is_limit_in_description": false,
  "read_more_in_description": false,
  "only_ascii": false,
  "ellipsis_in_description": false,
  "allow_future_dates": false,
  "estimated_article_dates": false,
  "force_estimated_article_dates": false,
  "permalink_for_xml": false,
  "twitter_include_replies": false,
  "twitter_embeds": false,
  "twitter_html_description": false,
  "twitter_prefix_with_username": false,
  "twitter_remove_url_from_title": false,
  "youtube_video_iframe": false,
  "youtube_description": false,
  "facebook_original_source": false,
  "instagram_videos": false,
  "char_limit_in_description": null,
  "timezone_offset": null,
  "active_display_author": false,
  "display_author_type": "hostname",
  "overrides": {
    "post_limit": true,
    "image_tag": true,
    "title_tag": false,
    "description_tag": false,
    "date_tag": false,
    "guid_tag": false,
    "twitter": false,
    "youtube": false,
    "facebook": false,
    "author_tag": false,
    "instagram": false
  },
  "effective": {
    "bundle_post_limit": 50,
    "image_in_media": true,
    "image_in_enclosure": true,
    "enable_placeholder_for_image": false,
    "placeholder_for_image": null,
    "is_limit_in_title": false,
    "char_limit_in_title": null,
    "cache_bust_placeholder_image": false,
    "remove_all_html_from_description": false,
    "keep_line_breaks_in_description": false,
    "image_in_description": false,
    "remove_all_images_in_description": false,
    "include_iframes_when_possible": false,
    "is_limit_in_description": false,
    "read_more_in_description": false,
    "only_ascii": false,
    "ellipsis_in_description": false,
    "allow_future_dates": false,
    "estimated_article_dates": false,
    "force_estimated_article_dates": false,
    "permalink_for_xml": false,
    "twitter_include_replies": false,
    "twitter_embeds": false,
    "twitter_html_description": false,
    "twitter_prefix_with_username": false,
    "twitter_remove_url_from_title": false,
    "youtube_video_iframe": false,
    "youtube_description": false,
    "facebook_original_source": false,
    "instagram_videos": false,
    "char_limit_in_description": null,
    "timezone_offset": null,
    "active_display_author": false,
    "display_author_type": "hostname"
  }
}

Bundles / settings

Update Bundle Settings

Update output settings for an existing bundle. Omitted fields stay unchanged.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

overridesobject

Partial section switches. False resumes workspace inheritance without erasing saved local values. Do not disable a section and write its fields in the same request.

post_limitboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

image_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

title_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

description_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

date_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

guid_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

twitterboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

youtubeboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

facebookboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

author_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

instagramboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

overridesobject

Which saved local sections are active.

post_limitboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

image_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

title_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

description_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

date_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

guid_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

twitterboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

youtubeboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

facebookboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

author_tagboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

instagramboolean

True uses saved local values for this section; false follows workspace defaults. The post_limit section controls bundle_post_limit on bundles.

effectiveobject

Resolved output settings after workspace inheritance. Read-only; this does not confirm publication is complete.

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Changing settings

Send only the fields you want to change. Other fields keep their current values.

{ "bundle_post_limit": 50 }

This sets the output to at most 50 posts, within your plan limit. It does not change API list pagination.

Local values or workspace defaults?

Each section has an overrides switch:

true — use the saved local values.
false — use the workspace defaults.

post_limit: Post count — controls bundle_post_limit.
image_tag: Image tags and fallback image.
title_tag: Title length.

Editing a field turns on its whole local section. When a section was inherited, its other fields start with the current workspace defaults.

To use the workspace image settings again, send:

{ "overrides": { "image_tag": false } }

Do not send image fields in that same request. Setting the switch to true alone restores the currently saved local section, not an older dashboard version.

Value limits

Post counts must be positive integers within your plan limit.
Title length: char_limit_in_title accepts 0–1000 characters.
Fallback image: placeholder_for_image accepts an HTTP(S) URL up to 2048 characters.

false disables a flag. null clears the title limit or fallback URL only when that feature is disabled; it does not turn on inheritance.

Response: 200 OK

PATCH/v1/bundles/:bundle_id/settings

curl --location --request PATCH 'https://api.rss.app/v1/bundles/:bundle_id/settings' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "bundle_post_limit": 50,
  "image_in_media": true
}'

Response · 200 OK

{
  "bundle_post_limit": 50,
  "image_in_media": true,
  "image_in_enclosure": true,
  "enable_placeholder_for_image": false,
  "placeholder_for_image": null,
  "is_limit_in_title": false,
  "char_limit_in_title": null,
  "cache_bust_placeholder_image": false,
  "remove_all_html_from_description": false,
  "keep_line_breaks_in_description": false,
  "image_in_description": false,
  "remove_all_images_in_description": false,
  "include_iframes_when_possible": false,
  "is_limit_in_description": false,
  "read_more_in_description": false,
  "only_ascii": false,
  "ellipsis_in_description": false,
  "allow_future_dates": false,
  "estimated_article_dates": false,
  "force_estimated_article_dates": false,
  "permalink_for_xml": false,
  "twitter_include_replies": false,
  "twitter_embeds": false,
  "twitter_html_description": false,
  "twitter_prefix_with_username": false,
  "twitter_remove_url_from_title": false,
  "youtube_video_iframe": false,
  "youtube_description": false,
  "facebook_original_source": false,
  "instagram_videos": false,
  "char_limit_in_description": null,
  "timezone_offset": null,
  "active_display_author": false,
  "display_author_type": "hostname",
  "overrides": {
    "post_limit": true,
    "image_tag": true,
    "title_tag": false,
    "description_tag": false,
    "date_tag": false,
    "guid_tag": false,
    "twitter": false,
    "youtube": false,
    "facebook": false,
    "author_tag": false,
    "instagram": false
  },
  "effective": {
    "bundle_post_limit": 50,
    "image_in_media": true,
    "image_in_enclosure": true,
    "enable_placeholder_for_image": false,
    "placeholder_for_image": null,
    "is_limit_in_title": false,
    "char_limit_in_title": null,
    "cache_bust_placeholder_image": false,
    "remove_all_html_from_description": false,
    "keep_line_breaks_in_description": false,
    "image_in_description": false,
    "remove_all_images_in_description": false,
    "include_iframes_when_possible": false,
    "is_limit_in_description": false,
    "read_more_in_description": false,
    "only_ascii": false,
    "ellipsis_in_description": false,
    "allow_future_dates": false,
    "estimated_article_dates": false,
    "force_estimated_article_dates": false,
    "permalink_for_xml": false,
    "twitter_include_replies": false,
    "twitter_embeds": false,
    "twitter_html_description": false,
    "twitter_prefix_with_username": false,
    "twitter_remove_url_from_title": false,
    "youtube_video_iframe": false,
    "youtube_description": false,
    "facebook_original_source": false,
    "instagram_videos": false,
    "char_limit_in_description": null,
    "timezone_offset": null,
    "active_display_author": false,
    "display_author_type": "hostname"
  }
}

Bundles / filter

Get Bundle Filter

Retrieve the filter for an existing bundle.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

is_bundle_inherit_feed_filter_rulesboolean

Run supported member-feed rules before bundle rules. Requires the workspace feature and is separate from feed-wide output inheritance.

effectiveobject

Filter after workspace lists and flags are combined. Read-only.

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

is_bundle_inherit_feed_filter_rulesboolean

Run supported member-feed rules before bundle rules. Requires the workspace feature and is separate from feed-wide output inheritance.

limitsobject

Read-only keyword counts and plan limits.

max_keywords_per_listinteger

Plan limit for each combined keyword list.

local_whitelist_countinteger

Number of saved whitelist keywords.

local_blacklist_countinteger

Number of saved blacklist keywords.

inherited_whitelist_countinteger

Workspace whitelist keywords included in the effective filter.

inherited_blacklist_countinteger

Workspace blacklist keywords included in the effective filter.

exceeds_current_limitboolean

Whether the current combined list exceeds the plan limit. Existing keywords remain active; new growth is refused.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the response

Top-level fields show the saved local filter. effective shows the filter after workspace defaults are applied. limits reports local and inherited keyword counts.

Combining local and global filters

When a local filter has default_filter: true:

Global and local keyword lists are combined. Their enabled matching fields apply to every word in the combined list. The whitelist is checked as one combined list.
An enabled global flag stays enabled even if its local value is false.
The more aggressive enabled similar-title setting takes priority.

For example, global blacklist ["ads"] plus local blacklist ["sponsored"] blocks both keywords. Clearing the local list still leaves “ads” blocked.

To use only the local filter, its default_filter must be false.

Filtering order

no_images hides posts without an original image, even when a fallback image is configured.
Blacklist checks run before text replacements and title truncation.

effective describes this bundle’s filter. It does not combine the independent filters of all member feeds. The separate is_bundle_inherit_feed_filter_rules switch applies supported member-feed rules, including hide-post rules, when available for your workspace. It does not copy the complete feed filter.

Keyword limits

Your plan limits each keyword list. Inherited keywords count toward the local total.

Targeting and other filter options

Where keywords are matched

Use whitelist_by_title, whitelist_by_description, whitelist_by_link or whitelist_by_image_url. Blacklist options use the same endings with blackList.

whitelist_contains_word and blacklist_contains_word enable partial matching.

For categories, use whitelist_by_keywords or blacklist_by_keywords.

Missing content and duplicates

no_images, no_date and no_description hide posts missing that content. hide_non_secure_links hides insecure links.

Use duplicate_titles, duplicate_descriptions or duplicate_similar_titles to remove duplicates. The similar-title threshold accepts balanced, strict or aggressive.

Title cleanup and date window

Use title_auto_cleaner and title_replace_keywords for title cleanup.

For a date window, set enable_date_filter, date_period (DAY or HOUR) and seconds_until. The enabled window must equal 1–100000 whole days or hours.

Response: 200 OK

GET/v1/bundles/:bundle_id/filter

curl --location --request GET 'https://api.rss.app/v1/bundles/:bundle_id/filter' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "whitelist": [],
  "blacklist": [
    "sponsored"
  ],
  "whitelist_by_title": false,
  "whitelist_by_description": false,
  "whitelist_by_link": false,
  "whitelist_by_image_url": false,
  "whitelist_contains_word": false,
  "blacklist_by_title": true,
  "blacklist_by_description": false,
  "blacklist_by_link": false,
  "blacklist_by_image_url": false,
  "blacklist_contains_word": false,
  "no_images": true,
  "no_date": false,
  "no_description": false,
  "hide_non_secure_links": false,
  "duplicate_titles": false,
  "duplicate_descriptions": false,
  "duplicate_similar_titles": false,
  "duplicate_similar_titles_threshold": "balanced",
  "default_filter": true,
  "whitelist_by_keywords": false,
  "blacklist_by_keywords": false,
  "enable_date_filter": false,
  "seconds_until": 604800,
  "date_period": "DAY",
  "title_auto_cleaner": false,
  "title_replace_keywords": [],
  "is_bundle_inherit_feed_filter_rules": false,
  "effective": {
    "whitelist": [],
    "blacklist": [
      "sponsored"
    ],
    "whitelist_by_title": false,
    "whitelist_by_description": false,
    "whitelist_by_link": false,
    "whitelist_by_image_url": false,
    "whitelist_contains_word": false,
    "blacklist_by_title": true,
    "blacklist_by_description": false,
    "blacklist_by_link": false,
    "blacklist_by_image_url": false,
    "blacklist_contains_word": false,
    "no_images": true,
    "no_date": false,
    "no_description": false,
    "hide_non_secure_links": false,
    "duplicate_titles": false,
    "duplicate_descriptions": false,
    "duplicate_similar_titles": false,
    "duplicate_similar_titles_threshold": "balanced",
    "default_filter": true,
    "whitelist_by_keywords": false,
    "blacklist_by_keywords": false,
    "enable_date_filter": false,
    "seconds_until": 604800,
    "date_period": "DAY",
    "title_auto_cleaner": false,
    "title_replace_keywords": [],
    "is_bundle_inherit_feed_filter_rules": false
  },
  "limits": {
    "max_keywords_per_list": 50,
    "local_whitelist_count": 0,
    "local_blacklist_count": 1,
    "inherited_whitelist_count": 0,
    "inherited_blacklist_count": 0,
    "exceeds_current_limit": false
  }
}

Bundles / filter

Update Bundle Filter

Update the filter for an existing bundle. Omitted fields stay unchanged.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

is_bundle_inherit_feed_filter_rulesboolean

Run supported member-feed rules before bundle rules. Requires the workspace feature and is separate from feed-wide output inheritance.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

is_bundle_inherit_feed_filter_rulesboolean

Run supported member-feed rules before bundle rules. Requires the workspace feature and is separate from feed-wide output inheritance.

effectiveobject

Filter after workspace lists and flags are combined. Read-only.

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

default_filterboolean

Combine workspace and local filters when true. Lists combine and enabled global flags cannot be cancelled by local false.

whitelist_by_keywordsboolean

Match the whitelist against post categories. Local resources only.

blacklist_by_keywordsboolean

Match the blacklist against post categories. Local resources only.

enable_date_filterboolean

Enable the local date window. Set seconds_until and date_period to a valid whole number of units.

seconds_untilinteger

Window length in seconds, from 1 to 8640000000. When enabled, it must equal 1–100000 whole units of date_period.

date_periodenum

Window unit: DAY (86400 seconds) or HOUR (3600 seconds).

title_auto_cleanerboolean

Enable automatic title cleanup on this resource.

title_replace_keywordsarray of strings

Keywords used for local title cleanup. A supplied array replaces the saved list.

is_bundle_inherit_feed_filter_rulesboolean

Run supported member-feed rules before bundle rules. Requires the workspace feature and is separate from feed-wide output inheritance.

limitsobject

Read-only keyword counts and plan limits.

max_keywords_per_listinteger

Plan limit for each combined keyword list.

local_whitelist_countinteger

Number of saved whitelist keywords.

local_blacklist_countinteger

Number of saved blacklist keywords.

inherited_whitelist_countinteger

Workspace whitelist keywords included in the effective filter.

inherited_blacklist_countinteger

Workspace blacklist keywords included in the effective filter.

exceeds_current_limitboolean

Whether the current combined list exceeds the plan limit. Existing keywords remain active; new growth is refused.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Changing a keyword list

A supplied list replaces the saved list. Send [] to clear it. Spaces around keywords are removed.

{
  "blacklist": ["sponsored"],
  "blacklist_by_title": true
}

This hides posts whose title matches “sponsored”. Other filter fields stay unchanged.

Combining local and global filters

When a local filter has default_filter: true:

Global and local keyword lists are combined. Their enabled matching fields apply to every word in the combined list. The whitelist is checked as one combined list.
An enabled global flag stays enabled even if its local value is false.
The more aggressive enabled similar-title setting takes priority.

For example, global blacklist ["ads"] plus local blacklist ["sponsored"] blocks both keywords. Clearing the local list still leaves “ads” blocked.

To use only the local filter, send default_filter:

{ "default_filter": false }

Filtering order

no_images hides posts without an original image, even when a fallback image is configured.
Blacklist checks run before text replacements and title truncation.

Keyword limits

Your plan limits each keyword list. Inherited keywords count toward the local total.

Targeting and other filter options

Where keywords are matched

Use whitelist_by_title, whitelist_by_description, whitelist_by_link or whitelist_by_image_url. Blacklist options use the same endings with blackList.

whitelist_contains_word and blacklist_contains_word enable partial matching.

For categories, use whitelist_by_keywords or blacklist_by_keywords.

Missing content and duplicates

no_images, no_date and no_description hide posts missing that content. hide_non_secure_links hides insecure links.

Use duplicate_titles, duplicate_descriptions or duplicate_similar_titles to remove duplicates. The similar-title threshold accepts balanced, strict or aggressive.

Title cleanup and date window

Use title_auto_cleaner and title_replace_keywords for title cleanup.

For a date window, set enable_date_filter, date_period (DAY or HOUR) and seconds_until. The enabled window must equal 1–100000 whole days or hours.

Response: 200 OK

PATCH/v1/bundles/:bundle_id/filter

curl --location --request PATCH 'https://api.rss.app/v1/bundles/:bundle_id/filter' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "blacklist": [
    "sponsored"
  ],
  "blacklist_by_title": true,
  "no_images": true
}'

Response · 200 OK

{
  "whitelist": [],
  "blacklist": [
    "sponsored"
  ],
  "whitelist_by_title": false,
  "whitelist_by_description": false,
  "whitelist_by_link": false,
  "whitelist_by_image_url": false,
  "whitelist_contains_word": false,
  "blacklist_by_title": true,
  "blacklist_by_description": false,
  "blacklist_by_link": false,
  "blacklist_by_image_url": false,
  "blacklist_contains_word": false,
  "no_images": true,
  "no_date": false,
  "no_description": false,
  "hide_non_secure_links": false,
  "duplicate_titles": false,
  "duplicate_descriptions": false,
  "duplicate_similar_titles": false,
  "duplicate_similar_titles_threshold": "balanced",
  "default_filter": true,
  "whitelist_by_keywords": false,
  "blacklist_by_keywords": false,
  "enable_date_filter": false,
  "seconds_until": 604800,
  "date_period": "DAY",
  "title_auto_cleaner": false,
  "title_replace_keywords": [],
  "is_bundle_inherit_feed_filter_rules": false,
  "effective": {
    "whitelist": [],
    "blacklist": [
      "sponsored"
    ],
    "whitelist_by_title": false,
    "whitelist_by_description": false,
    "whitelist_by_link": false,
    "whitelist_by_image_url": false,
    "whitelist_contains_word": false,
    "blacklist_by_title": true,
    "blacklist_by_description": false,
    "blacklist_by_link": false,
    "blacklist_by_image_url": false,
    "blacklist_contains_word": false,
    "no_images": true,
    "no_date": false,
    "no_description": false,
    "hide_non_secure_links": false,
    "duplicate_titles": false,
    "duplicate_descriptions": false,
    "duplicate_similar_titles": false,
    "duplicate_similar_titles_threshold": "balanced",
    "default_filter": true,
    "whitelist_by_keywords": false,
    "blacklist_by_keywords": false,
    "enable_date_filter": false,
    "seconds_until": 604800,
    "date_period": "DAY",
    "title_auto_cleaner": false,
    "title_replace_keywords": [],
    "is_bundle_inherit_feed_filter_rules": false
  },
  "limits": {
    "max_keywords_per_list": 50,
    "local_whitelist_count": 0,
    "local_blacklist_count": 1,
    "inherited_whitelist_count": 0,
    "inherited_blacklist_count": 0,
    "exceeds_current_limit": false
  }
}

Bundles / Filter rules

List Bundle Filter Rules

Retrieve advanced filter rules for an existing bundle.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A list of rules in execution order.

Response attributes

dataarray of objects

Rules in creation and execution order. This list is not paginated; at most 21 rules are allowed.

idstring

Rule identifier used for update and delete requests.

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the list

The data array contains the rules in execution order. Use each rule’s id to update or delete it. Rules run in creation order. Each filter allows up to 21 rules and only one text_case rule.

Available rule types

Text: replace, remove, add_prefix, add_suffix, text_case
Links: replace_url, remove_url, remove_all_urls, replace_url_by_condition
Images: replace_image_by_condition
Visibility: hide_post

Targets, replacements and regular expressions

Choose a target

Text rules use search_title or search_description. hide_post also supports search_url, search_image and search_author. URL removal rules require a text target.

Type-specific values

Prefix, suffix and replace_url use take as the added text or full HTTP(S) URL.
Conditional URL/image replacements accept an empty take to replace the whole value.
text_case_mode: uppercase_all, capitalize_first, capitalize_every_word or lowercase_all.
take and put accept at most 255 characters.

Regular expressions

Response: 200 OK

GET/v1/bundles/:bundle_id/filter/rules

curl --location --request GET 'https://api.rss.app/v1/bundles/:bundle_id/filter/rules' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "data": [
    {
      "id": "RULE_ID",
      "type": "replace",
      "take": "Old brand",
      "put": "New brand",
      "search_title": true,
      "search_description": false,
      "search_url": false,
      "search_image": false,
      "search_author": false,
      "add_reg_exp": false,
      "text_case_mode": "uppercase_all"
    }
  ]
}

Bundles / Filter rules

Create Bundle Filter Rule

Create advanced filter rules for an existing bundle.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

`type`enumrequired

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

More parameters

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

More parameters

Idempotency-Keystring

A stable 1–128 character key for retrying creation. Reuse the same key and body to get the same live rule. Deleting the rule releases the key.

Returns

201 Created · A JSON object with the following attributes.

Response attributes

idstring

Rule identifier used for update and delete requests.

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Rule order and limits

Rules run in creation order. Each filter allows up to 21 rules and only one text_case rule.

Example: replace text in a title

{
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true
}

take is the text to find; put is its replacement. Each accepts up to 255 characters.

Available rule types

Text: replace, remove, add_prefix, add_suffix, text_case
Links: replace_url, remove_url, remove_all_urls, replace_url_by_condition
Images: replace_image_by_condition
Visibility: hide_post

Retrying creation safely

Send an Idempotency-Key header when creating a rule. Repeating the same key and body returns the existing rule. A conflicting body returns 409.

Keys contain 1–128 letters, digits, dots, underscores, colons or dashes. Protection lasts while the rule exists.

Targets, replacements and regular expressions

Choose a target

Text rules use search_title or search_description. hide_post also supports search_url, search_image and search_author. URL removal rules require a text target.

Type-specific values

Prefix, suffix and replace_url use take as the added text or full HTTP(S) URL.
Conditional URL/image replacements accept an empty take to replace the whole value.
text_case_mode: uppercase_all, capitalize_first, capitalize_every_word or lowercase_all.
take and put accept at most 255 characters.

Regular expressions

Response: 201 Created

POST/v1/bundles/:bundle_id/filter/rules

curl --location --request POST 'https://api.rss.app/v1/bundles/:bundle_id/filter/rules' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true
}'

Response · 201 Created

{
  "id": "RULE_ID",
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true,
  "search_description": false,
  "search_url": false,
  "search_image": false,
  "search_author": false,
  "add_reg_exp": false,
  "text_case_mode": "uppercase_all"
}

Bundles / Filter rules

Update Bundle Filter Rule

Update advanced filter rules for an existing bundle. Omitted fields stay unchanged.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

`rule_id`stringrequired

Identifier returned when creating or listing filter rules.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

idstring

Rule identifier used for update and delete requests.

typeenum

replace, remove, remove_url, replace_url, replace_url_by_condition, replace_image_by_condition, add_prefix, add_suffix, hide_post, text_case or remove_all_urls.

takestring | null

Match text, prefix/suffix text or replacement URL, depending on type. Up to 255 characters after sanitization. Regex input is limited to 200 characters.

putstring | null

Replacement text, up to 255 characters after sanitization. Required for replace and conditional URL/image replacements; an empty string is allowed.

search_titleboolean

Apply the rule to the post title, when supported by its type.

search_descriptionboolean

Apply the rule to the post description, when supported by its type.

search_urlboolean

Match the post URL. Supported only by hide_post.

search_imageboolean

Match the image URL. Supported only by hide_post.

search_authorboolean

Match the author. Supported only by hide_post.

add_reg_expboolean

Interpret take as a regular expression for supported rule types. Backreferences and lookaround are not supported.

text_case_modeenum

uppercase_all, capitalize_first, capitalize_every_word or lowercase_all. Used by text_case.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Rule order and limits

Rules run in creation order. Each filter allows up to 21 rules and only one text_case rule.

Send only the fields to change. Updating a rule keeps its position in the execution order.

Example: replace text in a title

{
  "type": "replace",
  "take": "Old brand",
  "put": "New brand",
  "search_title": true
}

take is the text to find; put is its replacement. Each accepts up to 255 characters.

Available rule types

Text: replace, remove, add_prefix, add_suffix, text_case
Links: replace_url, remove_url, remove_all_urls, replace_url_by_condition
Images: replace_image_by_condition
Visibility: hide_post

Targets, replacements and regular expressions

Choose a target

Text rules use search_title or search_description. hide_post also supports search_url, search_image and search_author. URL removal rules require a text target.

Type-specific values

Prefix, suffix and replace_url use take as the added text or full HTTP(S) URL.
Conditional URL/image replacements accept an empty take to replace the whole value.
text_case_mode: uppercase_all, capitalize_first, capitalize_every_word or lowercase_all.
take and put accept at most 255 characters.

Regular expressions

Response: 200 OK

PATCH/v1/bundles/:bundle_id/filter/rules/:rule_id

curl --location --request PATCH 'https://api.rss.app/v1/bundles/:bundle_id/filter/rules/:rule_id' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "put": "Updated brand"
}'

Response · 200 OK

{
  "id": "RULE_ID",
  "type": "replace",
  "take": "Old brand",
  "put": "Updated brand",
  "search_title": true,
  "search_description": false,
  "search_url": false,
  "search_image": false,
  "search_author": false,
  "add_reg_exp": false,
  "text_case_mode": "uppercase_all"
}

Bundles / Filter rules

Delete Bundle Filter Rule

Delete advanced filter rules for an existing bundle.

Path parameters

`bundle_id`stringrequired

Bundle identifier. Replace the placeholder in the request URL. Include the leading underscore.

`rule_id`stringrequired

Identifier returned when creating or listing filter rules.

No request body.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

idstring

Deleted rule identifier.

deletedboolean

True when the rule was deleted.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

After deletion

The rule stops applying. A repeated delete returns 404 RULE_NOT_FOUND. Deleting a rule also releases its creation idempotency key.

Response: 200 OK

DELETE/v1/bundles/:bundle_id/filter/rules/:rule_id

curl --location --request DELETE 'https://api.rss.app/v1/bundles/:bundle_id/filter/rules/:rule_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

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

Delete Bundle

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

Parameters

No parameters

Returns

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

DELETE/v1/bundles/:bundle_id

curl --location --request DELETE 'https://api.rss.app/v1/bundles/:bundle_id' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

RESPONSE

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

Workspace

Manage the global settings and filters of the workspace associated with your API key. Settings provide section defaults. Filters combine with local values when the resource includes workspace filters. Use the same Bearer key and secret as your feed requests.

Choose what you want to change

Start with your task. Workspace means the workspace belonging to your API key. Every example uses the same Bearer key and secret as your other API requests.

Get your key from Account → API. Use a plan with API access. Replace sample resource IDs with your own; bundle IDs include a leading underscore.

Change defaults for my workspace

Before you start

Read GET /v1/settings first and keep the current post_limit so you can undo your change. Your plan must allow the new count.

PATCH /v1/settings

Request

curl --location --request PATCH 'https://api.rss.app/v1/settings' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "post_limit": 25
}'

What changes

Feeds using the workspace post-count section now resolve to at most 25 posts. Feeds with custom counts keep them. For bundle defaults, use bundle_post_limit instead.

Undo

Send the previous post_limit to the same endpoint.

Open operation reference →

Give one feed or bundle custom output settings

Before you start

Replace the sample feed ID with your own. Read its settings first. For a bundle, use /v1/bundles/_Ab12Cd34Ef56Gh78/settings and bundle_post_limit.

PATCH /v1/feeds/Ab12Cd34Ef56Gh78/settings

Request

curl --location --request PATCH 'https://api.rss.app/v1/feeds/Ab12Cd34Ef56Gh78/settings' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "post_limit": 10
}'

What changes

The feed uses at most 10 posts, within your plan limit. overrides.post_limit becomes true and effective.post_limit is 10. Other sections keep their existing mode.

Undo

Send { "overrides": { "post_limit": false } } to use the current workspace count again. The saved local count remains available.

Open operation reference →

Add workspace filters to my local filters

Before you start

Requires filters on your plan and an editable feed. This example assumes an empty local blacklist and a workspace blacklist containing ads. Read existing filters first: a supplied list replaces the saved local list.

PATCH /v1/feeds/Ab12Cd34Ef56Gh78/filter

Request

curl --location --request PATCH 'https://api.rss.app/v1/feeds/Ab12Cd34Ef56Gh78/filter' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "default_filter": true,
  "blacklist": [
    "sponsored"
  ],
  "blacklist_by_title": true
}'

What changes

effective.blacklist contains ads and sponsored. The combined matching flags apply to both words. Global no_images stays on even if the local value is false.

Undo

Restore your previous local blacklist and default_filter value. An empty local blacklist removes sponsored from this example but leaves workspace ads active.

Open operation reference →

Use only this feed’s own filters

Before you start

Requires filters on your plan and an editable feed. Read both local and workspace filters first. Disabling default_filter disconnects all workspace filter conditions, not just no_images.

PATCH /v1/feeds/Ab12Cd34Ef56Gh78/filter

Request

curl --location --request PATCH 'https://api.rss.app/v1/feeds/Ab12Cd34Ef56Gh78/filter' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "default_filter": false,
  "no_images": false
}'

What changes

The feed can accept posts without an original image, subject to its other local conditions. Its saved local keywords remain active. A fallback image does not affect the original-image check.

Undo

Restore the previous local no_images value and default_filter value. Re-enabling default_filter uses the latest workspace filter and must fit the resulting keyword limit.

Open operation reference →

Make all bundles use this feed’s filtered output

Before you start

Configure the feed’s filters first. Your plan must support filters and inheritance. This affects every containing bundle, including bundles you add this feed to later.

PATCH /v1/feeds/Ab12Cd34Ef56Gh78/filter/inheritance

Request

curl --location --request PATCH 'https://api.rss.app/v1/feeds/Ab12Cd34Ef56Gh78/filter/inheritance' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inherit_in_bundles": true
}'

What changes

After preparation and propagation, bundles use this feed’s processed source. Each bundle still applies its own filters and output settings. You do not need the separate member-rule switch for this task.

Undo

Send { "inherit_in_bundles": false } to stop using the processed source. The current API also checks inheritance entitlement when disabling. Local filter and rule edits return 409 FILTER_LOCKED while enabled.

Open operation reference →

Apply member-feed rules in just one bundle (advanced)

Before you start

Requires filters on your plan and this workspace feature. This is a separate rule-processing stage, not the complete feed filter. It can also process hide-post rules.

PATCH /v1/bundles/_Ab12Cd34Ef56Gh78/filter

Request

curl --location --request PATCH 'https://api.rss.app/v1/bundles/_Ab12Cd34Ef56Gh78/filter' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "is_bundle_inherit_feed_filter_rules": true
}'

What changes

This bundle applies supported member rules before its own advanced rules. This does not change the feed-wide output switch or make the bundle inherit member output settings.

Undo

Send { "is_bundle_inherit_feed_filter_rules": false }. This stops the extra stage; it cannot undo changes already present in a processed source. Do not assume exactly-once rule execution when combining both switches.

Open operation reference →

Four choices with different effects

Settings control how output looks. Filters control which posts remain and how their content changes. There is no single inheritance switch for both.

Use workspace or custom settings

For one feed or bundle, choose the source of each settings section. A custom section replaces the whole workspace section.

overrides.image_tag

Include workspace filters

Add workspace keywords and enabled conditions to this resource’s local filter. The two filters combine; local false cannot cancel global true.

default_filter

Use a feed’s filtered output in all bundles

A feed-wide choice. Every containing bundle uses that processed source, including future memberships. Bundle filters still apply.

inherit_in_bundles

Apply member rules in one bundle

An advanced bundle-wide choice. Run supported member rules inside this bundle. This does not copy the full feed filter.

is_bundle_inherit_feed_filter_rules

How a bundle gets its result

Choose each member’s normal or processed source, using the feed-wide output switch.
Apply the bundle’s filter, combined with workspace filters when its default_filter is true.
Apply member rules if this bundle enables that extra stage, then its own advanced rules.
Format the bundle output using its own settings, resolved against workspace defaults.

This is a simplified map. A bundle cannot restore a post absent from its processed source by weakening its own blacklist. It does not inherit member feeds’ formatting settings.

What happens when both bundle switches are enabled?

Processed-source selection and member-rule application are independent. The second switch does not undo processing already present in the source.

Exactly-once rule execution across both stages is not guaranteed here. Keep the advanced member-rule switch off for the common task of using a feed’s filtered output. Check actual output before combining them, especially with prefixes and suffixes.

Changing one image field changes the section’s mode

The image section contains media, enclosure and fallback-image settings. Editing any one makes the complete section custom. Other inherited fields start with the current workspace values.

Workspace media is true and enclosure is false. The feed follows the workspace.
Send { "image_in_enclosure": true } to the feed settings endpoint.
The feed now has custom images: media true, enclosure true.
A later workspace media change to false does not change this feed.
Send { "overrides": { "image_tag": false } } to follow current workspace images again.
Setting image_tag to true again uses the saved local section, which dashboard edits may have changed.

Post count and title length have their own section switches. Never send section fields together with its override set to false. Null does not mean inherit. In particular, custom_author: null clears the custom author mode.

Combined keywords also share their matching fields

With default_filter: true, global and local lists become one list. Their matching fields combine too:

Blacklist source	Words	Match in
Workspace	ads	Title
Feed	sponsored	Description
Combined	ads, sponsored	Title and description, for both words

Clearing the local list leaves workspace words active. Global and local whitelists likewise form one list, not two independent requirements. Categories, date windows, title cleanup and advanced rules remain local.

To stop using workspace filter conditions, set default_filter to false. This disconnects all supported global filter fields together. Explicitly keep any protections you still need. Re-enabling uses the latest workspace values.

Saved, effective and published are different

Saved local values: The resource’s own values, including values currently hidden by workspace inheritance.
effective: Resolved configuration for this resource after workspace values are included. It does not flatten every member feed’s pipeline or prove publication is complete.
Published output: The posts readers receive. Cache propagation can lag; there is no application-progress status endpoint in this version.

After 503 OUTPUT_REFRESH_FAILED, configuration is saved but refreshing output failed. Read the saved state before retrying the update. Do not create a duplicate rule: use the same Idempotency-Key for a rule creation retry. Background recovery is not guaranteed after a process interruption.

Send only intended writable fields in PATCH. Do not send a whole GET response: effective and limits are read-only. Arrays replace saved lists; concurrent dashboard and API edits can overwrite one another.

Why does my result look different?

Workspace images changed, but my feed did not

Check overrides.image_tag. A custom image section does not follow later workspace changes.

no_images is still true after I set it false

Check default_filter and workspace no_images. Local false cannot cancel global true. The check uses the original image, even with a fallback configured.

A local keyword matches an unexpected field

Global and local matching flags apply to all combined keywords, not just their original list.

Clearing my blacklist left blocked words

Read effective.blacklist. Workspace words still apply while default_filter is true.

A post visible in a feed is missing from its bundle

Check the selected source, the bundle’s filter and its own rules. Member-rule application is another independent stage.

A locked feed changed after a global edit

The lock prevents local filter edits. It does not freeze inherited workspace values.

My keyword count is over the plan limit

Read limits.exceeds_current_limit. Existing keywords stay active after global growth or a downgrade; shrink lists before growing them again.

GET shows my change but output is old

Saved and effective settings do not confirm completed output propagation. Inspect the actual feed output.

Workspace / settings

Get Global Settings

Retrieve output settings for your workspace.

No request body or query parameters. The API key identifies your workspace.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the response

Additional output settings

{ "is_limit_in_description": true, "char_limit_in_description": 200, "active_display_author": true, "display_author_type": "website_name" }

The response contains your workspace defaults. Feeds and bundles use these values for sections they inherit.

No include query parameter is needed. Effective values describe resolved configuration, not completed publication.

Where these defaults apply

post_limit is the feed default; bundle_post_limit is the bundle default. Local section overrides take priority over these values.

Value limits

Post counts must be positive integers within your plan limit.
Title length: char_limit_in_title accepts 0–1000 characters.
Fallback image: placeholder_for_image accepts an HTTP(S) URL up to 2048 characters.

Response: 200 OK

GET/v1/settings

curl --location --request GET 'https://api.rss.app/v1/settings' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "post_limit": 50,
  "bundle_post_limit": 50,
  "image_in_media": true,
  "image_in_enclosure": true,
  "enable_placeholder_for_image": false,
  "placeholder_for_image": null,
  "is_limit_in_title": false,
  "char_limit_in_title": null,
  "cache_bust_placeholder_image": false,
  "remove_all_html_from_description": false,
  "keep_line_breaks_in_description": false,
  "image_in_description": false,
  "remove_all_images_in_description": false,
  "include_iframes_when_possible": false,
  "is_limit_in_description": false,
  "read_more_in_description": false,
  "only_ascii": false,
  "ellipsis_in_description": false,
  "allow_future_dates": false,
  "estimated_article_dates": false,
  "force_estimated_article_dates": false,
  "permalink_for_xml": false,
  "twitter_include_replies": false,
  "twitter_embeds": false,
  "twitter_html_description": false,
  "twitter_prefix_with_username": false,
  "twitter_remove_url_from_title": false,
  "youtube_video_iframe": false,
  "youtube_description": false,
  "facebook_original_source": false,
  "instagram_videos": false,
  "char_limit_in_description": null,
  "timezone_offset": null,
  "active_display_author": false,
  "display_author_type": "hostname",
  "custom_author": null
}

Workspace / settings

Update Global Settings

Update output settings for your workspace. Omitted fields stay unchanged.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

post_limitinteger

Maximum posts in feed output. Minimum 1; maximum is your plan’s feed limit. This does not change API pagination.

bundle_post_limitinteger

Maximum posts in bundle output. Minimum 1; maximum is your plan’s bundle limit.

image_in_mediaboolean

Include the post image in the RSS media tag.

image_in_enclosureboolean

Include the post image in the RSS enclosure tag.

enable_placeholder_for_imageboolean

Use a fallback image when an original image is missing. Enabling requires a valid placeholder_for_image.

placeholder_for_imagestring | null

is_limit_in_titleboolean

Limit title length. When enabled, char_limit_in_title must be an integer.

char_limit_in_titleinteger | null

Title limit from 0 to 1000 characters. Numeric writes require is_limit_in_title to be true (already enabled or in the same request). Zero is valid. Set null only while title limiting is disabled.

cache_bust_placeholder_imageboolean

Refresh the fallback image URL to avoid stale image caches. Can be enabled only when enable_placeholder_for_image is true.

remove_all_html_from_descriptionboolean

Return plain text descriptions instead of HTML. Enabling disables thumbnails and videos and removes inline images; contradictory explicit values are rejected.

keep_line_breaks_in_descriptionboolean

Preserve description line breaks. Can be enabled only in plain text mode.

image_in_descriptionboolean

Include the thumbnail in the description. Can be enabled only in rich text mode.

remove_all_images_in_descriptionboolean

Remove inline images from the description. Rich text writes require the new-description-output workspace feature. Plain text always removes images.

include_iframes_when_possibleboolean

Include supported embedded videos in the description. Can be enabled only in rich text mode.

is_limit_in_descriptionboolean

Limit description length using char_limit_in_description.

read_more_in_descriptionboolean

Append a Read more link to the description. Requires the workspace read-more feature.

only_asciiboolean

Remove emoji and other non-ASCII characters from descriptions. Requires the workspace only-ASCII feature.

ellipsis_in_descriptionboolean

Append an ellipsis when the description is truncated. Can be enabled only when is_limit_in_description is true.

allow_future_datesboolean

Allow posts whose date is in the future.

estimated_article_datesboolean

Estimate missing article dates. Requires the workspace estimated-date feature.

force_estimated_article_datesboolean

Always use estimated article dates.

permalink_for_xmlboolean

Mark the RSS GUID as a permalink.

twitter_include_repliesboolean

Include replies in X / Twitter output.

twitter_embedsboolean

Include embedded X / Twitter posts. Requires twitter_html_description to be false.

twitter_html_descriptionboolean

Use the full HTML description for X / Twitter posts. Enabling switches twitter_embeds off; explicitly enabling both is rejected.

twitter_prefix_with_usernameboolean

Prefix X / Twitter titles with the username.

twitter_remove_url_from_titleboolean

Remove URLs from X / Twitter titles.

youtube_video_iframeboolean

Include YouTube video embeds.

youtube_descriptionboolean

Include YouTube descriptions.

facebook_original_sourceboolean

Link Facebook posts to their original article source.

instagram_videosboolean

Include Instagram videos.

char_limit_in_descriptioninteger | null

Description limit from 0 to 2000 characters. Numeric writes require is_limit_in_description to be true (already enabled or in the same request). Required when description limiting is enabled.

timezone_offsetinteger | null

Shift output dates by -48 to 48 hours. Null disables the shift.

active_display_authorboolean | null

Use the selected author mode. False selects automatic output; null may appear in older saved settings. Writes require a boolean.

display_author_typeenum

custom_authorstring | null

Custom output author, up to 255 characters after sanitization. Send null to disable custom author mode. The production spelling customAuthor is still accepted on feeds. Send only one spelling.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Changing settings

Send only the fields you want to change. Other fields keep their current values.

{ "post_limit": 50 }

This sets the output to at most 50 posts, within your plan limit. It does not change API list pagination.

Where these defaults apply

post_limit is the feed default; bundle_post_limit is the bundle default. Local section overrides take priority over these values.

Value limits

Post counts must be positive integers within your plan limit.
Title length: char_limit_in_title accepts 0–1000 characters.
Fallback image: placeholder_for_image accepts an HTTP(S) URL up to 2048 characters.

false disables a flag. null clears the title limit or fallback URL only when that feature is disabled; it does not turn on inheritance.

Response: 200 OK

PATCH/v1/settings

curl --location --request PATCH 'https://api.rss.app/v1/settings' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "post_limit": 50,
  "image_in_media": true
}'

Response · 200 OK

{
  "post_limit": 50,
  "bundle_post_limit": 50,
  "image_in_media": true,
  "image_in_enclosure": true,
  "enable_placeholder_for_image": false,
  "placeholder_for_image": null,
  "is_limit_in_title": false,
  "char_limit_in_title": null,
  "cache_bust_placeholder_image": false,
  "remove_all_html_from_description": false,
  "keep_line_breaks_in_description": false,
  "image_in_description": false,
  "remove_all_images_in_description": false,
  "include_iframes_when_possible": false,
  "is_limit_in_description": false,
  "read_more_in_description": false,
  "only_ascii": false,
  "ellipsis_in_description": false,
  "allow_future_dates": false,
  "estimated_article_dates": false,
  "force_estimated_article_dates": false,
  "permalink_for_xml": false,
  "twitter_include_replies": false,
  "twitter_embeds": false,
  "twitter_html_description": false,
  "twitter_prefix_with_username": false,
  "twitter_remove_url_from_title": false,
  "youtube_video_iframe": false,
  "youtube_description": false,
  "facebook_original_source": false,
  "instagram_videos": false,
  "char_limit_in_description": null,
  "timezone_offset": null,
  "active_display_author": false,
  "display_author_type": "hostname",
  "custom_author": null
}

Workspace / filter

Get Global Filter

Retrieve the filter for your workspace.

No request body or query parameters. The API key identifies your workspace.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

Returns

200 OK · A JSON object with the following attributes.

Response attributes

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

limitsobject

Read-only keyword counts and plan limits.

max_keywords_per_listinteger

Plan limit for each combined keyword list.

local_whitelist_countinteger

Number of saved whitelist keywords.

local_blacklist_countinteger

Number of saved blacklist keywords.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Reading the response

The response contains the workspace filter and keyword limits. Local filters can include these values through default_filter.

How local filters inherit this

When a local filter has default_filter: true:

Global and local keyword lists are combined. Their enabled matching fields apply to every word in the combined list. The whitelist is checked as one combined list.
An enabled global flag stays enabled even if its local value is false.
The more aggressive enabled similar-title setting takes priority.

Filtering order

no_images hides posts without an original image, even when a fallback image is configured.
Blacklist checks run before text replacements and title truncation.

Keyword limits

Your plan limits each keyword list. Inherited keywords count toward the local total.

If a global change or plan downgrade puts an existing list over the limit, its keywords remain active. You can shrink it, but cannot grow it further.

Targeting and other filter options

Where keywords are matched

Use whitelist_by_title, whitelist_by_description, whitelist_by_link or whitelist_by_image_url. Blacklist options use the same endings with blackList.

whitelist_contains_word and blacklist_contains_word enable partial matching.

Missing content and duplicates

no_images, no_date and no_description hide posts missing that content. hide_non_secure_links hides insecure links.

Use duplicate_titles, duplicate_descriptions or duplicate_similar_titles to remove duplicates. The similar-title threshold accepts balanced, strict or aggressive.

Title cleanup, date windows and advanced rules are available only on local resources through this API.

Response: 200 OK

GET/v1/filter

curl --location --request GET 'https://api.rss.app/v1/filter' \
    --header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET'

Response · 200 OK

{
  "whitelist": [],
  "blacklist": [
    "sponsored"
  ],
  "whitelist_by_title": false,
  "whitelist_by_description": false,
  "whitelist_by_link": false,
  "whitelist_by_image_url": false,
  "whitelist_contains_word": false,
  "blacklist_by_title": true,
  "blacklist_by_description": false,
  "blacklist_by_link": false,
  "blacklist_by_image_url": false,
  "blacklist_contains_word": false,
  "no_images": true,
  "no_date": false,
  "no_description": false,
  "hide_non_secure_links": false,
  "duplicate_titles": false,
  "duplicate_descriptions": false,
  "duplicate_similar_titles": false,
  "duplicate_similar_titles_threshold": "balanced",
  "limits": {
    "max_keywords_per_list": 50,
    "local_whitelist_count": 0,
    "local_blacklist_count": 1
  }
}

Workspace / filter

Update Global Filter

Update the filter for your workspace. Omitted fields stay unchanged.

Send a JSON object. Omitted fields stay unchanged. Unknown and read-only fields are rejected.

Parameters

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

Headers

`Authorization`stringrequired

Bearer YOUR_API_KEY:YOUR_API_SECRET. Authentication guide.

`Content-Type`stringrequired

application/json

Returns

200 OK · A JSON object with the following attributes.

Response attributes

whitelistarray of strings

Include matching posts. A supplied array replaces the saved list; [] clears it. Keyword counts are limited by your plan.

blacklistarray of strings

Exclude matching posts. A supplied array replaces the saved list; [] clears it. Blacklist matching happens before text replacements.

whitelist_by_titleboolean

Match whitelist keywords against the post title.

whitelist_by_descriptionboolean

Match whitelist keywords against the post description.

whitelist_by_linkboolean

Match whitelist keywords against the post URL.

whitelist_by_image_urlboolean

Match whitelist keywords against the post image URL.

whitelist_contains_wordboolean

Allow partial-word matches for the whitelist.

blacklist_by_titleboolean

Match blacklist keywords against the post title.

blacklist_by_descriptionboolean

Match blacklist keywords against the post description.

blacklist_by_linkboolean

Match blacklist keywords against the post URL.

blacklist_by_image_urlboolean

Match blacklist keywords against the post image URL.

blacklist_contains_wordboolean

Allow partial-word matches for the blacklist.

no_imagesboolean

Hide posts without an original image. A configured fallback does not make the original image present.

no_dateboolean

Hide posts without a publish date.

no_descriptionboolean

Hide posts without a description.

hide_non_secure_linksboolean

Hide posts with insecure links.

duplicate_titlesboolean

Remove posts with duplicate titles.

duplicate_descriptionsboolean

Remove posts with duplicate descriptions.

duplicate_similar_titlesboolean

Remove posts with similar titles.

duplicate_similar_titles_thresholdenum

Similarity threshold: balanced, strict or aggressive.

limitsobject

Read-only keyword counts and plan limits.

max_keywords_per_listinteger

Plan limit for each combined keyword list.

local_whitelist_countinteger

Number of saved whitelist keywords.

local_blacklist_countinteger

Number of saved blacklist keywords.

Usage

Choose a task and understand settings, combined filters and bundle behavior →

Changing a keyword list

A supplied list replaces the saved list. Send [] to clear it. Spaces around keywords are removed.

{
  "blacklist": ["sponsored"],
  "blacklist_by_title": true
}

This hides posts whose title matches “sponsored”. Other filter fields stay unchanged.

How local filters inherit this

When a local filter has default_filter: true:

Global and local keyword lists are combined. Their enabled matching fields apply to every word in the combined list. The whitelist is checked as one combined list.
An enabled global flag stays enabled even if its local value is false.
The more aggressive enabled similar-title setting takes priority.

Filtering order

no_images hides posts without an original image, even when a fallback image is configured.
Blacklist checks run before text replacements and title truncation.

Keyword limits

Your plan limits each keyword list. Inherited keywords count toward the local total.

If a global change or plan downgrade puts an existing list over the limit, its keywords remain active. You can shrink it, but cannot grow it further.

Targeting and other filter options

Where keywords are matched

Use whitelist_by_title, whitelist_by_description, whitelist_by_link or whitelist_by_image_url. Blacklist options use the same endings with blackList.

whitelist_contains_word and blacklist_contains_word enable partial matching.

Missing content and duplicates

no_images, no_date and no_description hide posts missing that content. hide_non_secure_links hides insecure links.

Use duplicate_titles, duplicate_descriptions or duplicate_similar_titles to remove duplicates. The similar-title threshold accepts balanced, strict or aggressive.

Title cleanup, date windows and advanced rules are available only on local resources through this API.

Response: 200 OK

PATCH/v1/filter

curl --location --request PATCH 'https://api.rss.app/v1/filter' \
--header 'Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "blacklist": [
    "sponsored"
  ],
  "blacklist_by_title": true,
  "no_images": true
}'

Response · 200 OK

{
  "whitelist": [],
  "blacklist": [
    "sponsored"
  ],
  "whitelist_by_title": false,
  "whitelist_by_description": false,
  "whitelist_by_link": false,
  "whitelist_by_image_url": false,
  "whitelist_contains_word": false,
  "blacklist_by_title": true,
  "blacklist_by_description": false,
  "blacklist_by_link": false,
  "blacklist_by_image_url": false,
  "blacklist_contains_word": false,
  "no_images": true,
  "no_date": false,
  "no_description": false,
  "hide_non_secure_links": false,
  "duplicate_titles": false,
  "duplicate_descriptions": false,
  "duplicate_similar_titles": false,
  "duplicate_similar_titles_threshold": "balanced",
  "limits": {
    "max_keywords_per_list": 50,
    "local_whitelist_count": 0,
    "local_blacklist_count": 1
  }
}

Webhooks

The webhook feature enables real-time updates for feeds by sending notifications to a designated URL. Webhooks can be activated from the API settings page , where the target URL for receiving updates is specified. Each webhook request contains details about the feed and any new or modified items.

A test request option is available to confirm that the webhook setup is functioning correctly. Custom filters can be applied to determine which feed updates trigger notifications. The webhook settings page includes a history of all webhook calls for monitoring and troubleshooting purposes. Subscriptions can be configured to receive updates for all feeds, specific bundles, or individual feeds.

Verifying webhook signatures

When signing is enabled for a webhook, every request includes an RSSApp-Signature header so your server can cryptographically verify the request came from rss.app. Enable it from the API settings page — you'll see the full secret exactly once. Save it somewhere safe.

The header has the format:

RSSApp-Signature: t=1716220800,v1=a3f9b2c8e7d6...

where t is the Unix timestamp (seconds) at which we sent the request and v1 is the hex-encoded HMAC-SHA256 signature of the string ${t}.${raw_body} using your signing secret as the HMAC key.

Two things to get right:

1. Reject requests where the timestamp is more than 300 secondsaway from your server's clock. This prevents replay attacks where an attacker captures a valid request and re-sends it later.

2. Always use a timing-safe comparison when checking the signature (crypto.timingSafeEqual in Node, hmac.compare_digest in Python, hash_equals in PHP). A simple === leaks signature bytes through timing.

Node.js (Express)

import crypto from 'crypto';
import express from 'express';

const app = express();

// Capture the raw body BEFORE any JSON parsing.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.headers['rssapp-signature'];
  if (!header) return res.status(401).send('Missing signature');

  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const timestamp = parseInt(parts.t, 10);
  const signature = parts.v1;

  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) {
    return res.status(401).send('Timestamp out of tolerance');
  }

  const expected = crypto
    .createHmac('sha256', process.env.RSSAPP_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body.toString('utf8')}`)
    .digest('hex');

  const valid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
  if (!valid) return res.status(401).send('Invalid signature');

  const payload = JSON.parse(req.body.toString('utf8'));
  // ... handle payload ...
  res.status(200).send('ok');
});

Python (Flask)

import hmac, hashlib, time, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    header = request.headers.get('RSSApp-Signature')
    if not header:
        abort(401, 'Missing signature')

    parts = dict(p.split('=', 1) for p in header.split(','))
    timestamp = int(parts['t'])
    signature = parts['v1']

    if abs(int(time.time()) - timestamp) > 300:
        abort(401, 'Timestamp out of tolerance')

    secret = os.environ['RSSAPP_WEBHOOK_SECRET'].encode()
    expected = hmac.new(
        secret,
        f'{timestamp}.{request.get_data(as_text=True)}'.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401, 'Invalid signature')

    payload = request.get_json()
    # ... handle payload ...
    return 'ok', 200

PHP

<?php
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_RSSAPP_SIGNATURE'] ?? '';
if (!$header) { http_response_code(401); exit('Missing signature'); }

$parts = [];
foreach (explode(',', $header) as $p) {
    [$k, $v] = explode('=', $p, 2);
    $parts[$k] = $v;
}
$timestamp = (int) $parts['t'];
$signature = $parts['v1'];

if (abs(time() - $timestamp) > 300) {
    http_response_code(401);
    exit('Timestamp out of tolerance');
}

$secret = getenv('RSSAPP_WEBHOOK_SECRET');
$expected = hash_hmac('sha256', "{$timestamp}.{$rawBody}", $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
// ... handle payload ...
http_response_code(200);
echo 'ok';

Webhook Event Object

The webhook event object contains detailed information about the feed update. Below are the fields included in the request object sent to the target URL:

Attributes

idstring

Unique identifier for the webhook event.

typestring

Indicates the event type (feed_update is only used for now).

feedobject

Contains metadata about the feed

idstring

A unique identifier for the feed, which allows you to track which feed triggered the webhook.

titlestring

The title of the RSS feed, typically sourced from the feed`s metadata.

source_urlstring

The URL of the website or source from which the feed originates.

rss_feed_urlstring

The URL of the RSS feed in XML format. You can access this URL to retrieve the full feed data.

descriptionstring

A brief description of the feed`s content, giving context about the type of information being aggregated.

iconstring

A URL pointing to the favicon or icon of the source, often used for display purposes in widgets or applications.

dataobject

Contains feed update details.

items_newarray of objects

Contains information about new items added to the feed since the last webhook event.

urlstring

The URL linking to the full content of the new item.

titlestring

The title of the new item.

description_textstring

A short summary or excerpt of the item’s content.

thumbnailstring

The URL of the thumbnail image associated with the item.

date_publisheddate string

The timestamp of when the item was published.

authorsarray of objects

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

namestring

Name of the author

items_changedarray of objects

Contains information about items that have been modified since the last webhook event.

urlstring

The URL linking to the full content of the updated item.

titlestring

The title of the updated item.

description_textstring

A short summary or excerpt of the item’s content.

thumbnailstring

The URL of the thumbnail image associated with the item.

date_publisheddate string

The timestamp of when the item was published.

authorsarray of objects

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

namestring

Name of the author

WEBHOOK REQUEST OBJECT

{
  "id": "evt_bbMGHz1x5T0UCEos",
  "type": "feed_update",
  "feed": {
    "id": "q5JyPDGJvSe6pDuN",
    "title": "Business News - Latest Headlines on CNN Business | CNN Business",
    "source_url": "https://www.cnn.com/business",
    "rss_feed_url": "https://rss.app/feeds/q5JyPDGJvSe6pDuN.xml",
    "description": "View the latest business news about the world’s top companies, and explore articles on global markets, finance, tech, and the innovations driving us forward.",
        "icon": "https://www.cnn.com/media/sites/cnn/apple-touch-icon.png",
        "is_active": true
  },
  "data": {
    "items_new": [
      {
        "url": "https://www.cnn.com/2024/09/12/economy/retail-cards-interest-rates-study/index.html",
        "title": "Retail credit card interest rates reach record high | CNN Business",
        "description_text": "When you’re making a purchase at a store’s checkout counter, you may be invited to sign up for the retailer’s store card and promised an initial discount on what you’re buying, plus future perks.",
        "thumbnail": "https://media.cnn.com/api/v1/images/stellar/prod/gettyimages-1590519676-copy.jpg?c=16x9&q=w_800,c_fill",
        "date_published": "2024-09-12T17:52:59.000Z",
        "authors": [
          {
            "name": "Jeanne Sahadi"
          }
        ]
      },
      {
        "url": "https://www.cnn.com/2024/09/12/business/kalshi-political-betting-prediction-market/index.html",
        "title": "Federal judge allows prediction market Kalshi to offer betting on upcoming US elections | CNN Business",
        "description_text": "A federal judge cleared the way on Thursday for legal political gambling in the United States, rejecting a federal watchdog’s last-minute effort to delay a prediction market from offering bets on the November elections.",
        "thumbnail": "https://media.cnn.com/api/v1/images/stellar/prod/c-2020-08-30t180612z-1211798736-rc2ioi9xj295-rtrmadp-3-usa-legal.jpg?c=16x9&q=w_800,c_fill",
        "date_published": "2024-09-12T18:11:25.000Z",
        "authors": [
          {
            "name": "Piper HudspethBlackburn"
          }
        ]
      }
    ],
    "items_changed": []
  }
}

API Reference

Authentication

Errors

Attributes

Pagination

Parameters

List Response Format

Feeds

The Feed Object

Attributes

Create Feed By URL

Parameters

urlstringrequired

Returns

Parameters

urlstringrequired

Returns

Create Feed By Keyword

Parameters

keywordstringrequired

regionstringrequired

Returns

Parameters

keywordstringrequired

regionstringrequired

Returns

Retrieve Feed

Parameters

Returns

List All Feeds

Parameters

Returns

Update Feed

Parameters

idstringrequired

More parameters

Get Feed Settings

Path parameters

feed_idstringrequired

Headers

Authorizationstringrequired

Returns

Response attributes

Usage

Reading the response

Additional output settings

Local values or workspace defaults?

Value limits

Update Feed Settings

Path parameters

feed_idstringrequired

Parameters

Headers

Authorizationstringrequired

Content-Typestringrequired

Returns

Response attributes

Usage

Changing settings

Local values or workspace defaults?

Value limits

Get Feed Filter

Path parameters

feed_idstringrequired

Headers

Authorizationstringrequired

Returns

Response attributes

Usage

Reading the response

Combining local and global filters

Filtering order

Keyword limits

Where keywords are matched

Missing content and duplicates

Title cleanup and date window

Update Feed Filter

Path parameters

feed_idstringrequired

Parameters

`url`stringrequired

`url`stringrequired

`keyword`stringrequired

`region`stringrequired

`keyword`stringrequired

`region`stringrequired

`id`stringrequired

`feed_id`stringrequired

`Authorization`stringrequired

`feed_id`stringrequired

`Authorization`stringrequired

`Content-Type`stringrequired

`feed_id`stringrequired

`Authorization`stringrequired

`feed_id`stringrequired

`Authorization`stringrequired

`Content-Type`stringrequired

`feed_id`stringrequired

`Authorization`stringrequired

`feed_id`stringrequired

`type`enumrequired

`Authorization`stringrequired

`Content-Type`stringrequired

`feed_id`stringrequired

`rule_id`stringrequired

`Authorization`stringrequired

`Content-Type`stringrequired

`feed_id`stringrequired

`rule_id`stringrequired

`Authorization`stringrequired