Scanning content

POST /v1/secure/scan screens a piece of content — a prompt, a tool call, or a model output — against your active rules and returns a verdict, the matched reasons, and a recommended action. Flagged or blocked content is recorded as an incident.

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).
`context`	object		Structured context (source, destination, intent…).

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

With a registered agent

The example uses agent_name — no registration needed. To attribute the scan to a registered agent, pass agent_id (with or without agent_name):

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

Response#

{
  "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.