The Page-Type Lookup API, Explained in Plain Terms

GET /api/check?url={domain-or-url}

Every plan — Pro included — calls the exact same endpoint: GET https://www.aiagentallowlist.com/api/check. Send a domain or a full URL, get back a verdict and the domain's record. There are no separate endpoints for different page types, no batch mode, and nothing to install; the entire integration surface is one authenticated GET request.

# Your Pro-plan key, 90,000 lookups/month, resolved with one call:
curl -H "X-API-Key: YOUR_API_KEY" \
     "https://www.aiagentallowlist.com/api/check?url=stripe.com"

# A full URL works identically — nothing is stripped:
curl -H "X-API-Key: YOUR_API_KEY" \
     "https://www.aiagentallowlist.com/api/check?url=https%3A%2F%2Fdashboard.stripe.com%2Flogin"
#  → "verdict": "deny", "matched": {"layer": "page_type_db", "id": "login", ...}

This mirrors the request shape documented in full on the API docs request reference exactly: one required url parameter (a bare domain or full URL, nothing ever stripped), an optional method parameter (default GET), and your key sent as a header or query parameter. Nothing here is a simplified or alternate surface — it is the same endpoint, described at a faster pace.

One accounting detail worth stating up front, since it shapes every number on this page: a lookup is counted per API call, not per field returned. A single request against the Pro plan's quota comes back with the full record — the page-type map, both content taxonomies, and popularity context — and that entire response still counts as exactly one of the plan's 90,000 monthly lookups. You are never billed per page type resolved or per category attached; the unit of billing is the call itself.

One key, two ways to send it

Subscribing to the Pro plan (or any plan) issues an API key the moment payment completes, visible immediately in your account area. Send it as the X-API-Key header (recommended, since query strings end up in logs) or as an api_key query parameter — both are accepted on every request, on every plan, with no difference in behavior between them.

# Header — recommended for production
curl -H "X-API-Key: YOUR_API_KEY" "https://www.aiagentallowlist.com/api/check?url=stripe.com"

# Query parameter — fine for a quick test
curl "https://www.aiagentallowlist.com/api/check?url=stripe.com&api_key=YOUR_API_KEY"

A missing or unrecognized key returns 401. A valid key on a Pro-plan account that has exhausted its 90,000-lookup monthly quota, or one that has not completed activation, returns 403 with a message distinguishing the two cases. Full error reference on the API docs errors table.

The status codes you actually need to handle

Every code here matches the error reference in the full API docs exactly. The one guardrail-specific decision worth making up front, regardless of plan: what your enforcement point does on 429 or 503. The safe default is to fail closed for domains you have not already resolved this cycle, and serve from your local cache for domains you have.

Two of these codes deserve a closer look because they are easy to confuse with each other during on-call debugging. A 403 on the Pro plan almost always means one of two things: the account has not finished activation, or the 90,000-lookup monthly quota is spent for the current cycle — the JSON body's message and quota fields distinguish the two, so a client should read that message rather than treating every 403 identically. A 429, by contrast, has nothing to do with the monthly quota at all; it is the per-IP burst guard reacting to request rate, and it resolves itself within the same minute once traffic slows, whereas a quota-exhaustion 403 persists until the next billing cycle or an upgrade. Conflating the two in an alerting system produces false alarms in one direction and missed ones in the other.

Caching turns a monthly quota into an effective ceiling much higher than the number on the plan

The Pro plan's 90,000-lookup quota describes API calls, not URLs checked. Because agent traffic revisits the same domains constantly — a research agent looking at the same fifty vendor sites across dozens of tasks, a support agent hitting the same handful of documentation domains all day — a cache keyed by domain lets one lookup cover every URL an agent subsequently opens on that domain, for as long as the cache entry is kept.

Concretely: an agent fleet that opens ten thousand URLs a day across five hundred distinct domains does not need ten thousand lookups a day if it caches by domain — it needs, at most, five hundred, the first time each domain is seen in a given cache window. On the Pro plan's 90,000-lookup monthly allowance, that arithmetic is the difference between running out of quota by the second week of a billing cycle and running comfortably under it with headroom to spare. The pseudo-code pattern for this — check the local cache first, call the API only on a miss, cache the resulting record — is laid out in full in the integration pattern section of the full API docs.

The one thing caching should never do is cache a deny into a permanent allow, or vice versa, past the point where the underlying data might have changed. Page-type URLs move on the timescale of site redesigns, not requests, so a cache lifetime measured in hours to a few days is typical — long enough to capture nearly all the repeat-visit savings, short enough that a re-verified change in the database eventually supersedes a stale local entry rather than being shadowed by it indefinitely.

There is a second reason to cache beyond quota economics: latency. A cached record resolves in the time it takes to read local memory or a fast key-value store; an API call is a network round trip, typically single-digit to low double-digit milliseconds, but not free, and not something you want on the critical path of every single navigation decision an agent makes if the same domain was already resolved moments earlier. Treating the API as the source of truth for a domain's record, refreshed periodically, rather than as a per-URL gate called on every single fetch, is the pattern almost every production deployment converges on regardless of which plan they are on.