Referencia de la API

Todo Internet, a una llamada HTTP.

La API de athorion es una API REST JSON, operada desde Alemania con escaneos desde nuestra propia red en Darmstadt (AS62023). Hace tres cosas: buscar en el índice no intrusivo de Internet, ejecutar un escaneo de seguridad bajo demanda completo de cualquier objetivo público con un PDF como resultado, y hacer preguntas fundamentadas a nuestra IA de defensa (Manta para el triaje rápido, Nautilus para el razonamiento profundo). Todas las solicitudes van por HTTPS a la URL base de abajo.

BASEhttps://app.athorion.io/v1

Autenticación y alcances

Envíe su clave como token bearer en la cabecera Authorization. Las claves empiezan por ath_ y solo se muestran una vez, al crearlas. Los clientes crean claves en la consola, en API; las claves de socios las emite el operador de la plataforma.

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

Cada clave tiene un alcance (scope) que limita los endpoints que puede llamar. Una solicitud fuera del alcance devuelve 403.

AlcancePuede acceder a

scanSolo el flujo de escaneo bajo demanda: /v1/scans y sus subrutas.

llmSolo la IA de defensa (Manta y Nautilus): /v1/models, /v1/ask, /v1/ask/stream.

mcpLas herramientas del Model Context Protocol: búsqueda, escaneos bajo demanda, vista previa de exposición y la IA de defensa. La usa el servidor MCP alojado; solo planes de pago.

fullTodo /v1, incluida la búsqueda. El valor por defecto para claves de consola y de clientes.

Límites de tasa y cuota

Cada clave tiene una cuota diaria opcional (total de solicitudes por día natural, UTC) y un límite de tasa por hora opcional (solicitudes en una ventana móvil de 60 minutos). El operador fija ambos por clave; sin valor significa ilimitado. Superar cualquiera de los dos devuelve 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)"
  }
}

Los escaneos bajo demanda están además sujetos a un límite por tenant en toda la plataforma y a la lista de bloqueo global (los rangos privados y reservados nunca se escanean).

Errores y códigos de estado

Los errores devuelven un cuerpo JSON con un campo detail: una cadena o un objeto con un código error estable y un message legible.

HTTPerrorSignificado

400invalid_targetEl objetivo no es un dominio ni una IP pública, o no se pudo resolver.

401-Clave de API ausente o no válida.

403-El alcance de la clave no permite este endpoint.

404-ID de escaneo no encontrado para esta clave.

429quota_exceeded · rate_limitedSe alcanzó la cuota diaria o el límite de tasa por hora.

503llm_unavailableLa IA de defensa (backend LLM) no está configurada en esta instancia.

Servidor MCP

Controle toda la plataforma desde un agente de IA mediante el Model Context Protocol. El servidor alojado en mcp.athorion.io ofrece la búsqueda en el índice, los escaneos bajo demanda, las comprobaciones de exposición y la IA de defensa (Manta y Nautilus) como herramientas MCP. Autentíquese con una clave de alcance mcp (créela en la consola; plan Cyber Intelligence o Ecosystem). Cada llamada se ejecuta con su clave, su cuota y su presupuesto de modelo; el escaneo sigue siendo no intrusivo y controlado por el Authorization Plane.

search

Consulta del índice de Internet.

scan · scan_result

Escaneo no intrusivo bajo demanda.

exposure_preview

Comprobación pasiva de la postura del dominio.

ask · list_models

IA de defensa fundamentada (Manta, Nautilus).

Conecte un cliente stdio (Claude Desktop, agentes de IDE) con el shim de npx:

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

Los clientes con soporte remoto pueden conectarse directamente a https://mcp.athorion.io/mcp con una cabecera Authorization: Bearer.

              GET/v1/searchscope: full
            

Buscar en el índice

Búsqueda en el índice Tier-1 no intrusivo. Los filtros de q son port: product: cve: vuln: category: net: has_vuln: sev: más texto libre. Ordenado por número de vulnerabilidades y luego por última detección.

PARÁMETROS

q
string

Consulta, p. ej. port:3389 category:rdp has_vuln:true.

port
int

Filtro rápido para un solo puerto.

