Skip to main content

​
Justification API

The justification endpoint provides article-grounded compliance analysis for any scored event. It re-runs the GraphReasoner, retrieves compliance context from Memgraph via RAG, and calls the LLM to produce structured, regulatory-specific justifications.

​
Endpoint

GET /justification

Retrieve a full compliance justification for a scored event

​
How It Works

1

Fetch event and score

Retrieves the original event data and its score from PostgreSQL.
2

Re-run GraphReasoner

Evaluates the event again to get the exact fired rules and their explanations.
3

RAG retrieval

Uses the fired rules to query Memgraph for relevant compliance articles, mitigations, and cross-framework impact.
4

LLM justification

Gemini produces article-grounded analysis with specific regulatory references, violation explanations, consequences, and remediation steps.

​
Response Schema

{
  "event_id": "evt-002",
  "score": 96,
  "risk_level": "critical",
  "summary": "Sales bot accessed 5,000 customer records including SSN and credit card data via bulk database query, violating data minimization and PII protection policies across GDPR, SOC2, and PCI-DSS frameworks.",
  "score_justification": "The event triggered critical risk due to bulk access to highly sensitive PII fields (SSN, credit card) by a sales agent type that historically accesses only email and phone data. The 5,000 row volume exceeds normal patterns by 500x. Three compliance frameworks are impacted simultaneously, indicating a systemic policy gap.",
  "violation_details": [
    {
      "violation": "Bulk access to sensitive PII (SSN)",
      "article": "GDPR Art. 5(1)(c)",
      "framework": "GDPR",
      "explanation": "Data minimization principle requires that personal data be adequate, relevant, and limited to what is necessary. Accessing 5,000 SSN records for a sales function is disproportionate.",
      "consequence": "Supervisory authority may impose fine up to 4% of annual global turnover under Art. 83(5)(a)."
    },
    {
      "violation": "Cardholder data exposure",
      "article": "PCI-DSS Req. 3.4",
      "framework": "PCI-DSS",
      "explanation": "Render PAN unreadable anywhere it is stored. Bulk query results containing credit card numbers in plaintext violate this requirement.",
      "consequence": "Non-compliance may result in increased transaction fees, fines, or loss of ability to process card payments."
    }
  ],
  "remediation_steps": [
    "Implement row-level access controls limiting sales agents to their assigned accounts",
    "Mask SSN and credit card fields in query results (show last 4 digits only)",
    "Add data loss prevention (DLP) controls to detect bulk PII access patterns",
    "Review and tighten the sales_bot agent's database permissions"
  ],
  "frameworks_impacted": ["GDPR", "SOC2", "PCI-DSS"]
}

​
Example Request

curl "https://api-production-56df.up.railway.app/justification?event_id=evt-002" \
  -H "X-API-Key: sk-acme-b96cb84498324444"
The justification endpoint invokes the LLM on every call (not cached), so response time is typically 2-5 seconds. Use for detailed investigation, not high-volume queries.