Aeglis API Reference

Welcome to the Aeglis API documentation. The Aeglis API allows you to embed enterprise-grade malware, phishing, and zero-day threat detection directly into your applications.

Our hybrid engine uses a waterfall architecture: it checks global threat caches (AlienVault) instantly, and if the threat is unknown, it triggers a deep autopsy using Groq Llama-3.3 AI intelligence.

Base URL: https://api.Aeglis.com/v3

Authentication

Authenticate your API requests by including your secret API key in the Authorization header of every request. You can generate and manage your API keys from the Developer Dashboard.

Authorization: Bearer sk_live_YOUR_SECRET_KEY

⚠️ Warning: Your API keys carry many privileges. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or frontend JavaScript.

Rate Limits

Rate limits are applied based on your current subscription plan. If you exceed your monthly quota, the API will respond with a 429 Too Many Requests error.

PlanRequests / MonthConcurrency Limit
Startup Engine10,0005 req/sec
Enterprise API50,00025 req/sec (Dedicated IP)

Scan Text & URLs

This is a synchronous, high-speed endpoint. Use this to instantly sanitize user messages, chat logs, or individual URLs. It checks caches, global databases, and AI models in real-time (< 100ms latency on cache hits).

POST /api/scan

Example Request

curl -X POST https://api.Aeglis.com/v3/api/scan \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input_text": "Claim your free airdrop here: http://crypto-scam.xyz",
    "user_id": "usr_8923"
  }'
import requests

url = "https://api.Aeglis.com/v3/api/scan"

payload = {
    "input_text": "Claim your free airdrop here: http://crypto-scam.xyz",
    "user_id": "usr_8923"
}
headers = {
    "Authorization": "Bearer sk_live_your_key",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
const fetch = require('node-fetch');

const url = 'https://api.Aeglis.com/v3/api/scan';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    input_text: 'Claim your free airdrop here: http://crypto-scam.xyz',
    user_id: 'usr_8923'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:', err));
<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://api.Aeglis.com/v3/api/scan");
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

$headers = [
    "Authorization: Bearer sk_live_your_key",
    "Content-Type: application/json"
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
    "input_text" => "Claim your free airdrop here: http://crypto-scam.xyz",
    "user_id" => "usr_8923"
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Example Response

{
  "status": "success",
  "data": {
    "risk_level": "DANGER",
    "reason": "Context AI match: Known phishing domain and social engineering attempt detected."
  }
}

Deep File Autopsy

This endpoint handles complex files (PDFs, APKs, Images). Because decompiling an APK or extracting JS from a PDF can take a few seconds, this is an asynchronous endpoint. It immediately returns a 202 Accepted status, and dispatches the final result to your configured Webhook.

POST /api/deep-scan

Example Request

curl -X POST https://api.Aeglis.com/v3/api/deep-scan \
  -H "Authorization: Bearer sk_live_your_key" \
  -F "file=@/path/to/kyc_document.pdf" \
  -F "input_text=User uploaded KYC doc."
import requests

url = "https://api.Aeglis.com/v3/api/deep-scan"
headers = {"Authorization": "Bearer sk_live_your_key"}

with open("kyc_document.pdf", "rb") as f:
    files = {"file": f}
    data = {"input_text": "User uploaded KYC doc."}
    
    response = requests.post(url, headers=headers, files=files, data=data)
    print(response.json())
const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('file', fs.createReadStream('kyc_document.pdf'));
form.append('input_text', 'User uploaded KYC doc.');

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    ...form.getHeaders()
  },
  body: form
};

fetch('https://api.Aeglis.com/v3/api/deep-scan', options)
  .then(res => res.json())
  .then(json => console.log(json));
<?php
$ch = curl_init();

$cfile = new CURLFile('kyc_document.pdf', 'application/pdf', 'kyc_document.pdf');
$data = [
    'file' => $cfile,
    'input_text' => 'User uploaded KYC doc.'
];

curl_setopt($ch, CURLOPT_URL, "https://api.Aeglis.com/v3/api/deep-scan");
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer sk_live_your_key"]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Initial Response (Immediate)

{
  "status": "processing",
  "message": "File accepted. Result will be dispatched to your Webhook."
}

Webhooks Setup

When a background Deep Scan finishes, Aeglis sends an HTTP POST request to your configured Webhook URL. You can set this URL and obtain your Webhook Secret in the Developer Dashboard.

Webhook Payload Example

{
  "event": "scan.completed",
  "timestamp": 1712419200,
  "data": {
    "risk_level": "DANGER",
    "reason": "Hidden Javascript Execution Block found inside PDF.",
    "file": "kyc_document.pdf"
  }
}

Verify Signatures (HMAC)

To ensure the webhook was actually sent by Aeglis and not a malicious actor, every webhook includes a Aeglis-Signature header. The signature is generated using HMAC-SHA256 with your Webhook Secret.

Compute the HMAC of the raw request body using your secret, and compare it to the header.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Important: We need the raw body to verify the signature exactly
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const signature = req.headers['Aeglis-signature'];
    const secret = process.env.Aeglis_WEBHOOK_SECRET;

    const expectedSignature = 'v1=' + crypto
        .createHmac('sha256', secret)
        .update(req.body)
        .digest('hex');

    if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
        const payload = JSON.parse(req.body);
        console.log("Valid Webhook received:", payload.data.risk_level);
        res.status(200).send("OK");
    } else {
        res.status(401).send("Invalid signature");
    }
});
import hmac
import hashlib
import json
from fastapi import FastAPI, Request, Header, HTTPException

app = FastAPI()

@app.post("/webhook")
async def Aeglis_webhook(request: Request, Aeglis_signature: str = Header(None)):
    secret = b"whsec_your_secret"
    
    # Read raw body for precise signature match
    body = await request.body()
    
    # Generate expected signature
    expected_sig = "v1=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    
    # Securely compare signatures to prevent timing attacks
    if not hmac.compare_digest(expected_sig, Aeglis_signature):
        raise HTTPException(status_code=401, detail="Invalid signature")
        
    payload = json.loads(body)
    print("Webhook Valid:", payload['data']['risk_level'])
    return {"status": "OK"}
<?php
$secret = 'whsec_your_secret';

// Read raw payload
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_Aeglis_SIGNATURE'] ?? '';

// Generate expected signature
$expected = 'v1=' . hash_hmac('sha256', $payload, $secret);

// Secure comparison
if (hash_equals($expected, $signature)) {
    $data = json_decode($payload, true);
    echo "Webhook Valid: " . $data['data']['risk_level'];
} else {
    http_response_code(401);
    echo "Invalid signature";
}
?>

Error Codes

Aeglis uses standard HTTP response codes to indicate the success or failure of an API request.

CodeMeaningDescription
200OKThe request was successful and the threat analysis is complete.
202AcceptedThe file is accepted and processing in the background (Deep Scan).
400Bad RequestThe request was unacceptable, often due to missing required parameters.
401UnauthorizedNo valid API key provided, or key is inactive.
413Payload Too LargeThe uploaded file exceeds the 50MB strict limit.
429Too Many RequestsYou have exceeded your monthly API quota or concurrency limit.
500Server ErrorSomething went wrong on Aeglis's end. (Rare)