Analyse du contenu

POST /v1/secure/scan d'écrans un morceau de contenu — a prompt, une appel d'outil, ou un modèle sortie — contre votre actif règles et renvoie un verdict, les raisons correspondantes, et une action recommandée. Le contenu flaggué ou bloqué est enregistré comme un incident.

Nécessite une portée secure:scan:write.

Quand analyser#

`scan_type`	Scanner...	où
`prompt_input` (par défaut)	Entrée utilisateur/en amont avant que le modèle ne le voie.	En chemin.
`tool_call`	Un appel d'outil/fonction. Jeu `tool_name`.	Avant d'exécuter l'outil.
`output`	La réponse du modèle avant qu'il ne soit montré/envoyé.	En chemin.

Organisme de demande#

Champ	Type	Requis	Désignation des marchandises
`content`	chaîne de caractères	✓	L'invite, la charge utile de l'outil ou la sortie à analyser.
`scan_type`	enum		`prompt_input` (par défaut), `tool_call`, `output`.
`tool_name`	chaîne de caractères	✓ si `tool_call`	L'outil qui s'appelle.
`agent_name`	chaîne de caractères		Appelable à lecture humaine (utiliser lorsque l'agent n'est pas enregistré).
`agent_id`	chaîne de caractères		Numéro d'identification de l'agent enregistré (voir Agents).
`context`	objet		Contexte structuré (source, destination, intention...).

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

Avec un agent enregistré

L'exemple utilise agent_name — pas d'enregistrement nécessaire. Pour attribuer le scan à un agent enregistré, laissez passer agent_id (avec ou sans agent_name):

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

Réponse#

{
  "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 }
    ]
  }
}

Champ	Type	Désignation des marchandises
`scan_id`	chaîne de caractères	ID unique pour ce scan.
`verdict`	enum	`safe`, `flagged`ou `bloqué`.
`recommended_action`	enum \| null	`block`, `flag`, `log`.
`severity`	enum \| null	`low`, `medium`, `high`, `critical`.
`incident_id`	chaîne de caractères \| null	Présent quand le scan a produit un incident.
`agent_id` / `agent_name`	chaîne de caractères \| null	L'identité de l'appelant que vous avez fournie.
`reasons`	tableau	Chaque match : `rule`, `rule_id`, `type`, `reason`, `confidence` (0–1).

Verdict → action

`verdict`	Signification	`recommended_action`
`safe`	Aucune règle ne correspond.	`log` ou `null`
`flagged`	Une règle qui correspond; procéder avec prudence.	`flag`
`bloqué`	Une règle qui devrait arrêter l'action.	`block`

Honoraires recommended_action: block → arrêter; flag → permettre mais log/route pour l'examen; log → permettre (vérification seulement).

Idempotency#

Passer une Idempotency-Key l'en-tête pour rendre les relevés sûrs — voir Erreurs et limites de taux.