# RSSHub User Guide

RSSHub turns almost anything on the web into an RSS, Atom, or JSON feed. It is an open-source feed-generation framework with thousands of community-maintained **routes** — each route knows how to scrape one source (a GitHub repo's issues, a YouTube channel, a Weibo user, a Telegram channel, a news site) and emit a clean, standards-compliant feed your reader can subscribe to.

This guide shows you how to **use** RSSHub: how feed URLs are structured, how to pick output formats, and how to reshape any feed on the fly with a rich set of universal query parameters (filtering, full-text extraction, item limits, AI summaries, and more). It also covers getting your own instance running in minutes with Docker.

> [!NOTE]
> RSSHub is a *feed generator*, not a feed reader. You point an RSS reader (Folo, Feedly, Miniflux, NetNewsWire, Inoreach, etc.) at an RSSHub feed URL. RSSHub builds the feed; your reader displays it.

---

## 1. Quick Start

There are two ways to use RSSHub. Pick based on whether you want zero setup or full control.

=== "Use a public instance (no setup)"

    The fastest path. Public instances host every route for you. The reference instance is `https://rsshub.app`. Build a feed URL by appending a route path:

    ```text
    https://rsshub.app/github/issue/DIYgod/RSSHub/open
    ```

    Paste that URL into your RSS reader's "add subscription" box. You now have a feed of open issues in the `DIYgod/RSSHub` repository.

    > [!WARNING]
    > Public instances are shared and best-effort. They may rate-limit, cache aggressively, or lack the credentials some routes need (for example, routes that require a login cookie). For anything you depend on, self-host.

=== "Self-host with Docker (full control)"

    One command gets you a private instance on port `1200`:

    ```bash
    docker run -d --name rsshub -p 1200:1200 diygod/rsshub
    ```

    Verify it is live:

    ```bash
    curl http://localhost:1200/healthz
    ```

    ```text
    Health check successful
    ```

    Now build feed URLs against your own host:

    ```text
    http://localhost:1200/github/issue/DIYgod/RSSHub/open
    ```

    For a production self-host with Redis caching and a headless browser, see the [Admin Guide](/guides/DIYgod/RSSHub/admin-guide/) — it covers `docker-compose`, Cloudflare Workers, Vercel, and Fly.io.

> [!TIP]
> RSSHub pairs especially well with [Folo](https://folo.is/), an RSS reader built by the same community. Folo can discover RSSHub routes for the page you are viewing. The [RSSHub Radar](https://github.com/DIYgod/RSSHub-Radar) browser extension does the same — it inspects the current website and suggests the matching RSSHub feed.

---

## 2. How Feed URLs Work

Every RSSHub feed URL has the same shape:

```text
{instance}/{namespace}/{route-path}
```

| Part | Meaning | Example |
|------|---------|---------|
| `{instance}` | The RSSHub host you are using | `https://rsshub.app` or `http://localhost:1200` |
| `{namespace}` | The source/site, e.g. one folder of routes | `github`, `youtube`, `weibo`, `telegram` |
| `{route-path}` | The specific feed within that source, with its parameters filled in | `/issue/DIYgod/RSSHub/open` |

A **namespace** groups all routes for one website. RSSHub ships **over 1,500 namespaces** covering thousands of individual routes. Within a namespace, each route has a **path template** with named segments. Take the GitHub "Repo Issues" route, whose path template is:

```text
/issue/:user/:repo/:state?/:labels?
```

- Segments written `:name` are **required** parameters — you replace them with a real value.
- Segments written `:name?` are **optional** — you may omit them (a trailing `?` marks optionality).

So the template `/issue/:user/:repo/:state?/:labels?` produces real URLs like:

```text
/github/issue/DIYgod/RSSHub                 → all open issues (state defaults to "open")
/github/issue/DIYgod/RSSHub/closed          → closed issues
/github/issue/DIYgod/RSSHub/all/bug         → all issues labelled "bug"
```

> [!NOTE]
> Each route documents its own path, parameters, and a working **example** URL. The canonical, always-current catalog of every route lives at [docs.rsshub.app](https://docs.rsshub.app). The same data is served by your instance's API (see [Section 8](#8-discovering-routes-programmatically)) — useful when you self-host a pinned version.

### Finding the route you need

You do not memorize routes. Use one of these:

- **The documentation site** — [docs.rsshub.app](https://docs.rsshub.app) is searchable by site name.
- **RSSHub Radar** — the [browser extension](https://github.com/DIYgod/RSSHub-Radar) (and its mobile siblings [RSSBud](https://github.com/Cay-Zhang/RSSBud) for iOS and [RSSAid](https://github.com/LeetaoGoooo/RSSAid) for Android) detects whether the page you are on has a matching route and gives you the URL.
- **Your instance's home page** — open the instance root (`http://localhost:1200/`) in a browser for the built-in landing page.

---

## 3. Choosing an Output Format

By default, RSSHub returns **RSS 2.0**. Switch formats with the `format` query parameter. This is appended like any URL query string (`?key=value`).

| `format` value | Output | Content-Type | When to use |
|----------------|--------|--------------|-------------|
| *(omitted)* or `rss` | RSS 2.0 XML | `application/xml` | Default. Works with every reader. |
| `atom` | Atom 1.0 XML | `application/xml` | Readers that prefer Atom. |
| `json` | JSON Feed 1.1 | `application/feed+json; charset=UTF-8` | Apps and scripts that consume JSON. |
| `rss3` (or legacy `ums`) | RSS3 JSON | `application/json` | RSS3 network integrations. |

Examples:

```text
https://rsshub.app/github/issue/DIYgod/RSSHub?format=atom
https://rsshub.app/github/issue/DIYgod/RSSHub?format=json
```

> [!TIP]
> When you combine `format` with the universal parameters below, separate them with `&`:
> `…/DIYgod/RSSHub?format=json&limit=10`. The first parameter after the path uses `?`; every subsequent one uses `&`.

> [!NOTE]
> RSSHub sets an RSS `<ttl>` (time-to-live, in minutes) on the feed so well-behaved readers know how often to poll. When caching is enabled the `<ttl>` is derived from the route cache expiry; otherwise it is `1` minute.

---

## 4. Universal Feed Parameters — The Power Features

This is what sets RSSHub apart. **Every** route accepts the same set of query parameters that transform the feed *after* it is generated — filter it, trim it, translate it, summarize it, or pull in full article text. They work identically whether the route is for GitHub, YouTube, or a tiny blog.

Mix and match freely. All values are URL query parameters.

### 4.1 Filtering by content

Keep or drop items by matching their **title**, **description**, **author**, and **category** against a regular expression.

| Parameter | Effect |
|-----------|--------|
| `filter` | Keep only items where title **or** description **or** author **or** category matches. |
| `filter_title` | Keep only items whose **title** matches. |
| `filter_description` | Keep only items whose **description** matches. |
| `filter_author` | Keep only items whose **author** matches. |
| `filter_category` | Keep only items with a matching **category**. |
| `filterout` | Drop items where title or description matches. |
| `filterout_title` | Drop items whose **title** matches. |
| `filterout_description` | Drop items whose **description** matches. |
| `filterout_author` | Drop items whose **author** matches. |
| `filterout_category` | Drop items with a matching **category**. |
| `filter_case_sensitive` | Set to `false` for case-insensitive matching (matching is case-sensitive by default). |
| `filter_time` | Keep only items published within the last **N seconds** (based on each item's publish date). |

```text
# Only release notes that mention "security"
https://rsshub.app/github/issue/DIYgod/RSSHub?filter=security

# Everything EXCEPT items whose title contains "sponsored", case-insensitive
https://rsshub.app/github/issue/DIYgod/RSSHub?filterout_title=sponsored&filter_case_sensitive=false

# Only items from the last 24 hours (86400 seconds)
https://rsshub.app/github/issue/DIYgod/RSSHub?filter_time=86400
```

> [!IMPORTANT]
> When you supply `filter`, the field-specific keep filters (`filter_title`, `filter_description`, `filter_author`, `filter_category`) are ignored — `filter` takes precedence. The drop filters (`filterout*`) and `filter_time` still apply.

> [!NOTE]
> The regular-expression engine is configurable by the instance operator. Public/default instances use the **RE2** engine (linear-time, no catastrophic backtracking), which supports standard syntax but not certain advanced PCRE features like backreferences. If a complex pattern behaves unexpectedly on a self-hosted instance, check which engine is configured (see the Admin Guide's `FILTER_REGEX_ENGINE` setting).

### 4.2 Limiting and ordering

| Parameter | Effect |
|-----------|--------|
| `limit` | Return at most **N** items (applied after filtering). |
| `sorted` | Set to `false` to keep the route's original item order. By default items are sorted newest-first by publish date. |

```text
# The 5 most recent items
https://rsshub.app/github/issue/DIYgod/RSSHub?limit=5

# Preserve source ordering
https://rsshub.app/github/issue/DIYgod/RSSHub?sorted=false
```

> [!TIP]
> `limit` is the single most useful parameter for busy feeds. It also reduces load on the source site and on shared instances — use it generously.

### 4.3 Full-text extraction

Many sources only put a summary or the first paragraph in the feed. Add `mode=fulltext` to have RSSHub fetch each item's link and extract the **full article body**.

```text
https://rsshub.app/example/blog?mode=fulltext
```

> [!WARNING]
> Full-text mode fetches every linked page, so feeds build slower and put more load on the origin site. Pair it with `limit` to keep things reasonable, e.g. `?mode=fulltext&limit=10`. Extraction is best-effort: if a page cannot be parsed, RSSHub keeps the original description rather than erroring.

### 4.4 Shortening items

| Parameter | Effect |
|-----------|--------|
| `brief` | Truncate each item's description to **N** characters (strips HTML first, appends an ellipsis). `N` must be **100 or greater**. |

```text
# Trim every item down to a 300-character plain-text teaser
https://rsshub.app/github/issue/DIYgod/RSSHub?brief=300
```

> [!CAUTION]
> A `brief` value below 100 is rejected with an error. Use `brief=100` or higher.

### 4.5 Translation and conversion

| Parameter | Effect |
|-----------|--------|
| `opencc` | Convert Chinese text between scripts using OpenCC. Pass a conversion config such as `t2s` (Traditional → Simplified) or `s2t` (Simplified → Traditional). Applies to titles and descriptions. |
| `chatgpt` | Summarize or translate items using a configured OpenAI-compatible model (see note). |

```text
# Convert a Traditional-Chinese feed to Simplified
https://rsshub.app/example/zh?opencc=t2s
```

> [!NOTE]
> `chatgpt` only does anything if the **instance operator** has configured an OpenAI API key. On instances where it is enabled, it summarizes the description, translates the title, or both — controlled by the operator's settings. Public instances usually leave it off. The AI output is cached per item, so repeated builds are cheap.

### 4.6 Reading-integration helpers

| Parameter | Effect |
|-----------|--------|
| `tgiv` | Rewrite each item link to a **Telegram Instant View** URL. Pass your Instant View template hash as the value (`?tgiv=<rhash>`). |
| `scihub` | Rewrite each item link to its Sci-Hub page (uses the item's DOI when available). Useful for academic-paper feeds. |
| `image_hotlink_template` | Rewrite image URLs in item content through a proxy template — **only** when the operator has enabled user-supplied hotlink templates. |
| `multimedia_hotlink_template` | Same as above for audio/video sources. |

> [!NOTE]
> `image_hotlink_template` and `multimedia_hotlink_template` are ignored unless the operator enabled the feature. They let you route media through an image proxy to defeat referrer-based hotlink protection. See the Admin Guide's anti-hotlink section for the template syntax and the operator-level `HOTLINK_TEMPLATE` equivalent.

### 4.7 Putting parameters together

Parameters compose. A realistic "give me a clean, short, recent, English-only digest" URL:

```text
https://rsshub.app/github/issue/DIYgod/RSSHub/all?limit=15&filterout_title=bot&brief=400&format=json
```

That returns at most 15 items, drops anything whose title contains "bot", trims each description to 400 characters, and serves JSON Feed.

---

## 5. Access-Controlled Instances

Some self-hosted instances are locked down so only people who know a key can pull feeds. If an operator has set an access key, you must authenticate **every** feed request with one of two query parameters:

| Parameter | How it works |
|-----------|--------------|
| `key` | The plaintext access key. Simplest, but the key appears in the URL. |
| `code` | A per-path signature: the MD5 hash of `{request-path}{access-key}`. The key itself never appears in the URL. |

```text
# Plaintext key
http://your-instance:1200/github/issue/DIYgod/RSSHub?key=YOUR_ACCESS_KEY

# Signed code (hash of the path + the key)
http://your-instance:1200/github/issue/DIYgod/RSSHub?code=8f9b1c…
```

> [!IMPORTANT]
> The `code` value is specific to one exact request path. If you change the route path (or add a different route), you must compute a new `code`. The `key` value, by contrast, works for any path. Public instances and default self-hosts have **no** access key, so neither parameter is needed there.

The instance root (`/`), `robots.txt`, `favicon.ico`, and `logo.png` are always reachable without a key.

---

## 6. Everyday Recipes

> [!TIP]
> These combine the building blocks above. Replace the namespace/route with the one you actually need from [docs.rsshub.app](https://docs.rsshub.app); the *parameters* are universal.

### A noise-free GitHub release feed

```text
https://rsshub.app/github/issue/OWNER/REPO/all?filterout_title=dependabot&limit=20
```

### A morning digest of a busy news site

```text
https://rsshub.app/SITE/ROUTE?limit=10&filter_time=43200&brief=500
```

Last 12 hours (`43200` seconds), at most 10 items, 500-character teasers.

### Full articles from a summary-only blog, as JSON

```text
https://rsshub.app/BLOG/ROUTE?mode=fulltext&limit=5&format=json
```

### A keyword watch across one source

```text
https://rsshub.app/SITE/ROUTE?filter=kubernetes|k8s&filter_case_sensitive=false
```

Keep only items mentioning "kubernetes" or "k8s", in any case.

### A Simplified-Chinese version of a Traditional-Chinese feed

```text
https://rsshub.app/SITE/ROUTE?opencc=t2s
```

---

## 7. Troubleshooting

RSSHub returns a human-readable error page (or a JSON error when you request `?format=json`) with an HTTP status code that tells you what went wrong.

### Error: `this route is empty, please check the original site or create an issue`

**Cause** — The route ran successfully but produced zero items. Usually the source has no content matching your parameters, the upstream page changed its structure, or your `filter`/`filterout` removed everything.

**Solution** — Remove your filter parameters and retry. If it is still empty, open the source site in a browser to confirm it actually has content. If the site has content but the feed is empty, the route may need a fix — report it via [a GitHub issue](https://github.com/DIYgod/RSSHub/issues/new/choose).

**Prevention** — Test a route without filters first, then add `filter*` parameters once you confirm items appear.

### Error: `The route does not exist or has been deleted.` (HTTP 404)

**Cause** — The namespace or path does not match any registered route — a typo, a wrong number of path segments, or a route that was removed.

**Solution** — Re-check the path against the route's documented template and example on [docs.rsshub.app](https://docs.rsshub.app). Count the segments: a template like `/issue/:user/:repo/:state?` needs `user` and `repo` at minimum.

**Prevention** — Copy the example URL from the docs and edit the values, rather than typing paths from memory.

### Error: `Authentication failed. Access denied.` (HTTP 403)

**Cause** — The instance has an access key configured and your request did not include a valid `key` or `code` parameter.

**Solution** — Add `?key=YOUR_ACCESS_KEY` (or a correctly computed `?code=`) to the URL. Get the key from whoever operates the instance. See [Section 5](#5-access-controlled-instances).

**Prevention** — Store the key in your reader's saved subscription URL so it is always sent.

### Error: `This path is currently fetching, please come back later!` (HTTP 503)

**Cause** — Another request for the same feed is already in flight on the instance. RSSHub serializes identical requests to avoid hammering the source, and yours timed out waiting.

**Solution** — Wait a moment and refresh. The first request will have populated the cache, so the retry returns instantly.

**Prevention** — Let your reader poll on a normal schedule rather than refreshing repeatedly by hand.

### Error pages with HTTP 503 and an upstream message

**Cause** — The route reached the source site but the source returned an error, timed out, or blocked the request (rate limiting, anti-bot, expired credentials).

**Solution** — Retry later. If it persists on a *public* instance, the instance may be rate-limited by the source; try self-hosting with appropriate credentials. If it persists on your *self-hosted* instance, the route may require configuration (an API token or cookie) — check the route's docs and the Admin Guide's configuration reference.

**Prevention** — For sources that require login, self-host and supply the route's credentials via environment variables.

### Invalid parameter `brief`

**Cause** — You passed `brief` with a value below 100 (or a non-numeric value).

**Solution** — Use `brief=100` or any larger integer.

### A regex filter does nothing or errors on a self-hosted instance

**Cause** — The instance's regex engine (`re2` by default) does not support a feature your pattern uses (e.g. backreferences), or the pattern is invalid.

**Solution** — Simplify the pattern to standard regex syntax. Operators can switch the engine to `regexp` (see Admin Guide), but `re2` is the safe default.

---

## 8. Discovering Routes Programmatically

Every RSSHub instance exposes a small public **JSON API** describing its own routes — handy for building tools, dashboards, or your own route picker. These endpoints live under `/api` and need no authentication beyond the instance's normal access key (if any).

| Endpoint | Returns |
|----------|---------|
| `GET /api/namespace/all` | Every namespace and its routes, with parameters and examples. |
| `GET /api/namespace/:namespace` | One namespace's routes (e.g. `/api/namespace/github`). |
| `GET /api/category/:category` | Routes grouped under a category (e.g. `programming`). |
| `GET /api/radar/rules/all` | All RSSHub Radar detection rules. |
| `GET /api/radar/rules/:domain` | Radar rules for one domain. |
| `GET /api/route/status` | Route health/status data. |
| `GET /api/openapi.json` | The full OpenAPI 3.1 specification for the API. |
| `GET /api/reference` | An interactive, browsable API reference (Scalar UI). |

```bash
# List every route GitHub exposes on a public instance
curl https://rsshub.app/api/namespace/github
```

> [!TIP]
> `GET /api/reference` opens a friendly "try it" UI in the browser — the easiest way to explore the API without reading the spec.

---

## 9. Frequently Asked Questions

**Q: Do I need to install anything to use RSSHub?**
No. Use a public instance like `https://rsshub.app` and just paste route URLs into your reader. Install (via Docker) only if you want privacy, reliability, or routes that need credentials.

**Q: Is RSSHub free?**
Yes. RSSHub is open source under the AGPL-3.0 license. Public instances are run by volunteers; self-hosting is free aside from your own hosting costs.

**Q: A route needs my login cookie. Can I use it on the public instance?**
You should not put your private cookies into a shared public instance. Self-host and supply the cookie via the route's environment variable (see the Admin Guide's configuration reference). That keeps your credentials on your own server.

**Q: Why is my feed sometimes a few minutes stale?**
RSSHub caches route output (5 minutes by default on a typical instance) so it does not re-scrape the source on every request. This is intentional and keeps both RSSHub and the source healthy. The RSS `<ttl>` reflects the cache window.

**Q: How do I get only the latest few items?**
Add `?limit=N`, e.g. `?limit=5`. It applies after any filtering.

**Q: Can I keep only items matching a keyword?**
Yes — `?filter=KEYWORD`. Match a specific field with `filter_title`, `filter_description`, `filter_author`, or `filter_category`. Drop matches instead with the `filterout*` variants.

**Q: The feed only has summaries. Can I get full articles?**
Add `?mode=fulltext`. RSSHub fetches each linked page and extracts the body. Combine with `?limit=` so the build stays fast.

**Q: What output formats can I get?**
RSS (default), Atom (`?format=atom`), JSON Feed (`?format=json`), and RSS3 (`?format=rss3`). See [Section 3](#3-choosing-an-output-format).

**Q: How do I translate a Chinese feed?**
Use `?opencc=t2s` (Traditional → Simplified) or `?opencc=s2t` (Simplified → Traditional).

**Q: My reader says the feed is empty, but the website has new posts. What now?**
The route may have broken because the source site changed. Remove any filters first; if still empty, report it on [GitHub Issues](https://github.com/DIYgod/RSSHub/issues/new/choose).

**Q: Can I require a key so only I can use my instance?**
Yes — that is an operator setting (`ACCESS_KEY`). Once set, every feed URL needs `?key=` or `?code=`. See [Section 5](#5-access-controlled-instances) and the Admin Guide.

**Q: How do I find the route for a specific website?**
Search [docs.rsshub.app](https://docs.rsshub.app), or install the [RSSHub Radar](https://github.com/DIYgod/RSSHub-Radar) browser extension, which detects the route for whatever page you are on.

**Q: How many sites does RSSHub support?**
Over 1,500 namespaces, each with one or more routes — thousands of feeds in total, growing constantly through community contributions.

**Q: Can I read the routes via an API instead of the docs site?**
Yes. Hit `GET /api/namespace/all` (or `/api/reference` for an interactive browser). See [Section 8](#8-discovering-routes-programmatically).

**Q: Does RSSHub work on Cloudflare Workers / Vercel / Fly.io?**
Yes — those are deployment options for operators. As a user you just get a feed URL; how it is hosted is transparent to you. See the Admin Guide for deployment.

---

_Generated June 2026 from DIYgod/RSSHub at 3567ced. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._