ProtectCord API Documentation

GET /health

Get comprehensive system health status including D1 database, Workers performance, IPAPI connectivity, and cache performance.

Response Fields:

overall_status - Overall system health: "healthy", "degraded", or "unhealthy"
response_time_ms - Total health check execution time
uptime_seconds - Worker uptime since last restart
checks - Individual component health status

Example Request:

GET https://api.protectcord.com/health

Example Response:

{
  "overall_status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "response_time_ms": 145,
  "version": "1.0.0",
  "environment": "production",
  "checks": {
    "workers": {
      "status": "healthy",
      "response_time_ms": 12,
      "message": "Workers operating normally"
    },
    "database": {
      "status": "healthy",
      "response_time_ms": 45,
      "message": "Database operating normally",
      "details": {
        "tables_verified": 7
      }
    },
    "ipapi": {
      "status": "healthy",
      "response_time_ms": 234,
      "message": "IPAPI operating normally"
    },
    "cache": {
      "status": "healthy",
      "response_time_ms": 8,
      "message": "Cache operating normally",
      "details": {
        "total_entries": 1250,
        "recent_entries": 45,
        "freshness_percentage": 85
      }
    }
  },
  "uptime_seconds": 3600
}

GET /generate-key

Generate a new API key with basic permissions (Admin only). Supports custom name and rate limiting via query parameters.

Parameters:

key - Your admin API key (required)
name - Custom name for the key (optional)
discorduserid - Discord user ID to associate with the key (optional)
rate_limit - Custom rate limit per minute (optional, default: 32)

Response:

api_key - The new API key (save immediately!)
rate_limit_per_minute - Rate limit per minute
discord_user_id - Associated Discord user ID (if provided)
created_by - Admin who created the key

Example Request:

GET https://api.protectcord.com/generate-key?key=ADMIN_KEY&name=EXAMPLE&discorduserid=123456789012345678&rate_limit=32

Example Response:

{
  "success": true,
  "api_key": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567890abcdef12",
  "name": "EXAMPLE",
  "rate_limit_per_minute": 32,
  "is_admin": false,
  "discord_user_id": "123456789012345678",
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": "Admin",
  "message": "API key generated successfully. Please save this key as it won't be shown again."
}

⚠️ Security: Admin access required. Save your API key immediately - it cannot be retrieved later!

GET /checkip/{ip_address}

Get comprehensive information about an IP address.

Parameters:

ip_address - IPv4 or IPv6 address to check
key - Your API key (required)

Example Request:

GET https://api.protectcord.com/checkip/1.1.1.1?key=YourKey

Example Response:

{
  "ip": "1.1.1.1",
  "is_bogon": false,
  "is_mobile": false,
  "is_satellite": false,
  "is_crawler": false,
  "is_datacenter": true,
  "is_tor": false,
  "is_proxy": false,
  "is_vpn": false,
  "is_abuser": false,
  "is_whitelisted": false,
  "is_blacklisted": false,
  "company": {
    "name": "Cloudflare Inc",
    "risk_score": "0.0000 (Very Low)",
    "domain": "cloudflare.com",
    "type": "hosting",
    "network": "1.1.1.0/24"
  },
  "location": {
    "country": "Australia",
    "country_code": "AU",
    "city": "Sydney",
    "latitude": -33.8688,
    "longitude": 151.2093
  },
  "checked_by": "ProtectCord",
  "checked_at": "2024-01-15T10:30:00Z",
  "response_time_ms": 245
}

POST /admin/keys

Create a new API key (Admin only).

Request Body:

{
  "name": "My Application",
  "rate_limit_per_minute": 100,
  "is_admin": false
}

Response:

{
  "id": 123,
  "key": "generated_api_key_here",
  "name": "My Application",
  "rate_limit_per_minute": 100,
  "is_admin": false,
  "created_at": "2024-01-15T10:30:00Z"
}

GET /admin/keys

List all API keys (Admin only).

DELETE /admin/keys/{key_id}

Delete an API key (Admin only).

GET /admin/usage

Get usage statistics (Admin only).

GET /lookup/discord/{user_id}

Look up information about a Discord user.

Parameters:

user_id - Discord user ID
key - Your API key (required)

Example Request:

GET https://api.protectcord.com/lookup/discord/123456789012345678?key=YourKey

GET /lookup/minecraft/{username}

Look up information about a Minecraft player.

Parameters:

username - Minecraft username
key - Your API key (required)

Example Request:

GET https://api.protectcord.com/lookup/minecraft/Notch?key=YourKey

GET /lookup/minecraft-server/{server_ip}

Look up information about a Minecraft server.

Parameters:

