IP intelligence

Risk score

The score is arithmetic over the flags in the same response, capped at 100. Recompute it, or ignore it and branch on the booleans. Three rules apply: the datacenter weight is skipped when is_relay, is_crawler or is_corporate_proxy is true, because relay egress, verified crawlers and corporate gateways sit on infrastructure by design and their operator is known; is_vpn answers false on relay egress unless a VPN provider’s own list names the address, because Apple’s first-party declaration outranks the aggregate list that also carries those ranges; and an address on one of your own allow lists scores 0 whatever else fired, with a single allowlisted signal of weight 0 saying why.

Worked examples, as the API answers them:

risk_signals spells the sum out so nobody re-implements it. For the relay example above it reads:

"risk_signals": [
  { "signal": "datacenter", "weight": 0,  "dataset": "datacenter-ranges" },
  { "signal": "relay",      "weight": 10, "dataset": "relay-ranges" }
],
"risk_score": 10,
"risk_level": "low"

Residential proxies are not detectable with open data and are not claimed. When that signal ships it will be a separately labelled field, never folded into these weights. Nor is connection_type a score: it names what positive evidence says the address is attached to, and null never means residential.

Self and browser lookups

The same lookup is available three ways from a server. POST /api/v1/ip takes the address in the body, GET /api/v1/ip/{ip} takes it in the path, and GET /api/v1/ip/me answers for the address the call came from, as seen through the proxy in front of the service. Options ride in the body or the query string.

$ curl https://spaw.co/api/v1/ip/me \
    -H "Authorization: Bearer sk_live_…"

$ curl "https://spaw.co/api/v1/ip/2001:4860:4860::8888?privacy=1" \
    -H "Authorization: Bearer sk_live_…"

$ curl "https://spaw.co/api/v1/ip/72.21.1.1?browser_timezone=America/Chicago&fields=country,timezone,timezone_matches,is_anonymous" \
    -H "Authorization: Bearer sk_live_…"

Two options shape the answer rather than the lookup. browser_timezone is the IANA zone your page read from the visitor’s browser (Intl.DateTimeFormat().resolvedOptions().timeZone); the response compares it with the located zone in timezone_matches, the cheapest strong signal that a connection is not where its owner is. A zone the service does not know answers 422. fields is a comma-separated list of the field names to keep in data: unknown names are ignored, an empty list means everything, and sources is only sent when named, so a page that wants a country and a currency receives two keys rather than sixty. Both work on the three server endpoints and on the browser endpoint below. The two GET endpoints answer with Cache-Control: private, max-age=300, since nothing about an address changes within five minutes.

From a page, use a publishable key against POST /api/v1/ip/public. Create the key on the API keys page and list the domains it may run from; the endpoint checks the browser’s Origin header against that list. Leave ip out and the visitor’s own address is looked up, which is the usual case for choosing a language, a currency, or a consent banner on first paint:

const response = await fetch('https://spaw.co/api/v1/ip/public', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: 'pk_live_…',
    browser_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    fields: 'country,is_eu,currency,timezone_matches,is_anonymous',
  }),
});
const { data } = await response.json();

if (data.is_eu) showConsentBanner();
if (data.currency) setDefaultCurrency(data.currency);
if (data.is_anonymous || data.timezone_matches === false) requireEmailConfirmation();

Lookups bill the key’s owner and the response carries no meta block, so visitors never see the balance. Because the key sits in page source, give it a daily credit cap; once spent, the endpoint answers 429 KEY_SPEND_CAP_REACHED until the next day, and free answers never count toward it. A key that carries a Cloudflare Turnstile pair requires a confirmed turnstile_token with every lookup. The endpoint is throttled at 20 requests a minute per visitor.

Batch and bulk

POST /api/v1/ip/batch looks up as many as 1,000 addresses in one call, in input order, under the single-lookup billing rules: one credit buys five answered addresses, the lookup that opens a block reports credits_used 1 and the next four 0, and each item's meta.ip_lookups_prepaid says how many are left. Reserved and private ranges, unallocated space, addresses nothing knows and repeats are free and use none. Repeats inside the list are looked up once. If the balance runs out mid-list, the paid partial results come back with meta.stopped_reason: "insufficient_credits"; only a batch whose first lookup is refused answers the typed 402. A key with a daily credit cap stops the list the same way once the cap is spent, reporting meta.stopped_reason: "key_spend_cap", so one large batch can never spend past the cap; a call that starts with the cap already spent answers 429 KEY_SPEND_CAP_REACHED and runs nothing. A batch counts as one request against the rate limit.

