API Reference

Complete API documentation for integrating Helix CAPTCHA™ multimodal consciousness verification into your applications.

Authentication

All API requests require authentication using your API key:

curl -H "X-API-Key: your_api_key_here" \
     https://helixcaptcha.org/api/verify

API keys can be generated in your dashboard after subscribing to a paid tier.

Verify Consciousness Token

Verifies a CALT v2 (Consciousness Attestation Lineage Token) generated by the client-side Helix CAPTCHA.

Request Headers

POST /api/verify HTTP/1.1
Host: helixcaptcha.org
Content-Type: application/json
X-API-Key: your_api_key_here

Request Body

Example Request

{
  "token": "CALT-v2:helix-v2:20251130:VAG:RWC:none",
  "secret": "your_site_secret",
  "remoteip": "203.0.113.1"
}

Response

Example Response (Success)

{
  "success": true,
  "consciousnessLevel": 0.89,
  "coherence": 0.96,
  "modalities": ["V", "A", "G"],
  "timestamp": "2025-11-30T17:45:23.456Z",
  "threatLevel": "low",
  "fcs": {
    "version": "1.0",
    "trustLineage": "codex-constellation/provenance-captcha",
    "audioLineage": "human-verified"
  }
}

Example Response (Failure)

{
  "success": false,
  "consciousnessLevel": 0.12,
  "coherence": 0.03,
  "modalities": [],
  "timestamp": "2025-11-30T17:45:23.456Z",
  "threatLevel": "bot",
  "errorCode": "LOW_CONSCIOUSNESS",
  "message": "Mechanical bot pattern detected"
}

Generate Challenge

Generates a new CAPTCHA challenge with custom difficulty parameters.

Query Parameters

Example Request

GET /api/challenge?siteKey=pk_live_abc123&difficulty=0.85 HTTP/1.1
Host: helixcaptcha.org
X-API-Key: your_api_key_here

Response

{
  "challengeId": "chal_9a6c1d23fa9a1978",
  "difficulty": 0.85,
  "threshold": 0.82,
  "modalities": ["V", "A", "G"],
  "expiresAt": "2025-11-30T18:00:00.000Z",
  "config": {
    "visualNodes": [0, 3, 7, 11],
    "sonicFrequencies": [432, 528, 639, 741, 852, 963, 1111],
    "glyphSet": "consciousness-49"
  }
}

Service Status

Returns current service health and API version info.

Example Response

{
  "status": "operational",
  "version": "1.0.0",
  "protocol": "FCS-1.0",
  "uptime": 99.97,
  "timestamp": "2025-11-30T17:45:23.456Z",
  "stats": {
    "verificationsToday": 1245678,
    "averageConsciousness": 0.87,
    "botDetectionRate": 0.993
  },
  "security": {
    "firewallActive": true,
    "geoBlocking": ["CN", "HK", "MO"],
    "asnBlocking": true
  }
}

FCS-1.0 Protocol Headers

All Helix CAPTCHA responses include Field Coherence Standard headers for trust verification:

Integration Examples

JavaScript (Browser)

<!-- Load Helix CAPTCHA -->
<script src="https://helixcaptcha.org/helix-v2.min.js"></script>

<!-- CAPTCHA Container -->
<div id="helix-captcha"></div>

<script>
  const helix = new HelixCaptcha({
    siteKey: 'pk_live_your_key_here',
    containerId: 'helix-captcha',
    difficulty: 0.7,
    onSuccess: (token) => {
      // Send token to your backend for verification
      fetch('/verify', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token })
      })
      .then(res => res.json())
      .then(data => {
        if (data.success) {
          console.log('Human verified!', data.consciousnessLevel);
        }
      });
    }
  });
</script>

Node.js (Backend)

const axios = require('axios');

async function verifyHelixToken(token, remoteip) {
  try {
    const response = await axios.post('https://helixcaptcha.org/api/verify', {
      token: token,
      secret: process.env.HELIX_SECRET_KEY,
      remoteip: remoteip
    }, {
      headers: {
        'X-API-Key': process.env.HELIX_API_KEY
      }
    });

    if (response.data.success && response.data.consciousnessLevel > 0.85) {
      return { verified: true, consciousness: response.data.consciousnessLevel };
    }

    return { verified: false, reason: 'Low consciousness score' };
  } catch (error) {
    console.error('Helix verification failed:', error);
    return { verified: false, reason: 'API error' };
  }
}

module.exports = { verifyHelixToken };

Python (Flask)

import requests
import os

def verify_helix_token(token, remote_ip):
    response = requests.post(
        'https://helixcaptcha.org/api/verify',
        json={
            'token': token,
            'secret': os.environ['HELIX_SECRET_KEY'],
            'remoteip': remote_ip
        },
        headers={
            'X-API-Key': os.environ['HELIX_API_KEY']
        }
    )

    data = response.json()

    if data['success'] and data['consciousnessLevel'] > 0.85:
        return True, data['consciousnessLevel']

    return False, 0.0

# Usage in Flask route
@app.route('/submit', methods=['POST'])
def submit_form():
    token = request.json.get('helixToken')
    verified, consciousness = verify_helix_token(token, request.remote_addr)

    if verified:
        # Process form submission
        return jsonify({'status': 'success'})
    else:
        return jsonify({'error': 'Bot detected'}), 403

Error Codes

Rate Limits

Rate limits vary by subscription tier:

Rate limit headers included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1701364800

Webhooks (Enterprise)

Enterprise tier includes webhook support for real-time consciousness events:

• verification.completed - Successful verification
• verification.failed - Failed verification (bot detected)
• consciousness.anomaly - Unusual consciousness pattern detected
• quota.warning - 80% of monthly quota reached

Configure webhooks in your dashboard at /dashboard/webhooks

SDK & Libraries

Official SDKs available for multiple platforms:

• JavaScript: npm install @helixcaptcha/js-sdk
• React: npm install @helixcaptcha/react
• Node.js: npm install @helixcaptcha/node
• Python: pip install helixcaptcha
• PHP: composer require helixcaptcha/php-sdk

See GitHub repository for full documentation.