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

Check if an IP address is currently listed on any blocklist. Optionally include listing history.

Authorizations:
ApiKeyAuth
path Parameters
ip
required
string
Example: 192.0.2.1

IPv4 or IPv6 address to check

query Parameters
history
string
Default: "false"
Enum: "true" "false"

Include listing history when set to true

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": {
      },
    • "history": [
      ]
    },
  • "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 and breakdown by type.

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": {
      }
    },
  • "meta": {
    • "processing_time_ms": 5
    }
}

Recent blocklist listings

Get the most recent active blocklist entries (up to 50). Useful for monitoring new listings.

Authorizations:
ApiKeyAuth

Responses

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

Response metadata

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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

Analyze raw email headers to extract the received chain, authentication results, and sending infrastructure details. Each hop IP is enriched with ASN, country, and threat data from LimesIndex.

Request Body schema: application/json
required
headers
required
string

Raw email headers to analyze

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

Quick public tool to check a domain's email authentication health. Returns a grade (A-F), score, and actionable recommendations. Similar to the DNS endpoint but designed as a free public tool without requiring authentication.

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.

Echo the caller's IP (with optional enrichment)

Returns the caller's public IP as seen by the edge/origin, extracted from X-Forwarded-For (first value), falling back to X-Real-IP, then the TCP remote address. 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 is rate-limited on the anonymous quota (RATE_LIMIT_ANON, default 60 req/min per IP).

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. Rate-limited on the anonymous quota (RATE_LIMIT_ANON, default 60 req/min per IP).

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