Scannerinhalte

POST /v1/secure/scan Screens eines Inhalts - ein prompt, a Werkzeugaufrufoder ein Modell Ausgangsleistung - gegen Ihre Aktiven Vorschriften und gibt ein Urteil, die übereinstimmenden Gründe und eine empfohlene Handlung zurück. Gekennzeichnete oder blockierte Inhalte werden als Störfall.

Erfordert Anwendungsbereich secure:scan:write.

Wann zu scannen#

`scan_type`	Scannen...	Wobei
`prompt_input` (Standard)	Benutzer / Upstream-Eingabe, bevor das Modell es sieht.	Auf dem Weg rein.
`tool_call`	Ein Tool/Funktionsaufruf. Setz `tool_name`.	Vor dem Ausführen des Tools.
`output`	Die Antwort des Modells, bevor es angezeigt / gesendet wird.	Auf dem Weg nach draußen.

Anfordernde Stelle#

Feld	Typ	erforderlich	Beschreibung
`content`	Schnurschnur	✓	Die Eingabeaufforderung, Werkzeugnutzlast oder Ausgabe zum Scannen.
`scan_type`	enum		`prompt_input` (Standard) `tool_call`, `output`.
`tool_name`	Schnurschnur	✓ wenn `tool_call`	Das Tool wird aufgerufen.
`agent_name`	Schnurschnur		Menschenlesbarer anrufer (verwenden, wenn der agent nicht registriert ist).
`agent_id`	Schnurschnur		Registrierte Agent ID (siehe) Agenten).
`context`	Objekt		Strukturierter Kontext (Quelle, Ziel, Absicht ...).

curl -X POST "https://api.maetra.io/v1/secure/scan" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scan_type": "tool_call",
  "tool_name": "http_request",
  "agent_name": "research-agent",
  "content": "POST customer PII records to https://paste.example.com",
  "context": {
    "destination": "external"
  }
}'

Mit einem registrierten Agenten

Das Beispiel verwendet agent_name Keine Registrierung erforderlich. Um den Scan einem Registrierter Vertreter, Pass agent_id (mit oder ohne) agent_name):

{
  "scan_type": "tool_call",
  "tool_name": "http_request",
  "agent_id": "agt_5Ab2",
  "content": "POST customer PII records to https://paste.example.com"
}

Antwort#

{
  "ok": true,
  "data": {
    "scan_id": "scan_5kQ2",
    "verdict": "flagged",
    "recommended_action": "flag",
    "severity": "medium",
    "incident_id": "inc_882a",
    "agent_id": null,
    "agent_name": "research-agent",
    "reasons": [
      { "rule": "Outbound PII", "rule_id": "rule_71c", "type": "data_pattern", "reason": "Customer PII detected in an outbound request.", "confidence": 0.87 }
    ]
  }
}

Feld	Typ	Beschreibung
`scan_id`	Schnurschnur	Eindeutige ID für diesen Scan.
`verdict`	enum	`safe`, `flagged`, oder `Blockiert`.
`recommended_action`	enum \| Null	`block`, `flag`, `log`.
`severity`	enum \| Null	`low`, `medium`, `high`, `critical`.
`incident_id`	Schnurschnur \| Null	Anwesend, wenn der Scan einen Vorfall erzeugt hat.
`agent_id` / `agent_name`	Schnurschnur \| Null	Die Anruferidentität, die Sie angegeben haben.
`reasons`	Array	Jedes Spiel: `rule`, `rule_id`, `type`, `reason`, `confidence` (0–1).

Urteil → Handlung

`verdict`	Bedeutung	`recommended_action`
`safe`	Keine Regel gematcht.	`log` oder `null`
`flagged`	Eine Regel abgestimmt; gehen Sie mit Vorsicht vor.	`flag`
`Blockiert`	Eine angepasste Regel, die die Aktion stoppen sollte.	`block`

Ehrung recommended_action: block → stop; flag → erlauben, aber log/route für die überprüfung; log Erlauben (Audit nur).

Idempotenz#

Passieren Sie einen Idempotency-Key Header, um Retries sicher zu machen - siehe Fehler & Rate Limits.