server_ip - Minecraft server IP or domain
key - Your API key (required)

Example Request:

GET https://api.protectcord.com/lookup/minecraft-server/mc.hypixel.net?key=YourKey

GET /lookup/fivem/{identifier}

Look up information about a FiveM player.

Parameters:

identifier - FiveM player identifier
key - Your API key (required)

Example Request:

GET https://api.protectcord.com/lookup/fivem/steam:110000112345678?key=YourKey

POST /admin/whitelist

Add an IP address or CIDR subnet to the whitelist (Admin only). Supports both IPv4 and IPv6.

Request Body:

{
  "ip": "1.2.3.4",
  "cidr": "1.2.3.0/24",
  "reason": "Trusted partner network",
  "expires_at": "2024-12-31T23:59:59Z"
}

Note: You can specify either a single IP or a CIDR range. For CIDR, the cidr field will be used for matching.

Examples:

Single IPv4: 1.2.3.4
IPv4 CIDR: 192.168.1.0/24
IPv6: 2001:db8::1
IPv6 CIDR: 2001:db8::/32

POST /admin/blacklist

Add an IP address or CIDR subnet to the blacklist (Admin only). Supports both IPv4 and IPv6.

Request Body:

{
  "ip": "1.2.3.4",
  "cidr": "1.2.3.0/24",
  "reason": "Malicious activity detected",
  "risk_level": "HIGH",
  "expires_at": "2024-12-31T23:59:59Z"
}

Note: You can specify either a single IP or a CIDR range. For CIDR, the cidr field will be used for matching.

DELETE /admin/whitelist/{ip}

Remove an IP address from the whitelist (Admin only).

DELETE /admin/blacklist/{ip}

Remove an IP address from the blacklist (Admin only).

GET /admin/ip-reputation

List all IP reputation overrides (Admin only).

Parameters:

key - Your admin API key (required)
limit - Number of results to return (optional, default: 100)
offset - Offset for pagination (optional, default: 0)

Example Request:

GET https://api.protectcord.com/admin/ip-reputation?key=ADMIN_KEY&limit=50

Example Response:

{
  "success": true,
  "total": 25,
  "results": [
    {
      "id": 1,
      "ip_address": "192.168.1.100",
      "is_vpn": true,
      "is_proxy": false,
      "is_tor": false,
      "is_datacenter": true,
      "is_abuser": false,
      "risk_level": "MEDIUM",
      "custom_notes": "Corporate VPN endpoint",
      "added_by": "admin",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "is_active": true
    }
  ]
}

GET /admin/ip-reputation/{ip}

Get reputation override for a specific IP address (Admin only).

Parameters:

ip - IP address to check
key - Your admin API key (required)

Example Request:

GET https://api.protectcord.com/admin/ip-reputation/192.168.1.100?key=ADMIN_KEY

Example Response:

{
  "success": true,
  "ip_reputation": {
    "id": 1,
    "ip_address": "192.168.1.100",
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_abuser": false,
    "risk_level": "MEDIUM",
    "custom_notes": "Corporate VPN endpoint",
    "added_by": "admin",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "is_active": true
  }
}

POST /admin/ip-reputation/{ip}

Set or update reputation override for an IP address (Admin only).

Parameters:

ip - IP address to set reputation for
key - Your admin API key (required)

Request Body:

{
  "is_vpn": true,
  "is_proxy": false,
  "is_tor": false,
  "is_datacenter": true,
  "is_abuser": false,
  "risk_level": "MEDIUM",
  "custom_notes": "Corporate VPN endpoint identified manually"
}

Risk Levels:

UNKNOWN - Risk level not determined
LOW - Low risk, generally safe
MEDIUM - Medium risk, requires monitoring
HIGH - High risk, likely malicious
CRITICAL - Critical risk, immediate action required

Example Request:

POST https://api.protectcord.com/admin/ip-reputation/192.168.1.100?key=ADMIN_KEY

Example Response:

{
  "success": true,
  "message": "IP reputation updated successfully",
  "ip_reputation": {
    "id": 1,
    "ip_address": "192.168.1.100",
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": true,
    "is_abuser": false,
    "risk_level": "MEDIUM",
    "custom_notes": "Corporate VPN endpoint identified manually",
    "added_by": "admin",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:45:00Z",
    "is_active": true
  }
}

DELETE /admin/ip-reputation/{ip}

Remove reputation override for an IP address (Admin only).

Parameters:

ip - IP address to remove reputation override for
key - Your admin API key (required)

Example Request:

DELETE https://api.protectcord.com/admin/ip-reputation/192.168.1.100?key=ADMIN_KEY

Example Response:

