API-Übersicht

Hinweis

Die hier beschriebenen Endpunkte sind im aktuellen Workspace als lokaler Prototyp-/Operator-Pfad verfuegbar. https://api.superheld.app/ ist eine Zielarchitektur-URL — der verifizierte lokale Pfad laeuft auf http://127.0.0.1:8080.

Die Superheld API ermoeglicht die programmatische Integration von Bedrohungserkennung, Geraeteverwaltung und Alerting. Diese Seite beschreibt Endpunkte, Authentifizierung, Paginierung und Fehlerformate.

Basis-URL und Versionierung

Die aktuelle Workspace-Runtime verwendet unversionierte Endpunkte unter:

https://api.superheld.app/

• Transport: ausschließlich HTTPS. Unverschlüsselte Verbindungen werden abgelehnt.
• Aktuelle Workspace-Server-Runtime: Default-Bind ist 127.0.0.1:8080; nicht-loopback Binds erwarten TLS-Zertifikat oder einen expliziten Plaintext-Override für kontrollierte Dev-/Proxy-Setups.
• Versionierung: Die veröffentlichte Produkt-API-Versionierung befindet sich noch im Abgleich mit der Workspace-Implementierung. Die lokale Runtime nutzt derzeit kein /api/v1-Präfix.
• Datenformat: JSON (Request und Response).
• Kanonischer Vertrag: OpenAPI 3.1 Spezifikation (aktuell Draft, auf Workspace-Stand gezogen).

Authentifizierung

Alle Anfragen erfordern einen gültigen API-Schlüssel oder ein OAuth2-Token. Die aktuelle Workspace-Runtime akzeptiert API-Schlüssel per Authorization: Bearer ... oder X-API-Key:

Authorization: Bearer sh_live_abc123xyz456

X-API-Key: sh_live_abc123xyz456

Details zu API-Schlüsseln, OAuth2-Flows und Scopes: Authentifizierung und Autorisierung.

Rate Limiting

Die aktuelle Middleware arbeitet mit 120 Anfragen pro Minute. Bei Überschreitung antwortet die API mit 429 Too Many Requests. Relevante Response-Header:

Header	Beschreibung
X-RateLimit-Limit	Maximale Anfragen pro Zeitfenster
X-RateLimit-Remaining	Verbleibende Anfragen im aktuellen Zeitfenster
X-RateLimit-Reset	Unix-Timestamp, wann das Zeitfenster zurückgesetzt wird
Retry-After	Nur bei 429: Sekunden bis zum nächsten Versuch

Aktueller Workspace-Hinweis: Im Secure Mux wird Rate Limiting tenant-gebunden angewendet, sobald ein Token erfolgreich authentifiziert wurde. Außerhalb dieses Kontexts wird auf Credential-Fingerprint oder Remote-Adresse zurückgefallen.

Paginierung

Die API verwendet cursor-basierte Paginierung. Antworten mit mehreren Ergebnissen enthalten ein has_more-Feld und einen cursor-Wert für die nächste Seite:

GET /threats?cursor=abc123&limit=50

Standardwert: limit=20. Maximum: limit=100 (bzw. limit=500 für /events).

Kanonische Endpunkt-Tabelle

Die folgende Tabelle enthält alle dokumentierten Endpunkte. Endpunkte, die nur in einer einzigen Dokumentationsseite erwähnt werden, sind entsprechend markiert.

