Skip to main content
API docs by Redocly

LimesIndex API (1.0.0)

Download OpenAPI specification:Download

License: Proprietary

IP Intelligence and Registry API

LimesIndex provides comprehensive IP address intelligence including ASN information, geolocation, datacenter detection, threat scoring, and AI crawler identification.

IP Lookup

IP address intelligence operations

Single IP lookup

Look up intelligence data for a single IP address. Returns ASN information, geolocation, detection flags (datacenter, VPN, proxy, Tor, AI crawler), and threat scoring.

Authorizations:
ApiKeyAuth
path Parameters
ip
required
string
Example: 8.8.8.8

IPv4 or IPv6 address to look up

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

X-RateLimit-Limit
integer
Example: "1000"

Maximum number of requests allowed per time window

X-RateLimit-Remaining
integer
Example: "999"

Number of requests remaining in the current time window

X-RateLimit-Reset
integer <int64>
Example: "1704067200"

Unix timestamp when the rate limit window resets

X-Cache-Status
string
Enum: "HIT" "MISS"
Example: "HIT"

Cache status for the request (HIT or MISS)

Response Schema: application/json
required
object (IPLookupResult)

IP address intelligence data

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "8.8.8.8",
    • "prefix": "8.8.8.0/24",
    • "asn": 15169,
    • "asn_name": "Google LLC",
    • "country": "US",
    • "rir": "ARIN",
    • "connection_type": "datacenter",
    • "detection": {
      },
    • "threat": {
      }
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440000",
    • "processing_time_ms": 5,
    • "cache_status": "HIT",
    • "dataset_version": 1
    }
}

Batch IP lookup

Look up intelligence data for multiple IP addresses in a single request. Maximum batch size is 1000 IPs. Returns a map of IP addresses to their lookup results.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
ips
required
Array of strings [ 1 .. 1000 ] items

Array of IP addresses to look up (maximum 1000)

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

X-RateLimit-Limit
integer
Example: "1000"

Maximum number of requests allowed per time window

X-RateLimit-Remaining
integer
Example: "999"

Number of requests remaining in the current time window

X-RateLimit-Reset
integer <int64>
Example: "1704067200"

Unix timestamp when the rate limit window resets

Response Schema: application/json
required
object

Map of IP addresses to their lookup results

required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "ips": [
    • "8.8.8.8",
    • "1.1.1.1",
    • "208.67.222.222"
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "8.8.8.8": {
      },
    • "1.1.1.1": {
      }
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440001",
    • "processing_time_ms": 15,
    • "dataset_version": 1
    }
}

ASN Lookup

Autonomous System Number lookup operations

ASN lookup

Look up information for an Autonomous System Number (ASN). Returns the organization name, country, RIR, and optionally associated IP prefixes.

Authorizations:
ApiKeyAuth
path Parameters
asn
required
integer [ 1 .. 4294967295 ]
Example: 15169

Autonomous System Number to look up

query Parameters
include_prefixes
boolean
Default: false

Include associated IP prefixes in the response

prefix_limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of prefixes to return (max 1000)

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

X-RateLimit-Limit
integer
Example: "1000"

Maximum number of requests allowed per time window

X-RateLimit-Remaining
integer
Example: "999"

Number of requests remaining in the current time window

Response Schema: application/json
required
ASNInfo (object) or ASNInfoWithPrefixes (object)
required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "asn": 15169,
    • "name": "Google LLC",
    • "country": "US",
    • "rir": "ARIN",
    • "allocation_date": "2000-03-30"
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440003",
    • "processing_time_ms": 2
    }
}

Search ASNs by name

Search for Autonomous System Numbers by organization name. Uses full-text search for matching.

Authorizations:
ApiKeyAuth
query Parameters
q
required
string >= 2 characters
Example: q=Google

Search query (minimum 2 characters)

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return (max 100)

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

Response Schema: application/json
required
object
required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "results": [
      ],
    • "count": 2
    },
  • "meta": {
    • "processing_time_ms": 5
    }
}

ASN registry statistics

