Riferimento API

Tutto Internet, a una chiamata HTTP.

L'API di athorion è un'API REST JSON, gestita dalla Germania con scansioni dalla nostra rete a Darmstadt (AS62023). Fa tre cose: cerca nell'indice Internet non intrusivo, esegue una scansione di sicurezza on demand completa di qualsiasi target pubblico restituendo un PDF, e permette di porre domande basate sui fatti alla nostra IA di difesa (Manta per il triage rapido, Nautilus per il ragionamento approfondito). Tutte le richieste vanno via HTTPS all'URL base qui sotto.

BASEhttps://app.athorion.io/v1

Autenticazione e ambiti

Invia la tua chiave come token bearer nell'header Authorization. Le chiavi iniziano con ath_ e vengono mostrate una sola volta, alla creazione. I clienti creano le chiavi nella console alla voce API; le chiavi partner sono emesse dall'operatore della piattaforma.

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

Ogni chiave ha un ambito (scope) che limita gli endpoint che può chiamare. Una richiesta fuori dall'ambito restituisce 403.

AmbitoPuò raggiungere

scanSolo il flusso di scansione on demand: /v1/scans e i suoi sottopercorsi.

llmSolo l'IA di difesa (Manta e Nautilus): /v1/models, /v1/ask, /v1/ask/stream.

mcpGli strumenti del Model Context Protocol: ricerca, scansioni on demand, anteprima di esposizione e IA di difesa. Usato dal server MCP ospitato; solo piani a pagamento.

fullTutto /v1, ricerca inclusa. Il valore predefinito per le chiavi console e clienti.

Limiti di frequenza e quota

Ogni chiave ha una quota giornaliera opzionale (richieste totali per giorno di calendario, UTC) e un limite orario opzionale (richieste in una finestra mobile di 60 minuti). Entrambi sono impostati per chiave dall'operatore; se non impostati, sono illimitati. Superarne uno restituisce 429 con un error quota_exceeded o rate_limited.

HTTP/1.1 429 Too Many Requests

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

Le scansioni on demand sono inoltre soggette a un tetto per tenant valido su tutta la piattaforma e alla blocklist globale (gli intervalli privati e riservati non vengono mai scansionati).

Errori e codici di stato

Gli errori restituiscono un body JSON con un campo detail: una stringa o un oggetto con un codice error stabile e un message leggibile.

HTTPerrorSignificato

400invalid_targetIl target non è un dominio o un IP pubblico, oppure non si risolve.

401-Chiave API mancante o non valida.

403-L'ambito della chiave non consente questo endpoint.

404-ID di scansione non trovato per questa chiave.

429quota_exceeded · rate_limitedQuota giornaliera o limite orario raggiunto.

503llm_unavailableL'IA di difesa (backend LLM) non è configurata su questa istanza.

Server MCP

Gestisci l'intera piattaforma da un agente IA tramite il Model Context Protocol. Il server ospitato su mcp.athorion.io espone la ricerca nell'indice, le scansioni on demand, i controlli di esposizione e l'IA di difesa (Manta e Nautilus) come strumenti MCP. Autenticati con una chiave con ambito mcp (creala nella console; piano Cyber Intelligence o Ecosystem). Ogni chiamata usa la tua chiave, la tua quota e il tuo budget di modello; la scansione resta non intrusiva e controllata dall'Authorization Plane.

search

Query sull'indice Internet.

scan · scan_result

Scansione non intrusiva on demand.

exposure_preview

Verifica passiva della postura del dominio.

ask · list_models

IA di difesa basata sui fatti (Manta, Nautilus).

Collega un client stdio (Claude Desktop, agenti IDE) con lo shim npx:

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

I client con supporto remoto possono collegarsi direttamente a https://mcp.athorion.io/mcp con un header Authorization: Bearer.

              GET/v1/searchscope: full
            

Cerca nell'indice

Ricerca nell'indice Tier-1 non intrusivo. I filtri di q sono port: product: cve: vuln: category: net: has_vuln: sev: più testo libero. Ordinati per numero di vulnerabilità, poi per ultimo rilevamento.

PARAMETRI

q
string

Query, ad es. port:3389 category:rdp has_vuln:true.

port
int

