aitoolsblocklist 1.0.0

Python client for the AI Tools Blocklist API — classified AI-tool domains for web filtering, DNS security, and DLP.

aitoolsblocklist

A lightweight, production-ready Python client for the AI Tools Blocklist API — a daily-refreshed database of classified AI-tool domains built for web filtering, DNS security, data-loss prevention, and acceptable-use enforcement. The package wraps the REST API in a small, typed, dependency-light interface so security engineers, network administrators, and compliance teams can look up, filter, and synchronize AI-tool domain intelligence directly from Python.

The underlying dataset is a specialized extraction from a 102-million-domain enterprise web filtering infrastructure. It contains tens of thousands of AI-tool domains — chatbots, code assistants, image and video generators, voice-cloning services, autonomous agents, AI companions, and more — each classified into functional categories and subcategories rather than a single flat "AI" label. That granularity is what makes per-category policy possible: permit an approved AI tutor while blocking a deepfake generator, or allow a coding assistant while flagging an unvetted document-processing service.

---

Installation

pip install aitoolsblocklist

The only runtime dependency is requests. Python 3.7 and newer are supported.

Quick start

from aitoolsblocklist import AIToolsBlocklistClient

client = AIToolsBlocklistClient("atb_your_api_key_here")

# Single lookup — is this domain an AI tool, and what kind?
result = client.lookup("claude.ai")
print(result["in_blocklist"])        # True
print(result["primary_category"])    # "Text & Language"
print(result["subcategory"])         # "General assistants & chatbots"
print(result["risk_tier"])           # "high"

# A convenience boolean for policy gates
if client.is_blocked("midjourney.com"):
    enforce_block_policy("midjourney.com")

An API key is required and is available from the account dashboard after subscribing to any paid plan. Keys use the atb_ prefix for easy identification in logs, and are passed automatically as a Bearer token on every request.

Technical overview

Authentication and configuration

The client sends your key in the Authorization: Bearer header, requests gzip-compressed responses, and sets a descriptive User-Agent. Construction takes a handful of options:

client = AIToolsBlocklistClient(
    api_key="atb_your_api_key_here",
    base_url="https://api.aitoolsblocklist.com/v1",  # override for testing
    timeout=30,        # per-request timeout, seconds
    max_retries=3,     # automatic backoff on 429 and 5xx
)

Transient failures — HTTP 429 rate limits and 5xx server errors — are retried automatically with exponential backoff, honoring the Retry-After header when present. Authentication problems raise immediately, because retrying a revoked key is pointless.

Endpoints and methods

Each REST endpoint maps to a single method:

Method	Endpoint	Purpose
lookup(domain)	GET /v1/lookup/{domain}	Classify one domain
is_blocked(domain)	—	Convenience boolean wrapper
bulk_lookup(domains)	POST /v1/bulk-lookup	Classify up to 1,000 domains
bulk_lookup_all(domains)	—	Auto-chunks any number of domains
domains(**filters)	GET /v1/domains	One filtered, paginated page
iter_domains(**filters)	—	Iterate the entire filtered list
delta(since)	GET /v1/delta	Changes since a timestamp
taxonomy()	GET /v1/taxonomy	Category tree with IDs
stats()	GET /v1/stats	Database statistics

Single and bulk lookups

Pass a bare domain — claude.ai, not https://claude.ai/chat. Subdomains resolve to their registrable domain, so chat.openai.com returns the classification for openai.com. Both found and not-found responses are HTTP 200; your integration checks one unambiguous in_blocklist boolean instead of distinguishing "not found" from "bad request."

report = client.bulk_lookup(["openai.com", "github.com", "notion.so"])
for row in report["results"]:
    print(row["domain"], row["in_blocklist"], row.get("primary_category"))

# For arbitrarily large inputs, chunking is handled for you:
everything = client.bulk_lookup_all(my_10000_domains)

Loading and synchronizing the full list

For a local cache, DNS sinkhole, or firewall External Dynamic List, stream the full classified list. iter_domains() walks cursor-based pagination transparently:

with open("ai_blocklist.txt", "w") as fh:
    for record in client.iter_domains(status="active", min_confidence=0.9):
        fh.write(record["domain"] + "\n")

Then keep it current with a daily delta sync instead of re-downloading everything:

changes = client.delta(since="2026-07-01T00:00:00Z")
for added in changes["added"]:
    local_set.add(added["domain"])
for removed in changes["removed"]:
    local_set.discard(removed["domain"])

This "full load once, delta forever" pattern lets a modest request quota back millions of local lookups, because the actual matching happens in your own Redis, SQLite, or flat file.

Error handling

The client raises a small, specific exception hierarchy so callers can react precisely:

from aitoolsblocklist import (
    AIToolsBlocklistError, AuthenticationError,
    RateLimitError, NotFoundError,
)