Get statistics about the ASN registry including total count and breakdown by RIR.

Authorizations:
ApiKeyAuth

Responses

Response Schema: application/json
required
object
required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "total_asns": 75000,
    • "by_rir": {
      }
    },
  • "meta": {
    • "processing_time_ms": 10
    }
}

Blocklist

IP blocklist lookup and monitoring

Single IP blocklist check

API-key authenticated check for whether an IP address is currently listed on the LimesIndex-owned blocklist.

Authorizations:
ApiKeyAuth
path Parameters
ip
required
string
Example: 192.0.2.1

IPv4 or IPv6 address to check

Responses

Response Schema: application/json
required
object (BlocklistIPResult)

Blocklist check result for a single IP

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "192.0.2.1",
    • "listed": true,
    • "listing": {
      }
    },
  • "meta": {
    • "processing_time_ms": 3
    }
}

Batch blocklist check

Check multiple IP addresses against the blocklist in a single request. Maximum 100 IPs per request.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
ips
required
Array of strings [ 1 .. 100 ] items

Array of IP addresses to check (maximum 100)

Responses

Response Schema: application/json
required
Array of objects (BlocklistBatchItem)
required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "ips": [
    • "192.0.2.1",
    • "198.51.100.5",
    • "203.0.113.10"
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "meta": {
    • "processing_time_ms": 8
    }
}

Blocklist statistics

Get aggregate statistics about current blocklist entries, including total active listings, breakdown by type, new listings in the last 24 hours, and delistings in the last 24 hours.

Authorizations:
ApiKeyAuth

Responses

Response Schema: application/json
required
object (BlocklistStatsResult)

Blocklist statistics data

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "total_active": 4523,
    • "by_type": {
      },
    • "new_listings_24h": 92,
    • "delistings_24h": 17
    },
  • "meta": {
    • "processing_time_ms": 5
    }
}

Recent blocklist events

Get recent listing and delisting events from the LimesIndex-owned blocklist. Results are ordered newest first and paginated with limit/offset for feed and dashboard polling.

Authorizations:
ApiKeyAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 50

Number of events to return. Defaults to 50 and is capped at 100.

offset
integer >= 0
Default: 0

Number of events to skip.

Responses

Response Schema: application/json
required
object (BlocklistRecentResult)

Paginated recent blocklist event result

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "events": [
      ],
    • "count": 2,
    • "limit": 50,
    • "offset": 0
    },
  • "meta": {
    • "processing_time_ms": 4
    }
}

Email Reputation

IP sending reputation scoring and subnet analysis

IP sending reputation

Get the email sending reputation score for an IP address. Includes reputation factors, 30-day history, and subnet analysis. Score ranges from 0 (worst) to 100 (best).

Authorizations:
ApiKeyAuth
path Parameters
ip
required
string
Example: 198.51.100.25

IPv4 or IPv6 address to check

Responses

Response Schema: application/json
required
object (ReputationResult)

Full reputation data for an IP

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "198.51.100.25",
    • "score": 78,
    • "level": "good",
    • "factors": [
      ],
    • "history": [
      ],
    • "subnet": {
      }
    },
  • "meta": {
    • "processing_time_ms": 12
    }
}

Batch reputation check

Get reputation scores for multiple IP addresses in a single request. Maximum 100 IPs per request. Returns score and level for each IP.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
ips
required
Array of strings [ 1 .. 100 ] items

Array of IP addresses (maximum 100)

Responses

Response Schema: application/json
required
Array of objects (ReputationBatchItem)
required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "ips": [
    • "198.51.100.25",
    • "203.0.113.50"
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "meta": {
    • "processing_time_ms": 20
    }
}

Subnet reputation (neighbors)

Analyze the /24 subnet reputation around an IP address. Shows how many IPs in the neighborhood are listed and the overall contamination level.

Authorizations:
ApiKeyAuth
path Parameters
ip
required
string
Example: 198.51.100.25

IPv4 or IPv6 address to analyze subnet for

Responses

Response Schema: application/json
required
object (SubnetReputationSummary)

