API Documentation

Everything you need to integrate Auspex Verus™ IP classification into your application.

Quick Start

1. Get Your API Key

Sign up for an Auspex Verus™ account and generate your API key from the portal.

X-API-Key: avk_1234567890abcdef
X-API-Secret: avs_abcdefghijklmnopqrstuvwxyz1234567890

2. Make Your First Request

Send a POST request to the Auspex Verus™ API endpoint with an IP address.

curl -X POST https://api.auspex-labs.com/verus/classify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: avk_1234567890abcdef" \
  -H "X-API-Secret: avs_abcdefghijklmnopqrstuvwxyz1234567890" \
  -d '{"ipAddress": "8.8.8.8"}'

3. Handle the Response

The API returns a JSON response with classification results.

{
  "human": false,
  "certainty": 100
}

API Reference

Endpoint

POST https://api.auspex-labs.com/verus/classify

Request Headers

Header Required Description
Content-Type Yes Must be application/json
X-API-Key Yes Your API key (starts with avk_)
X-API-Secret Yes Your API secret (starts with avs_)

Request Body

Field Type Required Description
ipAddress string Yes IPv4 or IPv6 address to classify

Response Fields

Field Type Description
human boolean true if likely human user, false if likely bot/automated traffic
certainty integer Confidence score from 0-100. Higher values indicate stronger confidence.

Code Examples

Python

import requests

url = "https://api.auspex-labs.com/verus/classify"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "avk_1234567890abcdef",
    "X-API-Secret": "avs_abcdefghijklmnopqrstuvwxyz1234567890"
}
data = {"ipAddress": "8.8.8.8"}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(f"Human: {result['human']}")
print(f"Certainty: {result['certainty']}%")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type ClassifyRequest struct {
    IPAddress string `json:"ipAddress"`
}

type ClassifyResponse struct {
    Human     bool `json:"human"`
    Certainty int  `json:"certainty"`
}

func main() {
    reqBody, _ := json.Marshal(ClassifyRequest{IPAddress: "8.8.8.8"})

    req, _ := http.NewRequest("POST",
        "https://api.auspex-labs.com/verus/classify",
        bytes.NewBuffer(reqBody))

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "avk_1234567890abcdef")
    req.Header.Set("X-API-Secret", "avs_abcdefghijklmnopqrstuvwxyz1234567890")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result ClassifyResponse
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Printf("Human: %v\\nCertainty: %d%%\\n", result.Human, result.Certainty)
}

JavaScript

const classifyIP = async (ipAddress) => {
    const response = await fetch('https://api.auspex-labs.com/verus/classify', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'avk_1234567890abcdef',
            'X-API-Secret': 'avs_abcdefghijklmnopqrstuvwxyz1234567890'
        },
        body: JSON.stringify({ ipAddress })
    });

    const result = await response.json();
    console.log(`Human: ${result.human}`);
    console.log(`Certainty: ${result.certainty}%`);
    return result;
};

classifyIP('8.8.8.8');

PHP

<?php
$ch = curl_init('https://api.auspex-labs.com/verus/classify');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: avk_1234567890abcdef',
    'X-API-Secret: avs_abcdefghijklmnopqrstuvwxyz1234567890'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'ipAddress' => '8.8.8.8'
]));

$response = curl_exec($ch);
$result = json_decode($response, true);

echo "Human: " . ($result['human'] ? 'true' : 'false') . "\n";
echo "Certainty: " . $result['certainty'] . "%\n";

curl_close($ch);

Error Handling

HTTP Status Codes

Status Meaning Description
200 Success Classification completed successfully
400 Bad Request Invalid IP address format or missing required fields
401 Unauthorized Invalid or missing API credentials
429 Too Many Requests Rate limit exceeded (see rate limits below)
500 Server Error Internal server error, contact support if persists

Error Response Format

{
  "error": "Invalid IP address format",
  "statusCode": 400
}

Rate Limits & Usage

Rate Limits by Plan

Production API rate limits: These limits apply to the production Auspex Verus™ API. Exceeding your plan's monthly quota will result in 429 errors until your next billing period.

Plan Monthly Quota Rate Limit
On Demand Unlimited (pay per request) 100 requests/second
Bronze 100,000 queries/month 100 requests/second
Silver 10,000,000 queries/month 500 requests/second
Gold 100,000,000 queries/month 1,000 requests/second
Enterprise Custom Custom (negotiable)

Note: The demo website enforces a 1 request/second limit for demonstration purposes only. Production API keys have the rate limits shown above.

Rate Limit Headers

All responses include rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1698765432

Best Practices

Cache Results

Cache classification results for frequently seen IPs to reduce API calls and improve response times.

Handle Errors Gracefully

Implement retry logic with exponential backoff for transient errors (500, 503). Never retry 400 or 401 errors.

Respect Rate Limits

Monitor rate limit headers and implement client-side throttling to avoid 429 responses.

Use Certainty Scores

Don't just check human/bot - use certainty scores to implement nuanced policies (block high certainty bots, challenge medium certainty).

Secure Your Credentials

Never expose API keys in client-side code. Always make API calls from your backend server.

Monitor Usage

Track your API usage through the portal to avoid unexpected overage charges and optimize your plan.

Understanding Results

Interpreting Classifications

Human vs Bot

  • human: true - IP is likely residential, mobile, or office network (legitimate user)
  • human: false - IP is from hosting provider, datacenter, VPN, proxy, or known bot network

Certainty Levels

  • 75-100 - High confidence, strong signal (act with confidence)
  • 50-74 - Medium confidence, good signal (reasonable to act)
  • 25-49 - Low confidence, weak signal (consider additional verification)
  • 0-24 - Very low confidence, minimal signal (treat with caution)

Special Cases

  • Private IPs - RFC 1918 (10.x, 172.16.x, 192.168.x) and RFC 6598 (100.64.x) always return {human: true, certainty: 0}
  • Certainty: 0 - Unable to classify with confidence (private IP or insufficient data)

Recommended Actions

Classification Certainty Recommended Action
Bot 75-100 Block or present CAPTCHA
Bot 50-74 Challenge with CAPTCHA or additional verification
Bot 0-49 Allow with monitoring, apply rate limits
Human Any Allow with normal rate limits

Support & Resources

Need Help?

Contact our support team for integration assistance, technical questions, or account issues.

Contact Support

Try It Out

Test the Auspex Verus™ API with real IP addresses using our interactive demo interface.

Try Demo

View Pricing

Choose a plan that fits your needs with transparent, predictable pricing.

See Pricing