$ curl https://spaw.co/api/v1/ip/batch \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"ips": ["8.8.8.8", "103.124.165.2", "192.168.1.1"]}'

For log files and exports, a bulk run queues up to 100,000 addresses with POST /api/v1/ip/bulk or from the IP intelligence page in the dashboard. Poll GET /api/v1/ip/bulk/{jobId} for progress and the running low, medium and high counts, then download the CSV from GET /api/v1/ip/bulk/{jobId}/results: one row per input address, in input order, with these columns:

ip, version, reason, network, continent, country, country_name, is_eu, is_eea, privacy_regime, sanctions, fatf_list, region, city, latitude, longitude, location_source, location_confidence, timezone, timezone_source, currency, calling_code, asn, org, asn_type, connection_type, is_mobile, is_satellite, registry, registry_country, allocated_at, is_datacenter, hosting_provider, is_corporate_proxy, corporate_proxy, is_crawler, crawler, crawler_kind, is_blocklisted, blocklist, is_attack_source, attack_source, is_tor, tor_last_seen, is_vpn, is_relay, privacy_service, is_anonymous, account_list, risk_score, risk_level, credits_used

sanctions is written as its codes joined with ; and account_list as kind:name. The fields that only mean something for one live request stay out of the file: timezone_matches needs a browser, seen_by_you would count the run’s own rows, and the opt-in abuse contact, registry details and hostname fields are never fetched by a run.

Once the run has settled, its payload carries a summary added up from the same cells the CSV holds, so it can never disagree with the download: rows and reserved, the top ten countries and networks (asn, org, rows), how many rows carried each signal in signals (datacenter, corporate_proxy, crawler, tor, vpn, relay, anonymous, blocklisted, attack_source, mobile, satellite), how many hit one of your lists in listed, and the risk split. It is null until then. That is the shape of a log file: which countries, which networks, how much of the traffic was infrastructure.

Cancelling stops a queued job on the spot and a running one at its next checkpoint; rows already answered stay billed and downloadable. A run that failed part-way keeps the rows it had already written, and they stay downloadable too. With a webhook_url, the finish is POSTed there as bulk_ip_job.finished, signed with the secret creation returns once: X-Spaw-Signature-V2 carries t={unix seconds},v2={hex}, the HMAC-SHA256 of v2:{t}:{raw body}, and a receiver refuses a t more than five minutes from its own clock so a captured delivery cannot be replayed later. The original X-Spaw-Signature, over the body alone, is sent beside it until 1 March 2027. Send an Idempotency-Key header to make creation safe to retry: the same key with the same request replays the job with Idempotent-Replayed: true, the same key with a different request answers 409 IDEMPOTENCY_KEY_REUSED.

A run that stopped because your credits ran out is resumed rather than uploaded again: top up, then press Resume on the run or call POST /api/v1/ip/bulk/{jobId}/resume. The whole list runs again from the top, and the rows it already answered are repeats inside the seven-day window, so only the rows it never reached are charged. The job keeps its id, its webhook and its cumulative credits_used, while processed , the verdict counts and the summary restart and are rebuilt as the rows come back. A run that stopped for any other reason, or that is already going again, answers 409 JOB_NOT_RESUMABLE; one whose list has passed out of the 30-day retention window answers 409 JOB_INPUT_EXPIRED, and an empty balance answers 402 INSUFFICIENT_CREDITS rather than queueing a run that would stop again at once.

If a delivery fails — your endpoint was down for the half-minute the three attempts cover — ask for it again rather than falling back to polling: press Send webhook again on the run in the dashboard, or call POST /api/v1/ip/bulk/{jobId}/webhook/redeliver. The body is byte-for-byte the body the first delivery carried, rebuilt from the run's own frozen row, so the two reconcile. The signature is new, and has to be: a receiver refuses anything whose t is more than five minutes from its own clock, so verify a redelivery exactly as you verify any other delivery. Nothing deduplicates it for you — a receiver that gets both the original and the redelivery sees bulk_ip_job.finished twice, and job.id is the key to deduplicate on. A run created without a webhook_url answers 409 WEBHOOK_NOT_CONFIGURED and one that has not settled answers 409 JOB_NOT_FINISHED; a run whose last delivery succeeded is not refused, because a receiver can lose a message it has already acknowledged. The delivery is queued rather than made while you wait — one attempt takes half a minute against an endpoint that is down, which is the endpoint you are asking about — so the call answers 202 and the run reads webhook_status: "pending" until a worker has an answer, then delivered or failed with what your endpoint said in webhook_detail. The dashboard shows the same three states beside the run. It is free and capped at ten a minute counted per signed-in user: neither per key nor per account, so two keys held by one person share the one budget while two teammates have one each.