Subnet reputation analysis for a /24

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "subnet": "198.51.100.0/24",
    • "total_ips_seen": 12,
    • "listed_count": 1,
    • "avg_reputation": 65,
    • "worst_score": 30,
    • "contamination_level": "light"
    },
  • "meta": {
    • "processing_time_ms": 8
    }
}

Email Intelligence

Domain DNS authentication validation

Domain DNS authentication check

Validate email authentication DNS records (SPF, DKIM, DMARC) for a domain. Returns a domain authentication score (0-100), letter grade, individual record details, and actionable recommendations.

Authorizations:
ApiKeyAuth
path Parameters
domain
required
string
Example: example.com

Domain name to check

query Parameters
selectors
string
Example: selectors=google,selector1,default

Comma-separated DKIM selectors to check (defaults to common selectors)

Responses

Response Schema: application/json
required
object (DomainDNSResult)

Domain DNS authentication analysis

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "domain": "example.com",
    • "domain_auth_score": 85,
    • "grade": "B",
    • "mx": {
      },
    • "spf": {
      },
    • "dkim": [
      ],
    • "dmarc": {
      },
    • "recommendations": [
      ]
    },
  • "meta": {
    • "processing_time_ms": 450
    }
}

Telemetry

Email sending metric ingestion from partners

Telemetry ingestion

Ingest email sending telemetry observations from partner systems. Accepts bounce rates, complaint rates, and volume metrics. Maximum 100 observations per request. Timestamps must be within the last 48 hours.

Requires authentication.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects (TelemetryObservation) [ 1 .. 100 ] items

Array of observations (maximum 100)

Array ([ 1 .. 100 ] items)
ip
required
string

Sending IP address

bounce_rate
number <double> [ 0 .. 1 ]

Bounce rate (0.0 to 1.0)

complaint_rate
number <double> [ 0 .. 1 ]

Complaint rate (0.0 to 1.0)

volume_24h
integer >= 0

Sending volume in the last 24 hours

observed_at
string <date-time>

When the observation was made (must be within last 48h)

Responses

Response Schema: application/json
required
object (TelemetryIngestResult)

Telemetry ingestion result

required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "observations": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "accepted": 2,
    • "rejected": 0
    },
  • "meta": {
    • "processing_time_ms": 15
    }
}

Warmup

IP warm-up advisor and pool classification

IP warm-up status

Get warm-up advisor information for an IP address. Returns the current warm-up status, recommended daily volume, and guidance on whether to pause sending.

Authorizations:
ApiKeyAuth
path Parameters
ip
required
string
Example: 198.51.100.25

IPv4 or IPv6 address to check warm-up status

Responses

Response Schema: application/json
required
object (WarmupResult)

Warm-up advisor data

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "198.51.100.25",
    • "status": "warming",
    • "days_sending": 14,
    • "reputation_score": 72,
    • "recommended_daily_volume": 200,
    • "auto_pause_recommended": false,
    • "next_milestone": "2026-04-28",
    • "next_milestone_volume": 500
    },
  • "meta": {
    • "processing_time_ms": 10
    }
}

Pool classification

Classify a set of IP addresses into pool tiers based on their reputation, warm-up status, and blocklist state. Maximum 50 IPs per request. Returns tier assignments and recommendations for each IP.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
ips
required
Array of strings [ 1 .. 50 ] items

Array of IP addresses to classify (maximum 50)

Responses

Response Schema: application/json
required
Array of objects (PoolClassifyItem)
required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "ips": [
    • "198.51.100.25",
    • "203.0.113.50",
    • "192.0.2.100"
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "meta": {
    • "processing_time_ms": 35
    }
}

Tools

Free public email infrastructure tools

Email header analysis

API-key-protected compatibility alias for the public Header Lab route. New anonymous clients should use /v1/public/tools/header-analyzer.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
headers
required
string <= 49152 characters

Raw email headers to analyze (maximum 48 KiB UTF-8 bytes at runtime)

Responses

Response Schema: application/json
required
object (HeaderAnalyzerResult)

