API Reference
https://api.netbait.orgThe Netbait API returns an abuse score for any IPv4 address. A single number between 0 and 1 that measures how malicious that address is, computed in real time from our continuously updated dataset.
Public lookups require no authentication and are available at 10 requests per second per client IP. Authenticated requests use a token for higher rate limits.
Get a token
Tokens are issued on request. Send an email to [email protected] with the following information:
| Field | Description |
|---|---|
| Rate per second | How many requests per second you need |
| Use case | What you are building and why you need the higher limit |
Requests without both pieces of information will not be processed.
Authentication
Pass your token in the Authorization header on every request
that requires it.
Authorization: Bearer nb_live_...The score endpoint is accessible without a token for public use. A token unlocks higher rate limits.
Rate limiting
Unauthenticated requests are limited to 10 per second per client IP. Authenticated tokens carry their own configured limit. Counters are per-second only. There are no per-minute or daily quotas.
Every authenticated response includes the following headers:
| Header | Description |
|---|---|
| RateLimit-Limit | Maximum requests per second for this token |
| RateLimit-Remaining | Requests remaining in the current window |
| RateLimit-Reset | Unix timestamp when the counter resets |
When the limit is exceeded, the server returns HTTP 429 with a
Retry-After header indicating how many seconds to wait.
Score an IP address
Returns the abuse score for a single IPv4 address.
No authentication required. A token increases your rate limit.
Example
curl https://api.netbait.org/v1/score/8.8.8.80.0412The response body is the raw score as a plain decimal number. No JSON envelope, no metadata. Designed to be dropped directly into a comparison without parsing.
Score values
The score measures the severity of an address's threat level, not a probability. A low score does not mean the address is safe by intent: a 0.20 may be a compromised machine whose owner has no idea it is generating malicious traffic. A 0.99 is a confirmed, deliberate bad actor. The thresholds below reflect how we use the score on our own routers, but you are free to set your own.
| Range | Meaning | Recommended action |
|---|---|---|
| 0.00 to 0.30 | Low threat level. May include compromised machines with limited known activity. | Allow |
| 0.30 to 0.65 | Moderate threat. Associated with scanning, noise or grey-area operations. | Review or throttle |
| 0.65 to 1.00 | High threat. Confirmed malicious activity, deliberate and sustained. | Block |
Our own network blocks anything above 0.30. At that threshold, 80% of inbound traffic is eliminated before touching any service.
Errors
| Status | Meaning |
|---|---|
| 400 | The address provided is not a valid IPv4 address |
| 401 | Missing or invalid token |
| 429 | Rate limit exceeded. Check Retry-After |
| 500 | Internal error on our side |
Integration pattern
Do not block incoming traffic while waiting for the API response. Query asynchronously and correlate the result after the fact. This keeps your application fast regardless of network conditions and avoids adding latency to every connection.
A practical approach: let the request through, fire the score lookup in a background thread or job, then act on the result. For most use cases (rate limiting, signup protection, logging), a few hundred milliseconds of delay between the connection and the decision has no practical impact. For hard blocking at the network edge, a local cache (see below) removes the need to wait at all.
Local cache
Querying the API on every single connection is rarely necessary and will consume your rate limit quickly. A local lookup table with expiring entries solves both problems at once.
The recommended approach is to maintain two separate lists:
| List | TTL | Rationale |
|---|---|---|
| Allowed | 6 hours | Legitimate IPs change rarely. Six hours avoids repeat queries without keeping stale entries too long. |
| Blocked | 24 hours | Hostile addresses stay hostile. A longer TTL means a repeat offender never burns your rate limit a second time that day. |
On each incoming connection, check your local table first. If the IP is there and the entry has not expired, apply the cached decision immediately without touching the API. If it is not in the table, query the API, store the result with the appropriate TTL, and apply the decision.
This pattern keeps your tables small enough to stay in memory, protects your rate limit from being exhausted by a single persistent attacker, and adds zero latency on repeat visits.