API-Referenz

Das ganze Internet, nur einen HTTP-Aufruf entfernt.

Die athorion API ist eine JSON-REST-API, betrieben aus Deutschland mit Scans aus unserem eigenen Netz in Darmstadt (AS62023). Sie kann drei Dinge: den nicht-intrusiven Internet-Index durchsuchen, einen vollständigen On-Demand-Sicherheitsscan jedes öffentlichen Ziels ausführen und als PDF liefern, und unserer Verteidigungs-KI (Manta für schnelle Triage, Nautilus für tiefes Reasoning) faktenbasierte Fragen stellen. Alle Anfragen gehen per HTTPS an die Basis-URL unten.

BASEhttps://app.athorion.io/v1

Authentifizierung & Scopes

Senden Sie Ihren Schlüssel als Bearer-Token im Header Authorization. Schlüssel beginnen mit ath_ und werden nur einmal bei der Erstellung angezeigt. Kunden erstellen Schlüssel in der Konsole unter API; Partner-Schlüssel vergibt der Plattformbetreiber.

curl https://app.athorion.io/v1/models \
  -H "Authorization: Bearer ath_••••••••"

Jeder Schlüssel hat einen Scope, der festlegt, welche Endpunkte er aufrufen darf. Eine Anfrage außerhalb des Scopes liefert 403.

ScopeErreicht

scanNur den On-Demand-Scan - /v1/scans und seine Unterpfade.

llmNur die Verteidigungs-KI (Manta & Nautilus) - /v1/models, /v1/ask, /v1/ask/stream.

mcpDie Werkzeuge des Model Context Protocol - Suche, On-Demand-Scans, Exposure-Vorschau und die Verteidigungs-KI. Genutzt vom gehosteten MCP-Server; nur in bezahlten Tarifen.

fullGanz /v1, einschließlich Suche. Standard für Konsolen- und Kundenschlüssel.

Rate Limits & Kontingent

Jeder Schlüssel hat optional ein Tageskontingent (Anfragen pro Kalendertag, UTC) und optional ein stündliches Rate Limit (Anfragen in einem gleitenden 60-Minuten-Fenster). Beides legt der Betreiber pro Schlüssel fest; nicht gesetzt heißt unbegrenzt. Wird eines davon überschritten, antwortet die API mit 429 und dem error quota_exceeded oder rate_limited.

HTTP/1.1 429 Too Many Requests

{
  "detail": {
    "error": "rate_limited",
    "message": "hourly rate limit reached (60/hour)"
  }
}

On-Demand-Scans sind zusätzlich durch eine plattformweite Obergrenze pro Mandant und die globale Scan-Sperrliste begrenzt (private und reservierte Adressbereiche werden nie gescannt).

Fehler & Statuscodes

Fehler liefern einen JSON-Body mit einem Feld detail: einem String oder einem Objekt mit stabilem error-Code und lesbarer message.

HTTPerrorBedeutung

400invalid_targetDas Ziel ist keine Domain oder öffentliche IP oder ließ sich nicht auflösen.

401-API-Schlüssel fehlt oder ist ungültig.

403-Der Scope des Schlüssels erlaubt diesen Endpunkt nicht.

404-Scan-ID für diesen Schlüssel nicht gefunden.

429quota_exceeded · rate_limitedTageskontingent oder stündliches Rate Limit erreicht.

503llm_unavailableDie Verteidigungs-KI (LLM-Backend) ist auf dieser Instanz nicht konfiguriert.

MCP-Server

Steuern Sie die ganze Plattform aus einem KI-Agenten über das Model Context Protocol. Der gehostete Server unter mcp.athorion.io stellt Index-Suche, On-Demand-Scans, Exposure-Checks und die Verteidigungs-KI (Manta & Nautilus) als MCP-Tools bereit. Authentifizieren Sie sich mit einem Schlüssel mit dem Scope mcp (in der Konsole erstellen; Tarif Cyber Intelligence oder Ecosystem). Jeder Aufruf läuft mit Ihrem Schlüssel, Kontingent und Modellbudget - Scans bleiben nicht-intrusiv und durch die Authorization Plane abgesichert.

search

Abfrage des Internet-Index.

scan · scan_result

Nicht-intrusiver On-Demand-Scan.

exposure_preview

Passive Prüfung der Domain-Sicherheit.

ask · list_models

Faktenbasierte Verteidigungs-KI (Manta, Nautilus).

Einen stdio-Client (Claude Desktop, IDE-Agenten) über den npx-Shim anbinden:

{
  "mcpServers": {
    "athorion": {
      "command": "npx",
      "args": ["-y", "@athorion/mcp"],
      "env": { "ATHORION_API_KEY": "ath_your_mcp_key" }
    }
  }
}

