# FilterLists: a directory for subscription lists your blocker can actually query > FilterLists is a catalogue of ad, tracker and malware blocking lists plus the web UI and API that make them findable, launched in 2015 after contributors found selection was the hard part. It is a directory, not a blocker: you still need a client that can subscribe. **collinbarrett/FilterLists** — :shield: The independent, comprehensive directory of filter and host lists for advertisements, trackers, malware, and annoyances. - Repository: https://github.com/collinbarrett/FilterLists - Website: https://filterlists.com - Stars: 1,659 · Forks: 143 - Language: C# - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/collinbarrett-filterlists ## A blocker is useless until you know which lists to subscribe to The problem FilterLists addresses is one step downstream of ad blocking itself. Blockers work by comparing the requests a page makes against lists of hosts and filters and blocking the ones that match, and the README points out that this is how malvertising gets stopped and how bandwidth use drops. That mechanism is well understood and widely implemented. The friction is on the supply side. Thousands of contributors maintain these lists, and locating and selecting the right subset of them has historically been awkward. The project was launched in 2015 to solve exactly that selection problem, not the blocking problem. So the shape of the product is: a directory of lists, a website to browse them, and an API to query them. The README's own framing puts installation outside the project, telling you first to install one of the software tools that supports these lists, then to subscribe to a set of them inside that software. Anything that blurs that boundary is a misreading of what this repository is. ## Two services, one React site and one ASP.NET Core API The services table in the README lists exactly two entries, and the split between them is the architecture in miniature. The first is the Website, described as a React and TypeScript UI built with Ant Design, served at filterlists.com. It is the human path: browse, compare, subscribe. The second is the Directory API, an ASP.NET Core API serving the core FilterList information, hosted at api.filterlists.com. It is the machine path, and it is documented rather than reverse engineered, which is what makes it usable from a script. The repository uses the MIT licence, and the repository layout backs up the split: a web/ directory for the front end and a services/ directory for the API, alongside an infra/ directory, a global.json pinning the.NET SDK version, and AGENTS.md and.vscode/ for tooling. The topic list on the repository carries the whole stack in plain sight, including aspnetcore, react, typescript, azure, azure-sql-database, azure-static-web-apps, azure-app-service, entity-framework-core, dotnet-aspire, rest-api, docker and ant-design. That is a.NET API with a relational store, a React front end, Azure deployment targets and container images, not a folder of text files. ## The API ships an OpenAPI spec and a Docker image Two integration paths are documented, and they cover different users. The spec route is the OpenAPI 3.0 document published at the API's own Swagger endpoint: ``` https://api.filterlists.com/swagger/v1/swagger.json ``` The same service exposes an interactive Swagger UI, which the README links from the services table. If you are writing code against FilterLists, that document is the thing to read first: it defines the shape of the FilterList objects the API serves, and any script you write should be generated from or validated against it rather than against a guess. The deployment route is the container. The services table links a Docker image published as a package for the Directory API, under the name filterlists-directory-api. So the API is not only a hosted endpoint you consume; it is something you can run yourself, which matters if you want the directory behind your own firewall or want to point a mirror of the metadata at an internal blocker fleet. ## What the lists cover, and what a subscription actually is The repository description gives the categories: advertisements, trackers, malware, and annoyances. The README repeats that these are filter and host lists for those four things, and that inside your blocking software you subscribe to a set of them. Two properties follow from the format and are worth separating. Filter lists are rule-based, host lists are domain-based, and a client that supports both will treat them differently in terms of breakage risk. That is general knowledge about blocker formats rather than something the README states, so treat the specific compatibility of any given client as something to check in that client. What the README does state about the value proposition is worth keeping in view when evaluating a subscription: blocking is described as protecting the surfer's privacy, preventing malvertising attacks, and reducing bandwidth requirements. If your reason for filtering is one of those three, the directory is directly relevant. If your reason is something else, this catalogue will not have it. ## Curating a subscription is the ongoing work, and it is delegated The repository does not host the list content as its own product; it indexes lists maintained elsewhere. The contribution model reflects that. The README's contributing section opens by routing list submissions and data corrections through pull requests, which means adding a list or correcting metadata about an existing one goes through code review rather than a form. That has an upside and a downside. The upside is that the metadata in the directory is reviewable, so a subscription URL that has quietly changed is likely to be caught. The downside is latency: if a list moves or dies, the directory's record of it only becomes accurate when someone opens a pull request, and nothing in the README suggests an automated staleness check. One line in the README is a comment on the whole project's economics rather than its technical design. It argues that while the free internet depends on advertising revenue, publishers have become too casual about tracking users without consent, and that until publishers change, protecting privacy has to be taken into our own hands. Read that as framing. What you actually subscribe to is a set of URLs, and the ethics of the ad industry does not change whether a given list is well maintained. ## Where this is the wrong tool The clearest wrong-tool case is expecting protection from this repository alone. Install FilterLists, browse filterlists.com, and your browsing behaviour does not change until you configure a client. The project is a directory and a metadata API, and the README says so plainly. The second case is a hard requirement for curated, single-source data with an audit trail. FilterLists aggregates lists whose maintainers apply their own criteria, and the directory does not vet what is inside them. If your compliance posture needs to know exactly which domains are blocked and why, you need to read the lists you subscribe to, not the directory entry describing them. The third is dependency on a release cadence. The repository has no GitHub releases, so there is no versioned artifact to pin for the API's behaviour, only the OpenAPI document at runtime. If your integration needs a stable contract, generate a client from the spec at build time and check it, rather than assuming the hosted API will not change shape. Maintenance itself is not in question here. The repository is not archived, and its last push was on 2026-10-16. ## Comparing it to the list repositories it indexes The realistic alternative is going straight to the individual list maintainers, which is what people did before 2015 and what many still do. The difference is one of scope and trust, not of format. Going direct means you pick each list yourself, from the source repository, and you update it on your own schedule. You get the most current copy and you decide exactly what you take, but you also carry the whole selection problem, which is the problem this project was founded to remove, and you inherit every maintenance question about every list individually. Using FilterLists inverts that. You get a browseable catalogue, a searchable API and reviewable metadata changes, at the cost of one more dependency and some lag between a list changing upstream and the directory reflecting it. If you run a single personal browser, direct subscriptions are entirely adequate. If you provision blocking across a company, an office network or a fleet of devices, having the selection problem solved once and queryable over HTTP is worth more than the freshness you give up. ## Conclusion Adopt FilterLists if you run a blocker, firewall or DNS filter and spend time choosing which lists to subscribe to, since the directory plus the api.filterlists.com endpoint is the whole product and it maps directly onto what your client already supports. Do not adopt it as a standalone privacy tool, because nothing in the repository blocks a request by itself; you need client software installed first. Before you point an automated pipeline at the API, read the OpenAPI document at https://api.filterlists.com/swagger/v1/swagger.json, since that is the contract for list IDs and URLs and it is the artifact your integration will actually depend on. ## FAQ ### Does FilterLists block ads and trackers on its own? No. The README says to first install one of the software tools that supports these lists, then subscribe to a set of them inside that software. FilterLists is the directory of those lists. ### What services does the FilterLists project run? Two: a website, described as a React and TypeScript UI built with Ant Design at filterlists.com, and a Directory API, an ASP.NET Core API serving the core FilterList information at api.filterlists.com. ### Is there an API spec for the FilterLists Directory API? Yes. An OpenAPI 3.0 specification is published at https://api.filterlists.com/swagger/v1/swagger.json, alongside an interactive Swagger UI at the API host. ### Can I self-host the FilterLists API? A Docker image for the Directory API is published as a package named filterlists-directory-api, so the API can be run outside the hosted endpoint at api.filterlists.com. ### How do I submit a new list to FilterLists? Through a pull request. The contributing section says that submitting a new list, or updating data about an existing one, is done by opening a pull request rather than through a form. ## Sources - [collinbarrett/FilterLists on GitHub](https://github.com/collinbarrett/FilterLists) - [Issues](https://github.com/collinbarrett/FilterLists/issues) - [License: MIT](https://github.com/collinbarrett/FilterLists/blob/main/LICENSE) - [Project website](https://filterlists.com) - [README](https://github.com/collinbarrett/FilterLists/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/collinbarrett-filterlists