IP endpoints have their own rate limit of 50 requests per second per key, separate from the 5 per second that applies to the email endpoints.

Outcome feedback

A lookup can only say what the feeds know. What you learn afterwards, a confirmed fraudulent order, a scraper, a bot that got through, a chargeback, can be sent back so your own later lookups of that address carry it: POST /api/v1/ip/feedback takes up to 1,000 items of an address and an outcome, abuse, fraud, bot or chargeback, with an optional occurred_at. It is free and never logged as a lookup.

$ curl https://spaw.co/api/v1/ip/feedback \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"items": [{"ip": "203.0.113.9", "outcome": "fraud"}]}'

Any report you made about an address inside the last 30 days adds reported_abuse (+60, dataset abuse-feedback) to your own lookups of it. Once three or more accounts report the same address inside 30 days, everyone's lookups of it carry reported_abuse_widely (+40); only the number of reporting accounts is ever read, never who reported or what. Neither signal turns a null score into a number: an address no feed evaluated stays unscored.

Reports are the one thing the IP product stores on purpose, and even they never hold the address: each is a salted SHA-256 hash of the canonical address with the outcome and a timestamp, which can confirm a later lookup of the same address but cannot be read back into one. Malformed and reserved addresses are skipped and counted, not rejected. Reports are kept for 90 days, and GET /api/v1/ip/feedback/summary answers that window: totals per outcome, distinct addresses, and the IPv4 and IPv6 split.

Monitored lists

Your own addresses deserve the same check as your visitors’. A monitored list ( POST /api/v1/ip/monitors) keeps up to 500 of them, egress addresses, mail servers and office connections, under a daily, weekly or monthly re-check. The first run sets the baseline; from the next run on, every address that newly lands on a threat blocklist or an attack-source list, becomes a Tor exit or scores high arrives by email with the reason, so you learn that a mail server sits on Spamhaus DROP before your recipients’ inboxes do.

An entry can be a prefix as well as an address: a CIDR of at most 256 addresses ( /24 to /32, /120 to /128) is expanded into its addresses when the list is saved, and the whole list still fits under the 500 cap. A wider prefix is refused with a 422 that says to split it, because a /16 is 65,536 lookups a run and would be a bill nobody asked for.

Each run bills every address like a single lookup, five answered addresses to the credit, and the seven-day repeat marker applies, so a daily list costs at most one credit per five addresses a week; reserved and unallocated addresses are free. GET /api/v1/ip/monitors/{id} answers the last run per address: its status (clean, flagged or reserved), the flags that fired (blocklisted, attack_source, tor, high_risk), the list that names it, and whether it changed. POST /api/v1/ip/monitors/{id}/run re-checks the list ahead of schedule, and DELETE stops it.

A monitor can post its runs as well as email about them. Set webhook_url (https) when you create it, or later with a PATCH, and the signing secret comes back once in that response and is never readable again. webhook_events decides which runs are posted: changes, the default, posts only when the run found something new — an address that is newly flagged, or one whose status changed — or stopped early, and every_run posts after every run, which also tells you the monitor is still running. The body is { "event": "ip_monitor.run", "monitor": {…}, "summary": {…}, "changes": [ … ] }, where changes names the addresses the alert email names, and X-Spaw-Signature-V2 carries t={unix seconds},v2={hex}, where the hex is the HMAC-SHA256 of v2:{t}:{raw body} keyed with the secret. Refuse anything whose t is more than five minutes from your own clock: that window is what stops a captured delivery being replayed at you later. The original X-Spaw-Signature, the HMAC of the body alone, is sent beside it until 1 March 2027 and still verifies. Connection errors and 5xx answers are retried twice, three attempts in all; webhook_status and webhook_detail on the monitor say how the last delivery went. A URL that resolves onto a private network is refused at delivery, every time, because DNS can be repointed after a URL is saved.

A monitor is changed rather than replaced: PATCH /api/v1/ip/monitors/{id} takes name, ips, cadence and the webhook fields, and applies only the ones you send. That matters because what the last run recorded per entry is the baseline every alert is compared against: deleting a monitor and creating it again throws that away, and the first run of the new one only sets a baseline — a full cycle of silence, which is the one thing a monitor is bought to prevent. Replacing the list keeps what was recorded about the addresses that stayed, deletes what was recorded about the ones you removed, and gives a new entry no baseline. Changing the cadence neither skips a run nor starts a second one: a run already scheduled sooner than the new interval still happens, and a longer interval applies from the one after it. A body naming no field it could change answers 422.

