Validate Scan Results

Validate scan results against ground-truth labels and compute precision, recall, and F1 metrics

POST /api/validate

curl -X POST "https://api.example.com/api/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scan_id": "abc123",
    "dataset": "ibm_aml",
    "label_column": "IsLaundering"
  }'

{
  "metrics": {
    "precision": 0.87,
    "recall": 0.92,
    "f1": 0.89,
    "true_positives": 115,
    "false_positives": 17,
    "false_negatives": 10,
    "true_negatives": 858,
    "validated_against": "IBM_AML_IsLaundering",
    "total_labeled": 1000,
    "summary": "Detected 115 true positives with 87% precision and 92% recall"
  },
  "per_rule": [
    {
      "rule_id": "AML_HIGH_RISK_COUNTRY",
      "precision": 0.85,
      "recall": 0.90,
      "f1": 0.87,
      "detected": 45
    },
    {
      "rule_id": "AML_STRUCTURING",
      "precision": 0.89,
      "recall": 0.95,
      "f1": 0.92,
      "detected": 70
    }
  ],
  "summary": "Detected 115 true positives with 87% precision and 92% recall",
  "validated_against": "IBM_AML_IsLaundering",
  "total_labeled": 1000
}

Computes accuracy metrics by comparing detected violations against ground-truth labels from a dataset. Returns precision, recall, F1 score, and per-rule breakdowns to evaluate detection performance.

Request Body

scan_id · string · required

The unique identifier of the scan to validate

dataset · string · required

The dataset name containing ground-truth labels. Supported values: ibm_aml, paysim

label_column · string · required

The column name in the dataset containing ground-truth labels.

For ibm_aml: use IsLaundering

For paysim: use isFraud

Label Format

Ground-truth labels should be boolean or binary values:

• true / 1: Indicates a positive case (e.g., fraudulent transaction, money laundering)
• false / 0: Indicates a negative case (e.g., legitimate transaction)

Response

metrics · object

Overall validation metrics

precision · number

Precision score (TP / (TP + FP))

recall · number

Recall score (TP / (TP + FN))

f1 · number

F1 score (harmonic mean of precision and recall)

true_positives · number

Number of correctly detected violations

false_positives · number

Number of incorrectly detected violations

false_negatives · number

Number of missed violations

true_negatives · number

Number of correctly identified non-violations

validated_against · string

The ground-truth label column used for validation (e.g., IBM_AML_IsLaundering, PaySim_isFraud)

total_labeled · number

Total number of labeled records in the dataset

summary · string

Human-readable summary of validation results

per_rule · array

Per-rule breakdown of validation metrics

rule_id · string

Rule identifier

precision · number

Precision for this specific rule

recall · number

Recall for this specific rule

f1 · number

F1 score for this specific rule

detected · number

Number of violations detected by this rule

summary · string

Human-readable summary of validation results

validated_against · string

The ground-truth label column name

total_labeled · number

Total number of labeled records

Error Responses

error · string

Error code: VALIDATION_ERROR, NOT_FOUND, or INTERNAL_ERROR

message · string

Human-readable error message

details · array

Validation error details (only present for VALIDATION_ERROR)

curl -X POST "https://api.example.com/api/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scan_id": "abc123",
    "dataset": "ibm_aml",
    "label_column": "IsLaundering"
  }'

{
  "metrics": {
    "precision": 0.87,
    "recall": 0.92,
    "f1": 0.89,
    "true_positives": 115,
    "false_positives": 17,
    "false_negatives": 10,
    "true_negatives": 858,
    "validated_against": "IBM_AML_IsLaundering",
    "total_labeled": 1000,
    "summary": "Detected 115 true positives with 87% precision and 92% recall"
  },
  "per_rule": [
    {
      "rule_id": "AML_HIGH_RISK_COUNTRY",
      "precision": 0.85,
      "recall": 0.90,
      "f1": 0.87,
      "detected": 45
    },
    {
      "rule_id": "AML_STRUCTURING",
      "precision": 0.89,
      "recall": 0.95,
      "f1": 0.92,
      "detected": 70
    }
  ],
  "summary": "Detected 115 true positives with 87% precision and 92% recall",
  "validated_against": "IBM_AML_IsLaundering",
  "total_labeled": 1000
}