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
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 SupportTry It Out
Test the Auspex Verus™ API with real IP addresses using our interactive demo interface.
Try Demo