Methode	Pfad	Beschreibung	Status
GET	/devices	Registrierte Geräte abrufen	Implementiert
POST	/devices	Gerät registrieren	Implementiert
GET	/threats	Erkannte Bedrohungen auflisten (abgeleitete Entitätssicht)	Implementiert
GET	/events	Kanonischer Event-Stream (append-only, primäre SIEM-Integration)	Implementiert
POST	/events	Signiertes Device-Event einliefern	Implementiert
GET	/alerts	Abgeleitete user-visible Alerts abrufen	Implementiert
GET	/incidents	Tenant-gebundene Security-Incidents aus akzeptierten High-Severity-Alerting-Events oder High-Severity-Monitoring abrufen	Implementiert (prototypisch/intern)
GET	/incidents/{id}	Einzelnen tenant-gebundenen Security-Incident abrufen	Implementiert (prototypisch/intern)
PATCH	/incidents/{id}	Incident-Status entlang der aktuellen Lifecycle-Regeln weiterbewegen	Implementiert (prototypisch/intern)
GET	/jobs	Asynchrone Job-Records auflisten	Implementiert (prototypisch/intern)
POST	/jobs	Asynchronen Job-Record anlegen	Implementiert (prototypisch/intern)
GET	/jobs/{id}	Einzelnen Job-Record abrufen	Implementiert (prototypisch/intern)
POST	/jobs/{id}/cancel	Queued-, Running- oder Waiting-Review-Job abbrechen	Implementiert (prototypisch/intern)
POST	/jobs/{id}/review	Waiting-Review-Job freigeben, anpassen, ablehnen oder abbrechen	Implementiert (prototypisch/intern)
GET	/jobs/audit	Tenant-scoped Review-Audit-Einträge über Jobs hinweg abrufen	Implementiert (prototypisch/intern)
GET	/jobs/{id}/audit	Review-Audit-Einträge für einen Job abrufen	Implementiert (prototypisch/intern)
GET	/jobs/{id}/steps	Ausführungsschritte eines Jobs abrufen	Implementiert (prototypisch/intern)
GET	/jobs/{id}/artifacts	Artefakte eines Jobs abrufen	Implementiert (prototypisch/intern)
GET	/artifacts/{id}	Einzelnes Artefakt abrufen	Implementiert (prototypisch/intern)
GET	/traces/{id}	Einzelnen Ausführungs-Trace abrufen	Implementiert (prototypisch/intern)
GET	/traces/{id}/steps	Ausführungsschritte eines Traces abrufen	Implementiert (prototypisch/intern)
GET	/tokens	Tenant-gebundene Secure-Mux-Token-Metadaten auflisten	Implementiert (prototypisch/intern)
POST	/tokens	Tenant-gebundenes Secure-Mux-Token erzeugen	Implementiert (prototypisch/intern)
GET	/tokens/audit	Tenant-gebundene Token-Audit-Einträge über alle sichtbaren Token hinweg abrufen	Implementiert (prototypisch/intern)
GET	/tokens/{id}	Einzelnes tenant-gebundenes Secure-Mux-Token-Metadatum abrufen	Implementiert (prototypisch/intern)
GET	/tokens/{id}/audit	Audit-Einträge für ein tenant-gebundenes Secure-Mux-Token abrufen	Implementiert (prototypisch/intern)
DELETE	/tokens/{id}	Einzelnes tenant-gebundenes Secure-Mux-Token widerrufen	Implementiert (prototypisch/intern)
POST	/scan	Inhalt zur Analyse übergeben	Implementiert
GET	/status	Schutzstatus abrufen	Implementiert
GET	/webhooks	Registrierte Webhooks abrufen	Implementiert
POST	/webhooks	Webhook registrieren	Implementiert
GET	/webhooks/dlq	Fehlgeschlagene Webhook-Zustellungen abrufen	Implementiert
POST	/webhooks/dlq	Konkreten DLQ-Eintrag oder den neuesten Eintrag eines Webhooks erneut zustellen	Implementiert
DELETE	/webhooks/dlq	Konkreten DLQ-Eintrag quittieren bzw. löschen	Implementiert
GET	/guidance	Guidance Cards abrufen	Implementiert (intern/prototypisch)

Kanonisches Integrationsmodell

/events ist der kanonische append-only Event-Stream (jede Entscheidung als unveränderliches Event). /threats ist eine abgeleitete Entitätssicht (letzter Stand pro Bedrohung, dedupliziert). Integratoren sollten /events als primären Feed nutzen.

Beispiel-Antworten

GET /threats

{
  "data": [
    {
      "threat_id": "thr_8f3a2b",
      "threat_category": "phishing",
      "confidence": 0.92,
      "severity": "high",
      "device_id": "dev_3c8a1f",
      "detected_at": "2026-03-14T09:22:17Z",
      "description": "Gefälschte Login-Seite erkannt",
      "status": "active"
    }
  ],
  "has_more": true,
  "total_count": 42
}

POST /scan

{
  "scan_id": "scn_4e7d1c",
  "status": "completed",
  "threat_detected": true,
  "threat_type": "phishing",
  "confidence": 0.97,
  "details": "Domain imitiert bekannten Finanzdienstleister. SSL-Zertifikat seit 2 Tagen aktiv."
}

Fehlerformat

Die API liefert Fehler in folgendem Format:

{
  "error": {
    "code": "error_code",
    "message": "Beschreibung des Fehlers.",
    "status": 400
  }
}

Relevante HTTP-Statuscodes:

Code	Bedeutung
400	Ungültige Anfrage (fehlende oder fehlerhafte Parameter)
413	Request-Body überschreitet das aktuelle Größenlimit
401	Authentifizierung fehlgeschlagen
403	Fehlender Scope oder unzureichende Berechtigung
404	Ressource nicht gefunden
429	Rate Limit überschritten
500	Interner Serverfehler