try:
    result = client.lookup("example.com")
except AuthenticationError:
    ...   # 401/403 — rotate or renew the key
except RateLimitError:
    ...   # 429 after retries — back off or upgrade the plan
except AIToolsBlocklistError:
    ...   # any other API or network failure

The client is also a context manager, so the underlying HTTP session is cleaned up automatically:

with AIToolsBlocklistClient("atb_your_api_key_here") as client:
    print(client.stats())

---

Why domain-level AI classification is needed

The technical interface above solves a problem that has become urgent for nearly every organization that runs a network: you can no longer see, let alone govern, where your data goes when employees and students use AI tools.

Two years ago, "AI at work" meant a handful of well-known services. Today, thousands of AI products launch every month, each with its own domain, and each capable of receiving text, code, images, or documents that a user pastes in. A blanket firewall rule cannot keep up, and a hand-maintained list of the famous fifty tools is stale within a week. The result is shadow AI: unsanctioned tools processing sensitive information with no oversight. Surveys of enterprise security leaders consistently rank data exposure through generative AI among their fastest-growing risks, and the guidance emerging from public research institutions reflects the same concern.

The data-governance problem

When an employee pastes a customer contract into an unfamiliar AI summarizer, or a developer sends proprietary source code to an online "explain this function" tool, that data leaves the organization's control. It may be logged, used for model training, or retained indefinitely. This is not a hypothetical: the U.S. National Institute of Standards and Technology's AI Risk Management Framework explicitly identifies data confidentiality and third-party dependency as core risks to be mapped and managed, and encourages organizations to maintain an inventory of the AI systems their people actually use. You cannot inventory what you cannot see, and you cannot see AI-tool usage at the network layer without knowing which of the millions of domains crossing your egress are AI tools in the first place.

Foundational work on the risks of large-scale models — for example, research hosted on arXiv from academic and industry labs — has documented how readily these systems memorize and can surface training data, which is precisely why unsanctioned data submission matters. Domain-level classification is the practical control point: it turns an unbounded, ever-changing population of AI services into a queryable list your existing security stack can act on.

Education and duty of care

Schools face a sharper version of the same problem, layered on top of legal obligations. In the United States, districts that receive certain federal funding must operate a technology protection measure under the Children's Internet Protection Act — the Federal Communications Commission's CIPA guidance sets out the requirement. AI chatbots, essay generators, and deepfake tools complicate that duty enormously: a district may want to permit an approved AI tutor that supports learning while blocking an essay-writing service that undermines academic integrity, or a companion-chat app inappropriate for minors. A single "AI" category cannot express that policy; per-subcategory classification can.

Academic-integrity offices are grappling with the same distinction. University teaching-and-learning centers — such as the guidance published by Stanford University and other institutions on generative AI in coursework — increasingly frame the question not as "AI or no AI" but as "which uses of which tools are appropriate for which assignments." Enforcing a nuanced policy at the network level requires data that is equally nuanced.

Why a purpose-built, refreshed feed

General web-categorization databases were not designed for this. They answer "is this a shopping site, a news site, a social network?" — not "is this an AI code assistant, an AI voice cloner, or an AI research agent?" The pace is also different: general categories are stable for years, whereas AI tools appear and disappear weekly. The dataset behind this client is rebuilt daily precisely so that new tools are caught close to launch rather than months later, and it is organized around the functional distinctions that policy actually turns on.

The public-interest research community has long argued that transparency and classification are prerequisites for governing new technologies. Digital-rights organizations such as the Electronic Frontier Foundation emphasize that filtering and monitoring must be precise and accountable rather than blunt — and precision is exactly what per-category domain intelligence enables. A well-classified feed lets an administrator write a rule that blocks a genuine risk category without collaterally breaking legitimate, sanctioned tools, which is the difference between a policy people follow and one they route around.

Where this package fits

This library is the thin, reliable bridge between that intelligence and your own systems. Drop lookup() into a proxy plugin or SOAR playbook for real-time decisions; use iter_domains() to seed a DNS sinkhole or firewall EDL; run delta() on a nightly cron to stay current. Because the heavy matching runs locally against data you have already synced, the approach scales from a single script to millions of lookups a day without hammering the API.

If AI-tool visibility and control are on your roadmap — for security, for compliance, or for duty of care — the AI Tools Blocklist provides the data, and this package provides the Python integration.

---

Links

• Product and API documentation: https://www.aitoolsblocklist.com
• NIST AI Risk Management Framework: https://www.nist.gov/itl/ai-risk-management-framework
• FCC — Children's Internet Protection Act: https://www.fcc.gov/consumer-governmental-affairs/childrens-internet-protection-act
• arXiv (open-access research): https://arxiv.org/

License

MIT