CandycornDB API Documentation

Introduction

Welcome to the CandycornDB API documentation. This API lets you programmatically query our real-time database of high-risk IP addresses and associated metadata. Our data includes: Tor exit nodes, IPs from high-risk ASNs, known proxies, VPNs, and suspicious network sources. To get started, you’ll need an API key, which you can generate from your dashboard.

Note: Every request must include your API key in the X-API-Key header. Keep it private — do not expose it in public code.

Authentication

Include your API key in the X-API-Key header on every request.

X-API-Key: your_api_key_here

If your request is missing or uses an invalid key, the API will return a 401 Unauthorized response.

Endpoints

Get IP Data

GET /api/public/data

Returns a paginated list of high-risk IP addresses and their associated metadata.

Query Parameters:

Parameter	Type	Default	Description
page	Integer	1	Page number for pagination
limit	Integer	10	Number of results per page (max 100)
source	String	All	Filter by source (e.g., "Tor", "ASN")

Example Response:

{
  "data": [
    {
      "ipAddress": "192.168.1.1",
      "location": {
        "country": "US",
        "city": "New York"
      },
      "isp": "Example ISP",
      "source": "Tor",
      "sourceDetails": "Exit Node",
      "timestamp": "2023-10-31T12:00:00.000Z"
    },
    {
      "ipAddress": "10.0.0.1",
      "location": {
        "country": "RU",
        "city": "Moscow"
      },
      "isp": "High Risk Provider",
      "source": "ASN",
      "sourceDetails": "AS12389",
      "timestamp": "2023-10-31T12:00:00.000Z"
    }
    // More IP data...
  ],
  "pagination": {
    "total": 1000,
    "page": 1,
    "pages": 100
  }
}

Get Statistics

GET /api/public/stats

Returns statistics about the high-risk IP data in the database.

Example Response:

{
  "total": 1000,
  "recentCount": 150,
  "sources": {
    "Tor": 250,
    "ASN": 750
  },
  "countries": [
    {
      "_id": "RU",
      "count": 250
    },
    {
      "_id": "CN",
      "count": 150
    }
    // More countries...
  ]
}

Check IP

GET /api/public/check/:ipAddress

Check if a specific IP address is in our high-risk database.

URL Parameters:

Parameter	Type	Description
ipAddress	String	The IP address to check

Example Response (IP found):

{
  "found": true,
  "data": {
    "ipAddress": "192.168.1.1",
    "location": {
      "country": "US",
      "city": "New York"
    },
    "isp": "Example ISP",
    "source": "Tor",
    "sourceDetails": "Exit Node",
    "timestamp": "2023-10-31T12:00:00.000Z"
  }
}

Example Response (IP not found):

{
  "found": false
}

Get IP Network Relationships

GET /api/public/data/network/:ipAddress

Get network relationship information for a specific IP address, including related IPs in the same subnet or ASN.

URL Parameters:

Parameter	Type	Description
ipAddress	String	The IP address to check for network relationships

Example Response:

{
  "ipAddress": "192.168.1.1",
  "trustScore": 85,
  "networkRelationships": {
    "relatedIPs": [
      {
        "ipAddress": "192.168.1.2",
        "relationship": "same-subnet",
        "trustScore": 80
      },
      {
        "ipAddress": "192.168.1.5",
        "relationship": "same-asn",
        "trustScore": 75
      }
    ],
    "clusterID": "cluster-192-168-1-1",
    "clusterRisk": 82
  }
}

Data Sources

CandycornDB collects high-risk IP data from the following sources:

Tor Exit Nodes - IP addresses of known Tor exit nodes, which are often used for anonymous browsing.
High-Risk ASNs - IP addresses from Autonomous System Numbers known for hosting malicious content or having minimal abuse controls, including:
- Bulletproof hosting providers (WorldStream, QUASINETWORKS/ECATEL, M247, etc.)
- ASNs frequently associated with malware command and control servers
- Networks with minimal abuse controls
Geographic Hotspots - IP addresses from regions frequently associated with cyber threats.

Each IP in our database includes metadata about its source, allowing you to filter and prioritize based on your specific security needs.

Rate Limiting

API requests are rate limited to protect our services. Each API key has a default limit of 100 requests per day. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Note: If you need a higher rate limit for your application, please upgrade your account.

Code Examples

JavaScript (Fetch API)

const apiKey = 'your_api_key_here';

fetch('https://your-candycorndb-url.com/api/public/data?page=1&limit=10&source=Tor', {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey
  }
})
.then(response => {
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.json();
})
.then(data => {
  console.log('High-risk IP data:', data);
})
.catch(error => {
  console.error('Error fetching data:', error);
});

Python (Requests)

import requests

api_key = 'your_api_key_here'
url = 'https://your-candycorndb-url.com/api/public/data'

headers = {
    'X-API-Key': api_key
}

params = {
    'page': 1,
    'limit': 10,
    'source': 'ASN'
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print('High-risk IP data:', data)
else:
    print(f'Error: {response.status_code}')
    print(response.text)

cURL

curl -X GET 'https://candycorndb.com/api/public/data?page=1&limit=10' \
  -H 'X-API-Key: your_api_key_here'

Support

If you have any questions or need help with the API, please contact the administrator.