A monitor that stops being run is deleted, and the identifiers and results it stored go with it. prunes_after_days on every monitor payload says how long that takes. A monitor in active use is never pruned: each run advances last_run_at, so the window only closes on a list that has genuinely stopped being re-checked — at which point holding the details somebody gave you serves no purpose. Deleting a monitor yourself removes everything it held at once.

Your own lists

The feeds know the Internet; only you know your office egress, your partners’ ranges and the addresses that already burned you. An account keeps up to 20 lists of up to 5,000 entries each, every entry an address or a CIDR prefix (IPv4 or IPv6), of one of two kinds. An allow list zeroes the score of every address it names: risk_score 0, risk_level low, and risk_signals carrying a single allowlisted entry of weight 0 so the reader sees why. A deny list tops it: denylisted +100, which is high on its own, whether or not any feed had anything to say. Whichever list matched is named in account_list with the entry that matched, and sources gains account-lists with the date the list last changed. Deny lists are checked before allow lists, so an address on both fails closed.

$ curl https://spaw.co/api/v1/ip/lists \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"name": "Office egress", "kind": "allow", "entries": ["203.0.113.0/24", "2001:db8:10::/48"]}'

GET /api/v1/ip/lists names the account’s lists with their entry counts and the limits in meta; POST creates one (201); GET /api/v1/ip/lists/{listId} returns it with its entries; PATCH renames it, changes its kind or replaces its entries, applying only the fields you send, and a body naming none is a 422; DELETE removes it. Entries are canonicalised and deduplicated, an entry that is neither an address nor a prefix is a 422, and creating a twenty-first list answers 409 IP_LIST_LIMIT_REACHED. The dashboard’s IP page has a Lists tab for the same thing by hand.

Lists belong to the account, not to the member who created them: any member manages any list, and they apply to every lookup the account is billed for — the API, the dashboard, batches, bulk runs, monitors and the browser widget alike. They are the one signal in the answer that is yours rather than the Internet’s, and the bulk summary counts how many rows hit one. Nothing about an entry leaves the account, and a list is deleted with it.

Networks and ranges

Two lookups answer about a network rather than an address. GET /api/v1/ip/asn/{asn} turns the ASN database inside out: every prefix the database assigns to the autonomous system, in both families, with the operator’s name, the asn_type the name settles, the registry facts the RIR statistics record for the system (registry, registry_country, allocated_at), and the operator-level flags the feeds answer without an address: is_blocklisted with the blocklist that names it (Spamhaus ASN-DROP), is_satellite and is_mobile. prefix_count is never capped; prefixes carries at most 500 per family in index order and truncated says when a family was cut. A system the index does not know answers 404 ASN_NOT_FOUND, free; a server whose index has not been built yet answers 501 ASN_INDEX_UNAVAILABLE, free. An answer costs 1 credit, and the seven-day repeat rule applies per number.

$ curl https://spaw.co/api/v1/ip/asn/14593 \
    -H "Authorization: Bearer sk_live_…"

GET /api/v1/ip/range?prefix=203.0.113.0/24 answers about a prefix (a bare address is a /32 or /128): the canonical prefix, first and last address, addresses (null when 2^bits does not fit an integer), the network of the first address with network_agrees (whether the last address resolves to the same system), the country of the first address with country_agrees, the registry facts of the first address, and signals: for each of datacenter, vpn, relay, tor, anycast, allocated, blocklist, attack_source, crawler and corporate_proxy, whether any feed record overlaps the prefix (tri-state like the flags, null when no installed feed of that signal covers the family), how many ranges intersect it (capped at 10,000 per feed, truncated says so) and the providers named. It is the quick way to learn that a /24 sits on Spamhaus DROP or that a partner’s range is really a cloud’s, before adding it to a list or a monitor. A prefix inside reserved space answers reason: reserved_range with everything else null, free; an answer costs 1 credit with the repeat rule keyed by the canonical prefix.

$ curl "https://spaw.co/api/v1/ip/range?prefix=8.8.8.0/24" \
    -H "Authorization: Bearer sk_live_…"

The ASN index is rebuilt from the monthly DB-IP ASN database and reported on /status as asn-prefixes; both endpoints sit under the ip key scope and the IP rate limit. The same facts are published without a key for the largest systems on the autonomous system pages, and every feed a range answer reads has its own data source page.