{
  "success": true,
  "message": "IP reputation override removed successfully"
}

POST /admin/asn-whitelist

Add an ASN to the whitelist (Admin only). All IPs from this ASN will be automatically whitelisted.

Parameters:

key - Your admin API key (required)

Request Body:

{
  "asn": 15169,
  "reason": "Google ASN - trusted services",
  "added_by": "Admin",
  "expires_at": "2024-12-31T23:59:59Z"
}

Example Request:

POST https://api.protectcord.com/admin/asn-whitelist?key=ADMIN_KEY

Example Response:

{
  "message": "ASN added to whitelist successfully",
  "asn": 15169,
  "reason": "Google ASN - trusted services"
}

POST /admin/asn-blacklist

Add an ASN to the blacklist (Admin only). All IPs from this ASN will be automatically blocked.

Parameters:

key - Your admin API key (required)

Request Body:

{
  "asn": 12345,
  "reason": "Malicious VPN provider",
  "risk_level": "HIGH",
  "added_by": "Admin",
  "expires_at": "2024-12-31T23:59:59Z"
}

Example Request:

POST https://api.protectcord.com/admin/asn-blacklist?key=ADMIN_KEY

Example Response:

{
  "message": "ASN added to blacklist successfully",
  "asn": 12345,
  "reason": "Malicious VPN provider",
  "risk_level": "HIGH"
}

DELETE /admin/asn-whitelist/{asn}

Remove an ASN from the whitelist (Admin only).

Parameters:

asn - ASN number to remove
key - Your admin API key (required)

Example Request:

DELETE https://api.protectcord.com/admin/asn-whitelist/15169?key=ADMIN_KEY

Example Response:

{
  "message": "ASN removed from whitelist successfully",
  "asn": 15169
}

DELETE /admin/asn-blacklist/{asn}

Remove an ASN from the blacklist (Admin only).

Parameters:

asn - ASN number to remove
key - Your admin API key (required)

Example Request:

DELETE https://api.protectcord.com/admin/asn-blacklist/12345?key=ADMIN_KEY

Example Response:

{
  "message": "ASN removed from blacklist successfully",
  "asn": 12345
}

POST /admin/blacklist

Add an IP address to the blacklist (Admin only).

Request Body:

{
  "ip": "1.2.3.4",
  "cidr": "1.2.3.0/24",
  "reason": "Malicious activity detected",
  "risk_level": "HIGH",
  "expires_at": "2024-12-31T23:59:59Z"
}

DELETE /admin/whitelist/{ip}

Remove an IP address from the whitelist (Admin only).

DELETE /admin/blacklist/{ip}

Remove an IP address from the blacklist (Admin only).

🧪 Interactive Demo

Test the API endpoints with live examples. The demo uses a rate-limited trial key (1 request/minute).

Try It Now:

Click the button above to test the API...

Note: For IP lookups and other protected endpoints, contact an administrator to generate an API key.

🛡️ ProtectCord API Documentation

Authentication

Rate Limiting

Endpoints

GET /health

Response Fields:

Example Request:

Example Response:

GET /generate-key

Parameters:

Response:

Example Request:

Example Response:

GET /checkip/{ip_address}

Parameters:

Example Request:

Example Response:

POST /admin/keys

Request Body:

Response:

GET /admin/keys

DELETE /admin/keys/{key_id}

GET /admin/usage

GET /lookup/discord/{user_id}

Parameters:

Example Request:

GET /lookup/minecraft/{username}

Parameters:

Example Request:

GET /lookup/minecraft-server/{server_ip}

Parameters:

Example Request:

GET /lookup/fivem/{identifier}

Parameters:

Example Request:

POST /admin/whitelist

Request Body:

Examples:

POST /admin/blacklist

Request Body:

DELETE /admin/whitelist/{ip}

DELETE /admin/blacklist/{ip}

🔍 IP Reputation Management

GET /admin/ip-reputation

Parameters:

Example Request:

Example Response:

GET /admin/ip-reputation/{ip}

Parameters:

Example Request:

Example Response:

POST /admin/ip-reputation/{ip}

Parameters:

Request Body:

Risk Levels:

Example Request:

Example Response:

DELETE /admin/ip-reputation/{ip}

Parameters:

Example Request:

Example Response:

🌐 ASN Management

POST /admin/asn-whitelist

Parameters:

Request Body:

Example Request:

Example Response:

POST /admin/asn-blacklist

Parameters:

Request Body:

Example Request:

Example Response:

DELETE /admin/asn-whitelist/{asn}

Parameters:

Example Request:

Example Response:

DELETE /admin/asn-blacklist/{asn}

Parameters:

Example Request:

Example Response: