# Scannerinhalte

`POST /v1/secure/scan` Screens eines Inhalts - ein **prompt**, a **Werkzeugaufruf**oder ein Modell **Ausgangsleistung** - gegen Ihre Aktiven [Vorschriften](https://maetra.io/de/docs/secure-api/rules) und gibt ein Urteil, die übereinstimmenden Gründe und eine empfohlene Handlung zurück. Gekennzeichnete oder blockierte Inhalte werden als [Störfall](https://maetra.io/de/docs/secure-api/incidents).

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](https://maetra.io/de/docs/agents)). |
| `context` | Objekt || Strukturierter Kontext (Quelle, Ziel, Absicht ...). |

#### cURL

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

#### JavaScript

```javascript
const res = await fetch("https://api.maetra.io/v1/secure/scan", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "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"
      }
  }),
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = await res.json();
console.log(data);
```

#### TypeScript

```typescript
const res = await fetch("https://api.maetra.io/v1/secure/scan", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "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"
      }
  }),
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = (await res.json());
```

#### Python

```python
import os, requests

res = requests.post(
    "https://api.maetra.io/v1/secure/scan",
    headers={"Authorization": f"Bearer {os.environ['MAETRA_API_KEY']}"},
    json={
        "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"
        }
    },
)
res.raise_for_status()
print(res.json())
```

#### Rust

```rust
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("MAETRA_API_KEY")?;
    let client = reqwest::Client::new();
    let res = client
        .post("https://api.maetra.io/v1/secure/scan")
        .bearer_auth(&key)
        .json(&json!({
            "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"
            }
        }))
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{data:#}");
    Ok(())
}
```

#### C++

```cpp
#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = "Authorization: Bearer " + std::string(std::getenv("MAETRA_API_KEY"));
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.maetra.io/v1/secure/scan");
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, R"({  "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"  }})");
    curl_easy_perform(curl);   // response is written to stdout by default
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}
```

#### Java

```java
import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maetra.io/v1/secure/scan"))
    .header("Authorization", "Bearer " + System.getenv("MAETRA_API_KEY"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "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"
  }
}"""))
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```


#### Mit einem registrierten Agenten

Das Beispiel verwendet `agent_name` Keine Registrierung erforderlich. Um den Scan einem [Registrierter Vertreter](https://maetra.io/de/docs/agents), Pass `agent_id` (mit oder ohne) `agent_name`):

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

### Antwort

```json
{
  "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 `blocked`. |
| `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` |
| `blocked` | 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](https://maetra.io/de/docs/getting-started/errors-and-rate-limits).