Email header analysis result

required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "headers": "Received: from mail.example.com (198.51.100.25) by mx.google.com...\nAuthentication-Results: mx.google.com; spf=pass..."
}

Response samples

Content type
application/json
{
  • "data": {
    • "received_chain": [
      ],
    • "authentication": {
      },
    • "infrastructure": {
      },
    • "anomalies": [ ]
    },
  • "meta": {
    • "processing_time_ms": 25
    }
}

Domain health check

API-key-protected compatibility alias for the public Domain Health route. New anonymous clients should use /v1/public/tools/domain-check/{domain}. The complete DNS operation has a five-second deadline and shares the bounded resolver budget.

Authorizations:
ApiKeyAuth
path Parameters
domain
required
string
Example: example.com

Domain name to check

Responses

Response Schema: application/json
required
object (DomainCheckResult)

Domain health check result (public tool)

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "domain": "example.com",
    • "grade": "B",
    • "score": 80,
    • "mx": {
      },
    • "spf": {
      },
    • "dkim": [
      ],
    • "dmarc": {
      },
    • "recommendations": [
      ]
    },
  • "meta": {
    • "processing_time_ms": 500
    }
}

Public

Anonymous, rate-limited endpoints under /v1/public/*. Per ADR-021 these bypass API-key auth even when REQUIRE_AUTH=true and are subject to a 60 req/min per-IP anonymous quota.

Public single IP lookup

Rate-limited IP intelligence lookup for anonymous customer tools. This is the reviewed public counterpart to /v1/ip/{ip}.

path Parameters
ip
required
string
Example: 8.8.8.8

IPv4 or IPv6 address to look up

Responses

Response Schema: application/json
required
object (IPLookupResult)

IP address intelligence data

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "8.8.8.8",
    • "prefix": "8.8.8.0/24",
    • "asn": 15169,
    • "asn_name": "Google LLC",
    • "organization": "Google LLC",
    • "provider": "Google",
    • "country": "US",
    • "rir": "ARIN",
    • "connection_type": "datacenter",
    • "hostname": "dns.google",
    • "service_url": "https://dns.google/",
    • "service_title": "Google Public DNS",
    • "service_server": "scaffolding on HTTPServer2",
    • "tls_organization": "Google LLC",
    • "rpki_status": "valid",
    • "detection": {
      },
    • "threat": {
      },
    • "geolocation": {
      },
    • "geo_consensus": {
      },
    • "geo_stability": {
      },
    • "ownership_timeline": [
      ],
    • "asn_reputation": {
      }
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440000",
    • "processing_time_ms": 5,
    • "cache_status": "HIT",
    • "dataset_version": 1
    }
}

Public email header analysis

Analyze raw email headers without an API key. The route is restricted to the explicit ADR-021 public namespace and authoritative 60 RPM per-client anonymous rate limit. The JSON body is capped at 64 KiB, the headers value at 48 KiB, and IP enrichment at 20 Received hops.

Request Body schema: application/json
required
headers
required
string <= 49152 characters

Raw email headers to analyze (maximum 48 KiB UTF-8 bytes at runtime)

Responses

Response Schema: application/json
required
object (HeaderAnalyzerResult)

Email header analysis result

required
object (Meta)

Response metadata

Request samples

Content type
application/json
{
  • "headers": "Received: from mail.example.com..."
}

Response samples

Content type
application/json
{
  • "data": {
    • "received_chain": [
      ],
    • "authentication": {
      },
    • "infrastructure": {
      },
    • "anomalies": [
      ]
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440000",
    • "processing_time_ms": 5,
    • "cache_status": "HIT",
    • "dataset_version": 1
    }
}

Public domain health check

Check MX, SPF, DKIM, and DMARC posture without an API key. The route is restricted to the ADR-021 public namespace and anonymous rate limit. It accepts strict public DNS hostnames only. All DNS work is cancellation-aware, has a five-second total deadline, and shares the per-request lookup budget and process-wide concurrency bound.

path Parameters
domain
required
string
Example: example.com

Domain name to check

Responses

Response Schema: application/json
required
object (DomainCheckResult)

Domain health check result (public tool)

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "domain": "example.com",
    • "grade": "B",
    • "score": 80,
    • "mx": {
      },
    • "spf": {
      },
    • "dkim": [
      ],
    • "dmarc": {
      },
    • "recommendations": [
      ]
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440000",
    • "processing_time_ms": 5,
    • "cache_status": "HIT",
    • "dataset_version": 1
    }
}

Public single IP blocklist check

Public, rate-limited check for whether an IP address is currently listed on the LimesIndex-owned blocklist.

Mounted on the /v1/public/* namespace per ADR-021 — never auth-gated, even when REQUIRE_AUTH=true. It shares the authoritative 60 req/min per-client origin quota for the public namespace.

path Parameters
ip
required
string
Example: 192.0.2.1

IPv4 or IPv6 address to check

Responses

Response Schema: application/json
required
object (BlocklistIPResult)

Blocklist check result for a single IP

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "192.0.2.1",
    • "listed": true,
    • "listing": {
      }
    },
  • "meta": {
    • "processing_time_ms": 3
    }
}

Echo the caller's IP (with optional enrichment)

Returns the caller's public IP using the same trusted Cloudflare/nginx identity selected by the authoritative anonymous rate limiter. Caller- supplied forwarding headers from untrusted peers are ignored. When the IP service is configured, the response also includes ASN, ASN name, country, and organization.

This endpoint is part of the /v1/public/* anonymous namespace (see ADR-021) and never requires authentication, even when REQUIRE_AUTH=true. It shares the authoritative 60 req/min per-client origin quota for the public namespace.

Used by the Diagnose page's "Check my IP" button.

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

X-RateLimit-Limit
integer
Example: "1000"

Maximum number of requests allowed per time window

X-RateLimit-Remaining
integer
Example: "999"

Number of requests remaining in the current time window

X-RateLimit-Reset
integer <int64>
Example: "1704067200"

Unix timestamp when the rate limit window resets

Response Schema: application/json
required
object
required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "ip": "203.0.113.5",
    • "asn": 15169,
    • "asn_name": "GOOGLE",
    • "country": "US",
    • "organization": "Google LLC"
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440000",
    • "processing_time_ms": 3,
    • "cache_status": "HIT",
    • "dataset_version": 42
    }
}

Public ASN lookup (CX-1211)

Public, unauthenticated ASN lookup used by the free /tools/asn ASN Health page. Returns the same ASNInfo payload as the authenticated /v1/asn/{asn} endpoint, including the cross-reference reputation summary (UCEprotect L1/L2/L3, Spamhaus DROP/EDROP) so anonymous visitors can check whether an ASN is safe to lease IPs from.

Mounted on the /v1/public/* namespace per ADR-021 — never auth-gated, even when REQUIRE_AUTH=true. It shares the authoritative 60 req/min per-client origin quota for the public namespace.

path Parameters
asn
required
integer [ 1 .. 4294967295 ]
Example: 20473

Autonomous System Number to look up

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

X-RateLimit-Limit
integer
Example: "1000"

Maximum number of requests allowed per time window

X-RateLimit-Remaining
integer
Example: "999"

Number of requests remaining in the current time window

X-RateLimit-Reset
integer <int64>
Example: "1704067200"

Unix timestamp when the rate limit window resets

Response Schema: application/json
required
ASNInfo (object) or ASNInfoWithPrefixes (object)
required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "asn": 15169,
    • "name": "Google LLC",
    • "country": "US",
    • "rir": "ARIN",
    • "allocation_date": "2000-03-30",
    • "reputation": {
      }
    },
  • "meta": {
    • "request_id": "550e8400-e29b-41d4-a716-446655440000",
    • "processing_time_ms": 5,
    • "cache_status": "HIT",
    • "dataset_version": 1
    }
}

Statistics

API usage and dataset statistics

API statistics

Retrieve API cache statistics and dataset information including cache size, dataset version, and feature availability.

Authorizations:
ApiKeyAuth

Responses

Response Headers
X-Request-ID
string <uuid>
Example: "550e8400-e29b-41d4-a716-446655440000"

Unique identifier for the request, useful for debugging and support

Response Schema: application/json
required
object (Stats)

API and dataset statistics

required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "size": 1000,
    • "version": 1,
    • "geo_enabled": true,
    • "redis_enabled": false
    },
  • "meta": {
    • "processing_time_ms": 0,
    • "dataset_version": 1
    }
}

Dataset version

Returns the current active dataset version. This endpoint is used by edge workers to coordinate cache keys without requiring manual configuration.

Responses

Response Headers
X-Dataset-Version
integer

Dataset version number

Response Schema: application/json
required
object
required
object (Meta)

Response metadata

Response samples

Content type
application/json
{
  • "data": {
    • "version": 42
    },
  • "meta": {
    • "processing_time_ms": 0,
    • "dataset_version": 42
    }
}

Health

Service health and readiness checks

Health check

Liveness probe endpoint. Returns 200 OK if the service is running. This endpoint does not check downstream dependencies.

Responses

Response Schema: text/plain
string

Readiness check

Readiness probe endpoint. Returns 200 OK if the service is ready to accept traffic. Checks database connectivity.

Responses

Response Schema: text/plain
string

Feeds

Phase 9 Threat Feeds — bulk-downloadable, subscription-gated feeds of Tor exits, AI crawlers, VPN/proxy ranges, datacenter IPs, and trap-confirmed bad actors. Each feed is available in csv, json, plain and bind formats and is re-generated by a CronJob worker.

List available threat feeds

CX-091 — Returns the Phase 9 Threat Feeds catalog. Every registered feed is listed with its title, description, tier, license, latest row count, generated_at timestamp and per-format download URLs. The entitled flag tells the caller whether their API key's tier allows downloading the feed; premium feeds return entitled=false for free-tier keys alongside an upgrade_url in the envelope.

Authorizations:
ApiKeyAuth

Responses

Response Schema: application/json
object
user_tier
string
Enum: "free" "premium" "enterprise"
upgrade_url
string
Array of objects

Response samples

Content type
application/json
{
  • "data": {
    • "user_tier": "free",
    • "upgrade_url": "string",
    • "feeds": [
      ]
    }
}

Get feed manifest

Returns the JSON manifest for the latest snapshot of a feed, including row count, sha256 over the plain format, and the canonical file names for each format. Premium feeds require an upgraded tier.

Authorizations:
ApiKeyAuth
path Parameters
feed
required
string

Feed name (e.g. tor_exits, ai_crawlers, trap_confirmed)

Responses

Download the latest feed snapshot

Streams the latest snapshot for a feed in the requested format. The Content-Disposition header is set to attachment with a feed-date-format filename. The handler honours If-Modified-Since against the manifest's generated_at timestamp and returns 304 for unchanged snapshots. X-Feed-SHA256 and X-Feed-Row-Count response headers match the manifest.

CX-904 added four firewall-ready formats (nginx, caddy, iptables, cloudflare) that emit drop-in rule snippets for the four most common edge blocking surfaces. These formats power the public AI Crawler Firewall page at /tools/ai-firewall.

The optional brand query parameter is only valid for the ai_crawlers feed. It filters rows to a single AI vendor (e.g. gptbot, claudebot, perplexitybot) before encoding so operators can ship a per-vendor rule file. The X-Feed-Brand response header echoes the applied filter.

Authorizations:
ApiKeyAuth
path Parameters
feed
required
string
format
required
string
Enum: "csv" "json" "plain" "bind" "nginx" "caddy" "iptables" "cloudflare"
query Parameters
brand
string
Example: brand=gptbot

Filter the ai_crawlers feed to a single AI vendor (case-insensitive). Returns 400 if supplied for any other feed.

Responses

Response Headers
X-Feed-SHA256
string
X-Feed-Row-Count
integer
X-Feed-Brand
string

Echoes the brand filter when one was applied (CX-904).

Response Schema:
string

Response samples

Content type
No sample