ip
string

Filtro rápido para una red/IP (net:).

scan
bool

true ejecuta una comprobación profunda en vivo de un único host que no está actualizado en el índice.

limit
int · 1-1000

Resultados por página. Por defecto 100.

offset
int

Desplazamiento para la paginación.

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

RESPUESTAejemplo

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

Iniciar un escaneo de seguridad

Pone en cola un escaneo Tier-2 completo y no intrusivo de cualquier dominio o IP públicos (puertos, TLS, banners HTTP, CVE según versión). No se requiere prueba de propiedad. Devuelve un id de trabajo para consultar. Una webhook_url opcional recibe un POST cuando termina el escaneo.

PARÁMETROS

target
body · obligatorio

Dominio o IPv4 pública.

webhook_url
body

URL http(s) pública a la que se llama cuando termina el escaneo (sustituye el valor por defecto de la clave).

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

RESPUESTAejemplo

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

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

Obtener estado y resultado del escaneo

Consulte tras iniciar un escaneo. Mientras se ejecuta, status es queued o running. Con done se rellenan findings (severidad, CVE, KEV, categoría) y una pdf_url. refused/error incluyen un refusal_reason.

PARÁMETROS

id
path · obligatorio

El id del escaneo devuelto por POST /v1/scans.

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

RESPUESTAejemplo

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

Descargar el informe PDF

El PDF con marca de un escaneo terminado (igual que pdf_url). Content-Type application/pdf. Disponible cuando status es done; antes, 404.

PARÁMETROS

id
path · obligatorio

El id del escaneo.

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

RESPUESTAejemplo

%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
            

Listar los modelos de la IA de defensa

El catálogo del enrutador de la IA de defensa: manta (triaje rápido, por defecto) y nautilus (razonamiento profundo). Elija uno con ?model= en /v1/ask (desconocido o vacío vuelve al predeterminado). available:false significa que ese alias no está configurado en esta instancia.

PARÁMETROS

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

RESPUESTAejemplo

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

Preguntar a la IA de defensa

Preguntas y respuestas fundamentadas. El modelo ejecuta una comprobación profunda en vivo y no intrusiva de cada host mencionado en la pregunta y responde solo a partir de esa evidencia (nunca inventa hallazgos). Devuelve la respuesta, el modelo que la generó y los hosts comprobados.

PARÁMETROS

q
body · obligatorio

La pregunta. Cada dominio/IP que contenga se comprueba en vivo.

model
body

manta (rápido) o nautilus (profundo). Por defecto manta.

history
body

Array JSON opcional con turnos {q, a} anteriores como contexto.

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

RESPUESTAejemplo

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

Transmitir una respuesta (SSE)

Variante Server-Sent-Events de /v1/ask: deltas think (el razonamiento del modelo), luego deltas answer (el contenido) y después un evento done. Misma base factual y mismos modelos.

PARÁMETROS

q
string · obligatorio

La pregunta.

model
string

manta o nautilus.

h
string

Array JSON opcional con el historial.

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

RESPUESTAejemplo

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 compatible con OpenAI

Sustituto directo para el SDK de OpenAI y clientes agente como Crush, Cursor o Continue: URL base https://app.athorion.io/v1, tu clave como API key. Admite stream, tools (las llamadas vuelven como tool_calls reales) y modo JSON. A diferencia de /v1/ask, sin escaneo en vivo - tú aportas el contexto.

PARÁMETROS

model
body · obligatorio

nautilus (razona primero) o manta (responde directamente); full / flash también funcionan, un nombre desconocido devuelve 400.

messages
body · obligatorio

Mensajes de chat de OpenAI.

stream
body

true para Server-Sent Events en formato de chunks de OpenAI.

tools
body

Herramientas de función; las llamadas del modelo vuelven como 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."}]}'

RESPUESTAejemplo

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

HERRAMIENTAS

Próximamente

athorion CLI

Un cliente de línea de comandos ligero sobre esta API: lance un escaneo, descargue el PDF y hable con la IA de defensa directamente desde su terminal. Lee su clave de ATHORION_KEY y elige un modelo con --model, con los mismos alias recon / deep que /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