Sgraal Documentation

Key Endpoints

All endpoints require Authorization: Bearer <api_key>

When to use which endpoint

Architecture: both endpoints use the same internal scoring engine. The differences are side-effects and input richness, not scoring depth or speed: /v1/check has no quota, no audit log, no W3C VC, no webhook, and accepts plain strings; /v1/preflight is tier-quota-counted, audit-logged, issues a W3C VC, triggers webhooks, and accepts full memory metadata for context-aware scoring.

Capabilities & guides

Deep-dive guides for specific Sgraal capabilities — each backed by a live endpoint.

Quick Start — 5 minutes

{
  "mcpServers": {
    "sgraal": {
      "command": "npx",
      "args": ["-y", "@sgraal/mcp"],
      "env": { "SGRAAL_API_KEY": "sg_demo_playground" }
    }
  }
}

pip install sgraal

from sgraal import SgraalClient
client = SgraalClient(api_key="sg_demo_playground")

result = client.preflight(
    memory_state=[{
        "id": "mem_001", "type": "tool_state",
        "timestamp_age_days": 54, "source_trust": 0.6
    }],
    action_type="irreversible",
    domain="fintech"
)
print(result.recommended_action)  # BLOCK
print(result.omega_mem_final)      # 78.4  

npm install @sgraal/mcp

const { SgraalClient } = require('@sgraal/mcp');
const client = new SgraalClient({ apiKey: 'sg_demo_playground' });

const result = await client.preflight({
  memory_state: [{ id: 'mem_001', type: 'tool_state',
    timestamp_age_days: 54, source_trust: 0.6 }],
  action_type: 'irreversible', domain: 'fintech'
});
console.log(result.recommended_action); // BLOCK

curl -X POST https://api.sgraal.com/v1/preflight \
  -H "Authorization: Bearer sg_demo_playground" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_state": [{"id": "mem_001", "type": "tool_state",
      "timestamp_age_days": 54, "source_trust": 0.6}],
    "action_type": "irreversible", "domain": "fintech"
  }'

{
  "recommended_action": "BLOCK",
  "omega_mem_final": 78.4,
  "confidence": 0.94,
  "explanation": "Memory entry mem_001 is 54 days old...",
  "repair_plan": [{ "id": "mem_001", "action": "REFRESH" }],
  "compliance_result": { "compliant": false },
  "timestamp_integrity": "VALID",
  "timestamp_flags": [],
  "identity_drift": "CLEAN",
  "identity_drift_flags": [],
  "consensus_collapse": "CLEAN",
  "consensus_collapse_flags": [],
  "collapse_ratio": 0.0,
  "attack_surface_score": 0.0,
  "attack_surface_level": "NONE",
  "active_detection_layers": [],
  "detection_feedback_applied": false,
  "provenance_chain_integrity": "CLEAN",
  "provenance_chain_flags": [],
  "chain_depth": 0,
  "naturalness_score": 0.94,
  "naturalness_level": "ORGANIC",
  "vaccination_match": false,
  "memory_locations_present": false,
  "auto_profile_selected": true
}

Core Concepts

SMRS v1.0 — Memory Risk Score

Formal 0-100 risk score computed from 10 core components (plus an optional 11th, r_importance, when PageRank authority is enabled), each then deterministically adjusted by a set of analytics modules before the verdict. Determines the preflight decision.

Decision Thresholds

10 Components

Standard body: Sgraal Governance Working Group · Version: SMRS v1.0

Full definition → api.sgraal.com/v1/standard/score-definition

Authentication

Authorization: Bearer sg_demo_playground

MCP Setup

Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible host.

{
  "mcpServers": {
    "sgraal": {
      "command": "npx",
      "args": ["-y", "@sgraal/mcp"],
      "env": { "SGRAAL_API_KEY": "sg_demo_playground" }
    }
  }
}

All SDKs

Webhooks

Sgraal sends a POST to your endpoint for every BLOCK, WARN, or ASK_USER decision.

{
  "event": "decision.block",
  "timestamp": "2026-05-24T09:12:04Z",
  "agent_id": "agent_001",
  "omega": 78.4,
  "action": "BLOCK",
  "domain": "fintech",
  "repair_plan": [{ "id": "mem_001", "action": "REFRESH" }]
}

Rate Limits

Request throughput is a flat per-key limit — it does not vary by plan. The monthly decision quota is what differs by tier.

Monthly decision quota by plan

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1711843200
Retry-After: 13  # only on 429

Compliance Profiles

Error Codes