Here is a straightforward look at what is newznab, covering what it does well and where it falls short. Newznab is a Usenet indexing application and API standard that allows software to search, categorize, and retrieve NZB files from Usenet newsgroups in a consistent, machine-readable way.
If you have spent any time trying to automate Usenet downloads, you have almost certainly run into Newznab without knowing it. It sits quietly behind most modern NZB indexing sites, handling everything from header collection to category assignment.
The Newznab API became the de facto standard for Usenet search, meaning any tool that speaks Newznab can talk to dozens of different indexers without custom integrations.
Understanding what Newznab is, how it indexes Usenet content, and how its API works will make every part of your archival data organizer stack easier to configure and maintain.
What Newznab Means In Practice
Newznab operates at two distinct levels: as installable indexer software and as a shared API specification. Both matter, and confusing them leads to setup mistakes.
Newznab As Software Vs Newznab As An API
As software, Newznab is a web application written in PHP and MySQL that you install on a server. It connects to Usenet, collects headers, groups them into posts, and presents a searchable front-end with an API endpoint.
As an API, Newznab is a specification that defines how clients query an indexer. The spec covers endpoints, parameters, response formats, and authentication. Many indexers that do not run the original Newznab software still implement the same API contract, making them compatible with the same tools.
Think of it this way: the software is one implementation, and the API is the language. You can build a completely different indexer and still speak fluent Newznab.
Why Usenet Search Needed A Common Standard
Before a common API existed, every indexer had its own query format. Automation tools had to maintain separate integrations for each site, which was fragile and time-consuming.
The Newznab API resolved that fragmentation by giving every indexer the same vocabulary. A client that knows how to query one Newznab-compatible indexer can query all of them. That consistency is what made large-scale Usenet automation practical for archival data organizers.
NNTP still handles the actual binary transfer between your client and the Usenet provider. Newznab sits above that layer, handling discovery and search rather than download delivery.
How NZB Files Fit Into The Workflow
An NZB file is an XML document that tells your download client exactly which Usenet articles to retrieve and from which newsgroups. It contains message IDs, segment counts, and group names.
Newznab generates and serves NZB files for every indexed release. When your API synchronization hub sends a search query and gets a result back, the download URL in that response points to an NZB file. Your client fetches that file, passes it to SABnzbd or a similar tool, and the download begins.
The NZB is the bridge between the indexer layer and the NNTP delivery layer.
How A Usenet Indexer Works Behind The Scenes
The indexing process is more involved than most users realize. It involves continuous header retrieval, pattern matching, metadata lookup, and database writes happening in the background around the clock.
Header Collection From Usenet Groups
A Newznab server connects to a Usenet provider via NNTP and requests article headers from specific newsgroups, often groups in the alt.binaries hierarchy. It pulls new headers on a scheduled cycle and stores them locally.
Backfilling is a separate process that retrieves older headers beyond the current crawl window. This is how an indexer builds historical coverage that matches a provider’s retention depth. Backfilling groups is resource-intensive and can put significant load on both the indexer server and the upstream Usenet provider.
Retention refers to how far back headers are available. A provider with 5,000 days of retention means Newznab can theoretically backfill that entire window, though doing so requires substantial storage and processing time.
Message Grouping, Releases, And Categories
Raw Usenet headers are fragments. A single large file may be split across hundreds of articles, each with a subject line following a naming pattern. Newznab identifies these related parts and groups them into a single logical release.
Once grouped, each release is assigned to a category based on the newsgroup it came from and pattern matching against the subject line. Categories follow a standardized numbering scheme (for example, 2000 for audio, 5000 for PC content) that is consistent across Newznab-compatible indexers.
This categorization is what allows API synchronization hubs to filter search results by content type rather than having to parse raw subject lines themselves.
Regexes, GUIDs, And Metadata Enrichment
Regexes drive release naming and categorization. Newznab ships with a set of regular expressions that match subject line patterns to known release formats. Administrators can add custom regexes to improve recognition for groups not covered by defaults.
Each release is assigned a globally unique identifier (GUID) that persists in the database and appears in API responses. Clients use GUIDs to track which releases they have already processed.
Metadata enrichment pulls additional data from external sources like TVRage for series information and IMDb for film and video content. This enrichment populates fields like series name, episode details, and rating, which archival data organizers can use to sort and label their collections automatically.
yEnc encoding is the standard format for binary content posted to Usenet. Newznab does not decode yEnc during indexing; it reads the encoded segments and records their message IDs so that a downstream client can retrieve and decode them.
How The Newznab API Powers Search And Automation
The Newznab API is what makes the software useful beyond its own web front-end. It exposes structured search results that any compatible client can consume without a human in the loop.
CAPS, Search Endpoints, And Response Data
The caps endpoint is where every properly configured client starts. It returns an XML document describing what the indexer supports: which categories exist, which search types are available, and what the server name is. Clients use this to configure themselves automatically rather than requiring manual category mapping.
The primary search endpoints are search for general text queries and type-specific endpoints like tvsearch and movie for category-scoped queries. Results come back as RSS-formatted XML with extended Newznab namespace attributes carrying metadata like category ID, GUID, size, and the NZB download URL.
Retention information is often surfaced through the pubDate field in results, letting clients filter out posts that fall outside a provider’s availability window.
API Key Authentication And Client Requests
Every API request to a Newznab indexer requires an apikey parameter. The indexer validates this key against its user database before returning results. Without a valid key, the server returns an authentication error.
As noted in the Newznab documentation, Newznab ships with some default API keys for services like TVRage and IMDb, but administrators are expected to register their own keys through each service and update the settings accordingly.
From the client side, a typical search request looks like:
https://yourindexer.com/api?t=search&apikey=YOURKEY&q=searchterm&cat=5000
The servername field returned by the caps endpoint identifies the indexer, which is how aggregator tools like NZBHydra2 display it in their interface.
Why Sonarr, Radarr, And SABnzbd Depend On Compatibility
Sonarr, Radarr, and SABnzbd treat the Newznab API as their native indexer language. When Radarr looks for a release, it sends a Newznab-formatted query to every configured indexer and collects the responses. It then scores results against quality profiles and sends the best NZB to SABnzbd.
This chain only works if every indexer in the stack speaks the same API dialect. A single incompatible response format can break the automation entirely.
The Newznab API compatibility layer is also what allows tools like NZBHydra2 to act as a proxy, sitting between your archival data organizer apps and multiple indexers and presenting a single unified endpoint.
Core Newznab Components And Requirements
Newznab is a web application built on PHP, PEAR, and MySQL, and it runs on Linux, Windows, and macOS. Getting it running means understanding each component and how they interact.
Apache, PHP, And MySQL Foundations
Apache serves the web front-end and API endpoints. PHP handles application logic, and MySQL stores all indexed data including headers, releases, categories, user accounts, and API keys.
The stack is conventional but resource-hungry at scale. A small personal indexer covering a handful of groups can run on modest hardware. A public-facing indexer crawling hundreds of groups continuously will need significantly more RAM, CPU, and fast disk I/O to keep the database responsive.
PHP and PEAR dependency management must be configured correctly before the indexer will start collecting headers. Missing extensions or misconfigured PHP settings are among the most common setup failures.
Sphinx Integration And MySQL Search Options
Sphinx Search integration is what makes full-text search fast at scale. Sphinx is an open-source search server that indexes the release database and handles search queries far more efficiently than raw MySQL LIKE queries.
Without Sphinx, Newznab falls back to MySQL search, which works for small datasets but degrades quickly as the release count grows. Most production deployments enable Sphinx from the start.
Keeping the Sphinx index synchronized with new releases requires scheduled re-indexing. This adds another background process to manage alongside the binary update and release scripts.
CMS Features, SEO Friendly URLs, And Site Management
Newznab includes a simple CMS layer that lets administrators add static pages to the site. These pages automatically appear in navigation menus without requiring custom routing.
URL rewriting is built in, producing clean paths that are more readable and better suited for search engine indexing. Google Analytics and Google AdSense integration are included in the base software, which reflects the original intent of supporting community-facing public indexer sites.
Site management is handled through an admin panel where you configure newsgroups to crawl, manage user accounts, set API limits, adjust categories, and update external API keys for metadata enrichment services.
Versions, Forks, And Real-World Ecosystem Usage
The Newznab ecosystem is not a single project. It has split into distinct versions and inspired a range of independent implementations that all share the same API standard.
Newznab Classic, Newznab Plus, And GPLv3
Newznab exists in two official versions. Newznab Classic is the open-source version released under the GPLv3 license, making it freely available for anyone to install, modify, and distribute. Newznab Plus is the commercial version, offering additional features and support for paid users.
The GPLv3 licensing of Classic is significant because it ensures the codebase remains open. Anyone who modifies and distributes it must release their changes under the same terms, which has contributed to the growth of community forks.
Newznab-tmux, maintained on GitHub by NNTmux, is one notable fork that rebuilt the application on a Laravel foundation rather than the original PEAR-based stack, reflecting ongoing community development efforts.
Examples Of Indexers And Communities Using The Standard
Several well-known public indexers have been built on Newznab or implement its API. NZBFinder and NZBGeek are frequently mentioned examples in the community. Others include NZB.su, UsenetCrawler, DogNZB, NZBGrabIt, GingaDaddy, and ABNZB.
Ensisoft, a security software company, was historically associated with Newznab Plus development, though the commercial side of the project has seen limited public activity in recent years.
Each of these sites may run a customized version of the software, a fork, or an entirely independent codebase that simply conforms to the API specification. From a client’s perspective, this makes no difference as long as the API responses are well-formed.
Development Status And What That Means Today
As discussed in the Reddit Usenet community, most discussion about Newznab as self-hosted software is over a decade old. Active development on the original codebase has slowed considerably.
This matters for anyone considering a fresh self-hosted installation. Forks like nZEDb and newznab-tmux represent more actively maintained options for home lab operators who want a personal indexer. The original API specification, though, remains as relevant as ever because the entire ecosystem of archival data organizer tools still depends on it.
When To Use Newznab And What To Watch Out For
Choosing to run your own Newznab instance versus relying on an established public indexer is a real decision with meaningful trade-offs on both sides.
Personal Indexing Vs Public Indexing Sites
A personal Newznab instance gives you complete control over which newsgroups you index and how far back you backfill. This is useful for archival data organizers who work with niche groups that public indexers skip.
The trade-off is operational responsibility. You need a Usenet provider account for the indexer itself, a capable server, and time to maintain the stack. Public indexers like those built on Newznab-compatible platforms absorb that complexity in exchange for usage limits, subscription fees, or both.
For most users, starting with a reputable public indexer and a compatible API key is the practical choice before committing to self-hosting.
Backfill Load, Update Scripts, And Maintenance Overhead
The update_binaries script is the core process that collects new headers from Usenet. It runs continuously or on a cron schedule and feeds raw data into the database. The update_releases script then processes those headers into grouped releases with metadata.
Both scripts live in misc/update_scripts and need to be running reliably for the indexer to stay current. If either stops, your index falls behind and search results go stale.
Backfilling groups can be extremely resource-intensive. Pulling years of headers for a busy binary group generates millions of database writes. Starting a new instance with aggressive backfill targets on multiple groups simultaneously can overwhelm modest hardware.
Privacy, SSL, And Provider Considerations
Your Newznab instance connects to a Usenet provider via NNTP to collect headers. That connection should use SSL (port 563) to prevent your ISP from observing the traffic between your server and the provider.
Choose a provider with a no-logs policy and SSL support for both your personal downloads and your indexer’s header collection. If you are running a public-facing indexer, also consider what data you are logging about your users and what your retention and privacy policies are.
A VPN adds an additional layer of separation between your server’s IP and the provider, which is worth considering for privacy-conscious archival data organizer setups.
Frequently Asked Questions
How does a Usenet indexer work and what does it provide?
What is a Newznab server and how do you connect to it?
Where can you find a Newznab API key and what is it used for?
apikey parameter so the server can authenticate your requests and enforce any usage limits tied to your account.What is the correct Newznab URL format to add an indexer to an app?
https://yourindexer.com/api with query parameters appended for each request. When adding an indexer to an app like Radarr, you typically enter just the base URL and API key, and the app constructs full requests using the caps endpoint to discover supported categories and search types automatically.