Sernate FireHOL Search IP API

The machine-readable OpenAPI contract is available at /openapi.json.

Compatibility Policy

Existing public response fields are treated as part of the API contract. We may add new fields, but we do not remove or rename documented fields on the current endpoints without a versioned replacement or deprecation period.

Automation should ignore unknown fields and depend only on fields documented here or in /openapi.json.

Default Search Behavior

Public search answers the practical admin question: is this IPv4 address currently listed on a fresh feed? Historical removals and stale upstream sources are hidden by default.

Setting	Default	Meaning
`current_only`	`true`	Only return hits whose `current_status` is `present`.
`include_stale`	`false`	Hide feed sources older than 366 days.

Search Endpoints

GET /search/ip

curl -fsS 'https://blocklist.sernate.com/search/ip?v=1.15.51.236'

POST /search

curl -fsS -X POST \
  -H 'Content-Type: text/plain' \
  --data '8.8.8.8,1.1.1.1' \
  'https://blocklist.sernate.com/search'

History And Stale Feeds

Use investigation mode when you intentionally want to inspect old listings, removed listings, or source feeds that have not been updated recently.

Removed listings are kept in the database and can appear with current_status: absent when current_only=false is used. If the upstream source file is stale, also use include_stale=true.

curl -fsS 'https://blocklist.sernate.com/search/ip?v=8.8.8.8&current_only=false&include_stale=true'

Stale or historical hits should not be treated as current blocking evidence without manual review.

Limits

IP version	IPv4 only
CIDR prefix range	/`16` through /`32`
Max search items	100
Max requested IPs	65536
Max returned hits	500 Large CIDR searches may return `truncated: true`. Narrow the range for a complete view.
Max POST body	16384 bytes
Rate limiting	Too many requests may return HTTP `429`. Batch related checks where possible.

Client Caching

Automation may cache /version.txt for update checks. Search results should not be cached aggressively across scheduled checks because indexed listings can change after the next API sync. Keeping results for the current check run is fine.

Use GET /search/ip for manual single IP or single CIDR lookups. Use POST /search when checking multiple IPs in one scheduled server check. Edge caching currently applies only to identical GET /search/ip requests; clients should cache their own scheduled or manual results where practical.

Important Response Fields

`current_status`	`present` or `absent` for a feed hit.
`source_file_date`	Current source date reported by the upstream feed metadata when available.
`matched_source_file_date`	Source date stored with the matched entry. This can be older than the current feed source date when the entry stayed listed across later syncs.
`feed_last_synced_at`	When this API last synced metadata for the matching list/feed.
`source_age_days`	Age of the upstream source date when it can be parsed.
`source_is_stale`	Whether the source is older than the configured freshness limit.
`first_seen`, `last_added`, `last_removed`	Timeline fields tracked by this API for a feed hit.
`matched_entry`	Original feed entry that matched the query when range-aware storage is active, for example `64.62.156.0/24`.
`match_type`	`ip` or `cidr` when range-aware storage is active.
`matched_range_start`, `matched_range_end`	Overlap between the requested IP/CIDR and the matched feed entry.