URL WARN API Documentation
Integrate URL checking capabilities into your applications
Contents
Introduction
The URL WARN API allows you to check if a URL is present in our blacklist or whitelist database. This can be used to enhance security features in your applications, browsers, or security tools.
The API is RESTful and returns responses in JSON format. All API requests are made via GET requests.
Base URL
https://nerd.bh/apis/warnme/api.php
Endpoints
GET Check URL
Check if a URL is present in the blacklist or whitelist.
Endpoint
GET /api.php?action=check&url={url}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
string | Yes | Must be set to check |
url |
string | Yes | The URL to check |
Response Example
{
"url": "example-malicious-site.com",
"status": "blacklisted",
"found_in": "blacklist",
"details": {
"site": "example-malicious-site.com",
"reason": "Unsafe url to visit",
"alternatives": [
{
"name": "Safe Alternative",
"url": "https://safe-alternative.com"
}
]
},
"timestamp": "2025-06-09 21:40:42"
}
GET Search
Search for sites in the blacklist or whitelist based on a query string.
Endpoint
GET /api.php?action=search&query={query}&list={list}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
string | Yes | Must be set to search |
query |
string | Yes | The search query |
list |
string | No | Which list to search: blacklist, whitelist, or both (default) |
Response Example
{
"query": "example",
"blacklist": [
{
"site": "example-malicious-site.com",
"reason": "Unsafe url to visit",
"alternatives": [...]
}
],
"whitelist": [
{
"site": "example-safe-site.com",
"reason": "Legitimate service"
}
],
"count": 2,
"timestamp": "2025-06-09 21:40:42"
}
GET Statistics
Get statistics about the blacklist and whitelist databases.
Endpoint
GET /api.php?action=stats
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action |
string | Yes | Must be set to stats |
Response Example
{
"blacklist_count": 561,
"whitelist_count": 4273,
"total_sites": 4834,
"timestamp": "2025-06-09 21:40:42"
}
Code Examples
JavaScript Example
// Check if a URL is in the blacklist or whitelist
fetch('https://nerd.bh/apis/warnme/api.php?action=check&url=example.com')
.then(response => response.json())
.then(data => {
if (data.status === 'blacklisted') {
console.log('Warning: This site is blacklisted!');
console.log('Reason:', data.details.reason);
} else if (data.status === 'whitelisted') {
console.log('This site is safe to visit.');
} else {
console.log('This site is not in our database.');
}
})
.catch(error => console.error('Error:', error));
PHP Example
// Check if a URL is in the blacklist or whitelist
$url = 'example.com';
$apiUrl = "https://nerd.bh/apis/warnme/api.php?action=check&url=" . urlencode($url);
$response = file_get_contents($apiUrl);
$data = json_decode($response, true);
if ($data['status'] === 'blacklisted') {
echo "Warning: This site is blacklisted!\n";
echo "Reason: " . $data['details']['reason'];
} elseif ($data['status'] === 'whitelisted') {
echo "This site is safe to visit.";
} else {
echo "This site is not in our database.";
}