Clients mit Remote-Unterstützung verbinden sich direkt mit https://mcp.athorion.io/mcp und einem Header Authorization: Bearer.

              GET/v1/searchscope: full
            

Index durchsuchen

Suche im nicht-intrusiven Tier-1-Index. Die Filter in q sind port: product: cve: vuln: category: net: has_vuln: sev: plus Freitext. Sortiert nach Anzahl der Schwachstellen, dann nach letzter Sichtung.

PARAMETER

q
string

Abfrage, z. B. port:3389 category:rdp has_vuln:true.

port
int

Kurzfilter für einen einzelnen Port.

ip
string

Kurzfilter für ein Netz oder eine IP (net:).

scan
bool

true führt einen Live-Deep-Check eines einzelnen Hosts aus, der nicht aktuell im Index ist.

limit
int · 1-1000

Ergebnisse pro Seite. Standard 100.

offset
int

Offset für die Paginierung.

curl "https://app.athorion.io/v1/search?q=port:443 category:rdp&limit=2" \
  -H "Authorization: Bearer $ATHORION_KEY"

ANTWORTBeispiel

{
  "query": { "filters": { "port": ["443"] }, "free": "" },
  "count": 2, "total": 3007, "offset": 0, "limit": 2,
  "results": [
    { "ip": "185.12.4.7", "ports": [22, 443, 3389],
      "products": ["nginx"], "cves": ["CVE-2024-6387"],
      "vulns": 1, "kev": false,
      "last_seen": "2026-10-17T06:12:09Z" }
  ],
  "on_demand": null
}

              POST/v1/scansscope: scan
            

Sicherheitsscan starten

Stellt einen vollständigen, nicht-intrusiven Tier-2-Scan einer beliebigen öffentlichen Domain oder IP in die Warteschlange (Ports, TLS, HTTP-Banner, versionsbasierte CVEs). Kein Eigentumsnachweis nötig. Liefert eine Job-ID zum Abfragen. Eine optionale webhook_url erhält einen POST, sobald der Scan fertig ist.

PARAMETER

target
body · Pflicht

Domain oder öffentliche IPv4.

webhook_url
body

Öffentliche http(s)-URL, die nach Abschluss des Scans aufgerufen wird (überschreibt den Standard des Schlüssels).

curl -X POST "https://app.athorion.io/v1/scans" \
  -H "Authorization: Bearer $ATHORION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.de"}'

ANTWORTBeispiel

{
  "id": "e3b0c442-98fc-1c14-9afb-4c8996fb9242",
  "target": "example.de",
  "status": "queued",
  "created_at": "2026-10-18T13:20:11Z"
}

              GET/v1/scans/{id}scope: scan
            

Scan-Status & Ergebnis abrufen

Nach dem Start eines Scans regelmäßig abfragen. Während der Ausführung ist status queued oder running. Bei done sind findings (Schweregrad, CVE, KEV, Kategorie) und eine pdf_url gefüllt. refused/error enthalten einen refusal_reason.

PARAMETER

id
path · Pflicht

Die Scan-ID aus POST /v1/scans.

curl "https://app.athorion.io/v1/scans/{id}" \
  -H "Authorization: Bearer $ATHORION_KEY"

ANTWORTBeispiel

{
  "id": "e3b0c442-98fc-1c14-9afb-4c8996fb9242",
  "target": "example.de",
  "status": "done",
  "created_at": "2026-10-18T13:20:11Z",
  "finished_at": "2026-10-18T13:21:02Z",
  "refusal_reason": null,
  "finding_count": 7, "kev_count": 1,
  "counts": { "high": 1, "medium": 2, "low": 4 },
  "findings": [
    { "title": "OpenSSH 8.9p1 (version-based)",
      "severity": "high", "cve": "CVE-2024-6387",
      "kev": true, "category": "service",
      "reference": "185.12.4.7:22" }
  ],
  "pdf_url": "https://app.athorion.io/v1/scans/e3b0c442-.../report.pdf"
}

              GET/v1/scans/{id}/report.pdfscope: scan
            

PDF-Report herunterladen

Das gebrandete PDF eines abgeschlossenen Scans (wie pdf_url). Content-Type application/pdf. Verfügbar, sobald status done ist; vorher 404.

PARAMETER

id
path · Pflicht

Die Scan-ID.

curl "https://app.athorion.io/v1/scans/{id}/report.pdf" \
  -H "Authorization: Bearer $ATHORION_KEY"

ANTWORTBeispiel

%PDF-1.7
%\xE2\xE3\xCF\xD3
... (binary stream)

Content-Type: application/pdf
Content-Disposition: attachment;
  filename="athorion-example.de.pdf"

              GET/v1/modelsscope: llm
            

Modelle der Verteidigungs-KI auflisten

