API Reference

API Reference / Référence API

The FastAPI backend serves everything on 127.0.0.1:8000 (configurable via SNITCH_BIND/SNITCH_PORT). Every endpoint requires the per-launch token — send it as X-Snitch-Token: <TOKEN> header or ?token=<TOKEN> query param. The WebSocket accepts ?token=<TOKEN>.

L'API FastAPI écoute sur 127.0.0.1:8000. Chaque endpoint exige le jeton de lancement — en-tête X-Snitch-Token ou paramètre ?token=.

REST endpoints

Traffic & topology / Trafic & topologie

Method	Path	Description
GET	/graph	Current graph snapshot — nodes (hosts/processes) and edges with volumes / instantané du graphe — nœuds et liens avec volumes
GET	/devices	Passively discovered LAN devices (ARP table, mDNS/NetBIOS names) / appareils LAN découverts passivement
GET	/timeline	Sliding-window timeline aggregates (15/30/60 min) / agrégats de la fenêtre glissante
GET	/alerts	Recent anomaly alerts / alertes d'anomalies récentes
GET	/media	Microphone/camera usage state (Win/Linux; supported:false on macOS) / état micro/caméra

History / Historique

Method	Path	Description
GET	/history/host/{ip}	Per-minute byte/packet aggregates for a host / agrégats par minute pour un hôte
GET	/history/process/{name}	Same per process name / idem par nom de processus
GET	/history/top_processes	Top processes by volume / processus les plus consommateurs

Capture control / Contrôle de la capture

Method	Path	Description
GET	/capture/status	Capture state, interface, counters / état de la capture
POST	/capture/start	Start capture / démarrer la capture
POST	/capture/stop	Stop capture / arrêter la capture
POST	/capture/ports	Set port filters / filtres de ports
POST	/capture/processes	Excluded processes / processus exclus
POST	/capture/whitelist	IP whitelist (no alerts) / whitelist IP (pas d'alertes)

Alerts suppression / Suppression d'alertes

Method	Path	Description
GET	/alerts/ignore	List suppression rules / lister les règles
POST	/alerts/ignore	Add rule — body {"type": ..., "ip": ...} / ajouter une règle
DELETE	/alerts/ignore	Remove a rule / supprimer une règle

Settings & system / Réglages & système

Method	Path	Description
GET / POST	/settings	Read/update settings (language, retention_hours, filters) / lire/modifier les réglages
GET	/diagnostics	Runtime snapshot, no secrets — attach to bug reports / instantané sans secrets
GET	/geo/status	GeoIP database status / état de la base GeoIP
POST	/geo/download	Download fresh DB-IP Lite — the only outbound call, requires the consent flag / le seul appel sortant
POST	/shutdown	Graceful shutdown / arrêt propre

WebSocket — /ws?token=<TOKEN>

The UI consumes one WS stream. Messages are JSON with a type field:

type	Payload	Cadence
init	Full snapshot (graph, settings, capture state)	On connect / à la connexion
batch	New/updated nodes+edges, traffic counters, alerts	~every 250 ms / toutes les ~250 ms
node_update	Single node update (geo resolved, etc.)	As needed / à la demande
nodes_removed	Pruned node ids / nœuds purgés
alert	New anomaly alert / nouvelle alerte
device_update	LAN device seen/changed / appareil LAN vu/modifié
media	Mic/camera state change / changement micro/caméra
capture_status	Capture started/stopped/interface changed / état de la capture

Examples / Exemples

TOKEN=$(cat data/api_token.txt)

# Graph snapshot / instantané du graphe
curl -H "X-Snitch-Token: $TOKEN" http://127.0.0.1:8000/graph

# Top processes / top des processus
curl -H "X-Snitch-Token: $TOKEN" http://127.0.0.1:8000/history/top_processes

# Ignore alerts for a host / ignorer les alertes d'un hôte
curl -X POST -H "X-Snitch-Token: $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"NEW_HOST","ip":"192.168.1.50"}' \
  http://127.0.0.1:8000/alerts/ignore