Developer Documentation

Available Endpoints

All endpoints are available under the https://api.voightkampff.dev/ domain.

• /basic: Standard baseline check. Detects presence of signature-agent.
• /full: Advanced check. Cryptographically verifies HTTP message signatures.

Usage Patterns

1. Standard Fetch (CORS)

The preferred method for modern browsers. Supports signal timeouts.

const api_url = 'https://api.voightkampff.dev/basic';

fetch(api_url, { signal: AbortSignal.timeout(3000) })
  .then(r => r.ok ? r.json() : Promise.reject(r.status))
  .then(info => {
    // info.status: "agent" or "none"
    // info.signatureDomain: The domain of the agent (e.g. "google.com")
    console.log('[vk]', info);
  })
  .catch(err => console.warn('[vk]', err));

2. Legacy JSONP

For environments where CORS is restricted. Use the f parameter to specify your callback.

<script>
function vk_callback(info) {
    console.log('[vk] Received:', info.status, info.signatureDomain);
}

(function() {
    const script = document.createElement('script');
    script.src = 'https://api.voightkampff.dev/full?f=vk_callback';
    document.body.appendChild(script);
})();
</script>

Result Analysis

The API returns a JSON object (or JSONP padding) with the following key fields:

• status:
  • agent-verified: (/full only) Cryptographically confirmed agent.
  • agent: (/basic only) signature-agent header detected.
  • none: Standard browser or unsigned request.
  • invalid: Signature failed verification.
• signatureDomain: The extracted domain from the agent header. Use this to identify which crawler or service is accessing your site (e.g. bing.com, openai.com).
• verified: Boolean. True if cryptographic verification succeeded.

Data Retention & Anonymization

To ensure system stability and combat adversarial "Nexus" mimicry, requests are logged under the following protocol:

• Short-term Logs: Full request metadata is retained for exactly 1 day for abuse detection and error reporting.
• Permanent Storage: After 24 hours, all data is stripped of PII and anonymized. We do NOT store:
  • IP Addresses
  • Cookies or Session Identifiers
  • Exact City/Location data
  • Raw User-Agent strings
  • Fingerprinting vectors

Anonymized logs, as seen on the [LATEST] page, contain only: Timestamp, Endpoint, Simplified User-Agent, Signature Domain, and Status.