Multi-Tenant-Modell

Die aktuelle Workspace-Implementierung trägt tenant_id in Geräte- und Event-Payloads. Bei POST /events wird tenant_id gegen die registrierte Device-Zuordnung geprüft; sichere Scope-Prüfung erfolgt im Secure Mux.

Current workspace note: Der erste Job-Pfad ist jetzt intern nutzbar, aber bewusst begrenzt. Die Runtime unterstützt aktuell incident_triage_v1 als deterministischen Workflow mit GET /jobs, POST /jobs, GET /jobs/{id}, POST /jobs/{id}/cancel, POST /jobs/{id}/review, GET /jobs/audit, GET /jobs/{id}/audit, GET /jobs/{id}/steps, GET /jobs/{id}/artifacts, GET /artifacts/{id}, GET /traces/{id} und GET /traces/{id}/steps. POST /jobs/{id}/review akzeptiert aktuell approve, amend, reject und cancel; amend wirkt derzeit nur auf input_refs und max_runs, ungültige Review-Zustände liefern 422. Im Secure Mux akzeptiert der Review-Pfad jetzt dediziert jobs:review; jobs:write bleibt dafür als Legacy-Fallback akzeptiert. Reviewed jobs return reviewed_by when the path runs behind the secure mux, derived from the bound API token identity. Job-Review-Audits sind zusätzlich tenant-scoped über GET /jobs/audit und pro Job über GET /jobs/{id}/audit abrufbar, folgen wie die übrigen Listen dem Cursor-/Limit-Schema, unterstützen auf /jobs/audit derzeit die Filter action und reviewed_by und liefern zusätzlich strukturierte fields neben dem rohen detail. Review-Entscheidungen erscheinen zusätzlich als review_decision-Step im bestehenden Job-/Trace-Step-Pfad.

Current workspace note: Der Secure Mux enthält außerdem einen internen Token-Lifecycle-Prototyp. POST /tokens gibt den rohen Tokenwert genau einmal zurück, während GET /tokens, GET /tokens/audit, GET /tokens/{id} und GET /tokens/{id}/audit nur Metadaten bzw. Audit-Einträge liefern. Neue Tokens bleiben tenant-gebunden und dürfen nur Scopes anfordern, die der aufrufende Token bereits besitzt. In cmd/server werden nur SHA-256(token) und Metadaten im gewählten Runtime-Backend persistiert; Token-Audit-Einträge folgen demselben Runtime-Backend, nutzen Cursor-/Limit-Paginierung, unterstützen auf /tokens/audit derzeit die Filter action und token_id und liefern zusätzlich strukturierte fields neben dem rohen detail.

Integrationsmuster

Pull-Integration (Polling)

Bei der Pull-Integration fragt Ihr System die API regelmäßig nach neuen Daten ab. Beachten Sie das Rate Limit. Current workspace note: Hinter Reverse Proxies bleiben X-Forwarded-For und X-Real-IP standardmäßig unberücksichtigt. Proxy-Adressen werden erst dann als Client-Identität ausgewertet, wenn SUPERHELD_RATE_LIMIT_TRUST_PROXY=true explizit gesetzt ist.

curl -X GET "https://api.superheld.app/threats?since=2026-03-14T09:00:00Z&severity=high" \
  -H "Authorization: Bearer sh_live_abc123xyz456"

Push-Integration (Webhooks)

Bei der Push-Integration sendet Superheld Ereignisse an Ihren HTTPS-Endpunkt. Die aktuelle Workspace-Runtime konfiguriert Webhooks direkt über /webhooks:

curl -X POST https://api.superheld.app/webhooks \
  -H "Authorization: Bearer sh_live_abc123xyz456" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant-acme",
    "url": "https://mein-server.de/hooks/superheld",
    "secret": "superheld-shared-secret"
  }'

Die aktuelle Workspace-Runtime speichert das Secret serverseitig, gibt es aber in Create-/List-Responses nicht zurueck. List-Responses enthalten stattdessen zuletzt bekannte Delivery-Metadaten wie last_delivery_status, last_delivery_error, last_delivery_at und last_delivery_attempts.

Zusätzlicher Workspace-Hinweis: Webhook-Ziele muessen https:// verwenden. Loopback-, Link-Local- und private Zieladressen werden von der Runtime abgelehnt; Redirects auf solche Ziele ebenfalls.

Webhooks eignen sich für zeitkritische Sicherheitsereignisse. Polling eignet sich für regelmäßige Bestandsabgleiche. Beide Muster lassen sich kombinieren: Webhooks als primäre Quelle, Polling als Fallback.