Filtro rapido per una singola porta.

ip
string

Filtro rapido per una rete/un IP (net:).

scan
bool

true esegue un controllo approfondito live di un singolo host non aggiornato nell'indice.

limit
int · 1-1000

Risultati per pagina. Predefinito 100.

offset
int

Offset per la paginazione.

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

RISPOSTAesempio

{
  "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
            

Avvia una scansione di sicurezza

Mette in coda una scansione Tier-2 completa e non intrusiva di qualsiasi dominio o IP pubblico (porte, TLS, banner HTTP, CVE basate sulla versione). Nessuna prova di proprietà richiesta. Restituisce un id di job da interrogare. Una webhook_url opzionale riceve un POST al termine della scansione.

PARAMETRI

target
body · obbligatorio

Dominio o IPv4 pubblico.

webhook_url
body

URL http(s) pubblico chiamato al termine della scansione (sostituisce il valore predefinito della chiave).

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

RISPOSTAesempio

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

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

Stato e risultato della scansione

Da interrogare dopo l'avvio di una scansione. Durante l'esecuzione status è queued o running. Con done vengono compilati findings (gravità, CVE, KEV, categoria) e un pdf_url. refused/error riportano un refusal_reason.

PARAMETRI

id
path · obbligatorio

L'id della scansione restituito da POST /v1/scans.

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

RISPOSTAesempio

{
  "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
            

Scarica il report PDF

Il PDF brandizzato di una scansione completata (come pdf_url). Content-Type application/pdf. Disponibile quando status è done; prima, 404.

PARAMETRI

id
path · obbligatorio

L'id della scansione.

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

RISPOSTAesempio

%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
            

Elenca i modelli dell'IA di difesa

Il catalogo del router dell'IA di difesa: manta (triage rapido, predefinito) e nautilus (ragionamento approfondito). Scegline uno con ?model= su /v1/ask (sconosciuto o vuoto torna al predefinito). available:false significa che quell'alias non è configurato su questa istanza.

PARAMETRI

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

RISPOSTAesempio

{
  "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
            

Chiedi all'IA di difesa

Domande e risposte basate sui fatti. Il modello esegue un controllo approfondito live e non intrusivo di ogni host citato nella domanda e risponde solo in base a queste evidenze (non inventa mai risultati). Restituisce la risposta, il modello che l'ha fornita e gli host verificati.

PARAMETRI

q
body · obbligatorio

La domanda. Ogni dominio/IP citato viene verificato live.

model
body

manta (rapido) o nautilus (approfondito). Predefinito manta.

history
body

Array JSON opzionale dei turni {q, a} precedenti come contesto.

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"}'

RISPOSTAesempio

{
  "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
            

Risposta in streaming (SSE)

Variante Server-Sent-Events di /v1/ask: delta think (il ragionamento del modello), poi delta answer (il contenuto), poi un evento done. Stessa base fattuale e stessi modelli.

PARAMETRI

q
string · obbligatorio

La domanda.

model
string

manta o nautilus.

h
string

Array JSON opzionale della cronologia.

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

RISPOSTAesempio

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
            

Chat compatibile con OpenAI

Sostituto diretto per l'SDK OpenAI e client agente come Crush, Cursor o Continue: URL base https://app.athorion.io/v1, la tua chiave come API key. Supporta stream, tools (le chiamate tornano come veri tool_calls) e la modalità JSON. A differenza di /v1/ask niente scansione live - il contesto lo fornisci tu.

PARAMETRI

model
body · obbligatorio

nautilus (ragiona prima) o manta (risponde subito); anche full / flash funzionano, un nome sconosciuto restituisce 400.

messages
body · obbligatorio

Messaggi di chat OpenAI.

stream
body

true per Server-Sent Events nel formato a chunk di OpenAI.

tools
body

Strumenti funzione; le chiamate del modello tornano come tool_calls.

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."}]}'

RISPOSTAesempio

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

STRUMENTI

In arrivo

athorion CLI

Un client a riga di comando leggero sopra questa API: avvia una scansione, scarica il PDF e parla con l'IA di difesa direttamente dal tuo terminale. Legge la tua chiave da ATHORION_KEY e sceglie un modello con --model, con gli stessi alias recon / deep di /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