Skip to main content

Securedns Hostcheck

Check hostnames against SecureDNS parental control service to determine access permissions.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Endpoints

GET /securedns_hostcheck/

Check if access to a specific hostname should be allowed, refused, or ignored based on SecureDNS parental control rules. All requests are logged for monitoring and compliance purposes.

Parameters:

Parameter Type In Required Description
hostname string query Yes The hostname/domain to check against parental control rules
client_ip string query No Client IP address for logging purposes
category string query No Content category filter to apply

Example Request:

GET /api/v1/securedns_hostcheck/?hostname=example.com&client_ip=192.168.1.100

Example Response (Allowed):

{
  "hostname": "example.com",
  "action": "A",
  "rule_id": "safe_browsing_001",
  "category": "general",
  "timestamp": "2024-01-15T10:30:00Z",
  "client_ip": "192.168.1.100"
}

Example Response (Blocked):

{
  "hostname": "blocked-site.com",
  "action": "R",
  "rule_id": "parental_control_018",
  "category": "adult_content",
  "reason": "Content blocked by parental controls",
  "timestamp": "2024-01-15T10:30:00Z",
  "client_ip": "192.168.1.100"
}

Response Fields:

Field Type Description
hostname string The checked hostname
action string Action code: "A" (Allowed), "R" (Refused), "I" (Ignored)
rule_id string ID of the matching rule
category string Content category of the hostname
reason string Explanation when access is refused
timestamp string ISO 8601 timestamp of the check
client_ip string Client IP address (if provided)
Status Description
200 Rule matched and request allowed
401 Request not authorized - invalid or missing API token
403 Request forbidden/not allowed - rule matched and blocked
404 No rule matched for the hostname

Best Practices

  • Rate Limiting: Implement client-side caching for frequently checked hostnames to reduce API calls
  • Error Handling: Handle 404 responses appropriately - they may indicate either no rules exist or content is blocked
  • Logging: Include client IP addresses when possible for better audit trails and user tracking
  • Caching Strategy: Cache allowed responses for short periods (1-5 minutes) to improve performance
  • Fallback Behavior: Define clear fallback actions when the API is unavailable (allow, block, or queue for later checking)
  • Batch Processing: For high-volume environments, consider implementing request queuing to stay within rate limits
Back to top