> For the complete documentation index, see [llms.txt](https://docs.maetra.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maetra.io/secure-api/scanning-content.md). # Scanning content `POST /v1/secure/scan` screens a piece of content — a **prompt**, a **tool call**, or a model **output** — against your active [rules](/secure-api/rules.md) and returns a verdict, the matched reasons, and a recommended action. Flagged or blocked content is recorded as an [incident](/secure-api/incidents.md). Requires scope `secure:scan:write`. ### When to scan | `scan_type` | Scan… | Where | | -------------------------- | --------------------------------------------- | -------------------------- | | `prompt_input` *(default)* | User/upstream input before the model sees it. | On the way in. | | `tool_call` | A tool/function call. Set `tool_name`. | Before executing the tool. | | `output` | The model's response before it's shown/sent. | On the way out. | ### Request body | Field | Type | Required | Description | | ------------ | ------ | ---------------- | ------------------------------------------------------------ | | `content` | string | ✓ | The prompt, tool payload, or output to scan. | | `scan_type` | enum | | `prompt_input` (default), `tool_call`, `output`. | | `tool_name` | string | ✓ if `tool_call` | The tool being called. | | `agent_name` | string | | Human-readable caller (use when the agent isn't registered). | | `agent_id` | string | | Registered agent ID (see [Agents](/agents.md)). | | `context` | object | | Structured context (source, destination, intent…). | {% tabs %} {% tab title="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" } }' ``` {% endtab %} {% tab title="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); ``` {% endtab %} {% tab title="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()); ``` {% endtab %} {% tab title="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()) ``` {% endtab %} {% tab title="Rust" %} ```rust use serde_json::json; #[tokio::main] async fn main() -> Result<(), Box> { 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(()) } ``` {% endtab %} {% tab title="C++" %} ```cpp #include #include #include 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; } ``` {% endtab %} {% tab title="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()); ``` {% endtab %} {% endtabs %} #### With a registered agent The example uses `agent_name` — no registration needed. To attribute the scan to a [registered agent](/agents.md), pass `agent_id` (with or without `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" } ``` ### Response ```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 } ] } } ``` | Field | Type | Description | | ------------------------- | -------------- | -------------------------------------------------------------------- | | `scan_id` | string | Unique ID for this scan. | | `verdict` | enum | `safe`, `flagged`, or `blocked`. | | `recommended_action` | enum \| null | `block`, `flag`, `log`. | | `severity` | enum \| null | `low`, `medium`, `high`, `critical`. | | `incident_id` | string \| null | Present when the scan produced an incident. | | `agent_id` / `agent_name` | string \| null | The caller identity you supplied. | | `reasons` | array | Each match: `rule`, `rule_id`, `type`, `reason`, `confidence` (0–1). | #### Verdict → action | `verdict` | Meaning | `recommended_action` | | --------- | ------------------------------------------- | -------------------- | | `safe` | No rule matched. | `log` or `null` | | `flagged` | A rule matched; proceed with caution. | `flag` | | `blocked` | A rule matched that should stop the action. | `block` | **Honor `recommended_action`:** `block` → stop; `flag` → allow but log/route for review; `log` → allow (audit only). ### Idempotency Pass an `Idempotency-Key` header to make retries safe — see [Errors & rate limits](/getting-started/errors-and-rate-limits.md).