Der Katalog des KI-Routers: manta (schnelle Triage, Standard) und nautilus (tiefes Reasoning). Auswahl mit ?model= bei /v1/ask (unbekannt oder leer fällt auf den Standard zurück). available:false heißt, dieser Alias ist auf dieser Instanz nicht konfiguriert.

PARAMETER

curl "https://app.athorion.io/v1/models" \
  -H "Authorization: Bearer $ATHORION_KEY"

ANTWORTBeispiel

{
  "default": "manta",
  "models": [
    { "id": "manta", "label": "Manta",
      "reasoning": "low", "available": true,
      "default": true },
    { "id": "nautilus", "label": "Nautilus",
      "reasoning": "high", "available": true,
      "default": false }
  ]
}

              POST/v1/askscope: llm
            

Die Verteidigungs-KI fragen

Faktenbasierte Fragen und Antworten. Das Modell führt einen nicht-intrusiven Live-Deep-Check jedes in der Frage genannten Hosts aus und antwortet nur auf Basis dieser Belege (erfindet nie Findings). Liefert die Antwort, das antwortende Modell und die geprüften Hosts.

PARAMETER

q
body · Pflicht

Die Frage. Jede darin genannte Domain/IP wird live geprüft.

model
body

manta (schnell) oder nautilus (tief). Standard manta.

history
body

Optionales JSON-Array früherer {q, a}-Runden als Kontext.

curl -X POST "https://app.athorion.io/v1/ask" \
  -H "Authorization: Bearer $ATHORION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"is mail.example.de exposed?","model":"nautilus"}'

ANTWORTBeispiel

{
  "model": "nautilus",
  "model_label": "Nautilus",
  "answer": "mail.example.de exposes SMTP on 25 and\n587 with STARTTLS; SPF and DMARC are present,\nDKIM is missing. No critical CVE on the banner.",
  "grounded_on": ["mail.example.de"]
}

              GET/v1/ask/streamscope: llm
            

Antwort streamen (SSE)

Server-Sent-Events-Variante von /v1/ask: think-Deltas (das Reasoning des Modells), dann answer-Deltas (der Inhalt), dann ein done-Event. Gleiche Faktenbasis, gleiche Modelle.

PARAMETER

q
string · Pflicht

Die Frage.

model
string

manta oder nautilus.

h
string

Optionales JSON-Array mit dem Verlauf.

curl -N "https://app.athorion.io/v1/ask/stream?q=is example.de exposed?&model=nautilus" \
  -H "Authorization: Bearer $ATHORION_KEY"

ANTWORTBeispiel

event: think
data: Running a live deep check of
  example.de (DNS, mail, TLS, ports, CVEs) ...

event: answer
data: example.de has no critical exposure.

event: done
data: {}

              POST/v1/chat/completionsscope: llm
            

OpenAI-kompatibler Chat

Direkter Ersatz für das OpenAI-SDK und Agent-Clients wie Crush, Cursor oder Continue: Basis-URL https://app.athorion.io/v1, Ihr Schlüssel als API-Key. Unterstützt stream, tools (Aufrufe kommen als echte tool_calls zurück) und JSON-Modus. Anders als /v1/ask ohne Live-Scan - den Kontext liefern Sie selbst.

PARAMETER

model
body · Pflicht

nautilus (denkt zuerst) oder manta (antwortet direkt); full / flash funktionieren auch, unbekannte Namen liefern 400.

messages
body · Pflicht

OpenAI-Chat-Nachrichten.

stream
body

true für Server-Sent Events im OpenAI-Chunk-Format.

tools
body

Funktions-Tools; die Aufrufe des Modells kommen als tool_calls zurück.

curl -X POST "https://app.athorion.io/v1/chat/completions" \
  -H "Authorization: Bearer $ATHORION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nautilus","messages":[{"role":"user","content":"Explain the risk of RDP without NLA."}]}'

ANTWORTBeispiel

{
  "model": "nautilus",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Without NLA the login screen is\nreachable before authentication ..."
    },
    "finish_reason": "stop"
  }]
}

WERKZEUGE

Demnächst

athorion CLI

Ein schlanker Kommandozeilen-Client für diese API: Scan starten, PDF abholen und mit der Verteidigungs-KI sprechen, direkt aus Ihrem Terminal. Er liest Ihren Schlüssel aus ATHORION_KEY und wählt das Modell mit --model, mit denselben Aliasen recon / deep wie /v1/ask.

pip install athorion

export ATHORION_KEY=ath_••••••••

# full non-intrusive scan of a target, wait, save the PDF
athorion scan example.de --pdf report.pdf

# ask the defence AI, grounded on a live check
athorion ask "is mail.example.de exposed?" --model deep

# pipe context in, like any unix tool
cat targets.txt | athorion scan --stdin --json