Skip to content

Tool Security API ​

The Tool Security API provides programmatic access to the Tool Security Center — tool catalog, security policies, enforcement events, compliance reports, and anomaly detection.

All endpoints require authentication and are scoped to the authenticated user's organization.

Base URL: /api/tooling

Tool Catalog ​

GET /catalog ​

Returns the full tool catalog with risk levels, data classification, and security metadata.

Query Parameters:

ParameterTypeDefaultDescription
periodstring24hTime period for usage stats: 1h, 24h, 7d, 30d

Response: ToolCatalogResponse

json
{
  "tools": [
    {
      "id": "web_search",
      "name": "Web Search",
      "risk_level": "medium",
      "data_classification": "public",
      "scan_depth": "standard",
      "data_flow": [...],
      "security_controls": [...]
    },
    {
      "id": "chat.create_canvas",
      "name": "Canvas Create",
      "risk_level": "medium",
      "data_classification": "internal",
      "scan_depth": "standard",
      "data_flow": [...],
      "security_controls": ["HTML argument validation (blocked/warned patterns)", "PII scan on HTML content", "Size limit enforcement (150KB)", "CSP-restricted iframe sandbox", "Script heartbeat watchdog"]
    }
  ],
  "total": 14
}

GET /tools/ ​

Returns detailed information for a single tool including data flow and compliance mappings.

GET /pii-stats/ ​

Returns PII detection statistics for a specific tool.

Query Parameters:

ParameterTypeDefaultDescription
periodstring24hTime period: 1h, 24h, 7d, 30d

Security Posture ​

GET /posture ​

Returns the organization's aggregate security posture score.

Query Parameters:

ParameterTypeDefaultDescription
periodstring24hTime period: 1h, 24h, 7d, 30d

Response: SecurityPosture

json
{
  "score": 82,
  "inherent_risk_score": 68,
  "tools_mitigated": 8,
  "risk_breakdown": { "low": 5, "medium": 4, "high": 2, "critical": 1 },
  "pii_stats": { "total_scanned": 1200, "total_tokenized": 890, "total_leaked": 3 },
  "policy_coverage": 0.85,
  "approval_rate": 0.92
}

Security Policies ​

GET /policies ​

Returns all configured tool security policies for the organization.

POST /policies ​

Create or update a tool security policy.

Request Body: PolicyUpdateRequest

json
{
  "tool_name": "web_search",
  "scan_depth": "deep",
  "pii_action": "tokenize",
  "max_calls_per_hour": 100,
  "blocked_entity_types": ["US_SSN", "CREDIT_CARD"],
  "approval_status": "approved"
}

DELETE /policies/ ​

Delete a tool security policy, reverting to default behavior.

Approval Workflow ​

POST /approve ​

Create or update an approval decision for a tool.

Request Body: ApprovalRequest

json
{
  "tool_name": "code_execution",
  "status": "approved",
  "expires_at": "2026-06-01T00:00:00Z",
  "notes": "Approved for engineering team"
}

Tool Chain Analysis ​

GET /chain ​

Returns tool call chain analysis for a session.

Query Parameters:

ParameterTypeDefaultDescription
session_idstringrequiredSession to analyze

Anomaly Detection ​

GET /anomalies ​

Returns detected anomalies across tool usage patterns.

Query Parameters:

ParameterTypeDefaultDescription
periodstring24hTime period: 1h, 24h, 7d, 30d

GET /recommendations ​

Returns actionable security recommendations based on current tool usage.

Compliance ​

GET /compliance/report ​

Generate a compliance evidence report for a specific regulatory framework.

Query Parameters:

ParameterTypeDefaultDescription
frameworkstringhipaaFramework: hipaa, soc2, pci_dss, gdpr, nist_800_171, iso_27001
periodstring30dTime period for evidence

Response: ComplianceReport

json
{
  "framework": "hipaa",
  "generated_at": "2026-03-14T10:00:00Z",
  "organization_id": "org_123",
  "overall_score": 92,
  "controls": [
    {
      "id": "hipaa_access_control",
      "name": "Access Control",
      "status": "met",
      "weight": 20,
      "evidence": "All 12 tools have configured access policies...",
      "remediation": ""
    }
  ]
}

POST /simulate ​

Simulate the impact of a policy change before applying it.

Request Body: SimulationRequest

json
{
  "tool_name": "web_search",
  "proposed_scan_depth": "deep",
  "proposed_pii_action": "block"
}

Supply Chain ​

GET /supply-chain ​

Returns supply chain security report for MCP servers.

GET /blast-radius/ ​

Returns blast radius analysis for a specific tool.

Chain Rules ​

GET /chain-rules ​

Returns all configured chain policy rules.

PUT /chain-rules ​

Create or update a chain policy rule.

DELETE /chain-rules/ ​

Delete a chain policy rule.

GET /chain-rules/evaluate/ ​

Evaluate chain rules against a specific session's tool call history.

Shadow Tools ​

GET /shadow-tools ​

Returns shadow tool detection report.

Query Parameters:

ParameterTypeDefaultDescription
periodstring7dTime period: 1h, 24h, 7d, 30d

Enforcement ​

GET /enforcement ​

Returns aggregate enforcement statistics.

Query Parameters:

ParameterTypeDefaultDescription
periodstring24hTime period: 1h, 24h, 7d, 30d

Response: EnforcementSummary

json
{
  "period": "24h",
  "total_calls": 1450,
  "passed": 1320,
  "tokenized": 98,
  "blocked": 12,
  "warned": 15,
  "rate_limited": 3,
  "chain_blocked": 2,
  "pii_total_caught": 234,
  "avg_scan_ms": 8.3,
  "recent_events": [...]
}

GET /enforcement/events ​

Returns a paginated list of enforcement events with optional filtering.

Query Parameters:

ParameterTypeDefaultDescription
periodstring24hTime period: 1h, 24h, 7d, 30d
actionstringnoneFilter by action: passed, tokenized, blocked, warned, rate_limited, chain_blocked
tool_namestringnoneFilter by tool name
limitinteger50Results per page (max 200)
offsetinteger0Pagination offset

Response: EnforcementEventList

json
{
  "events": [
    {
      "tool_name": "web_search",
      "action": "tokenized",
      "direction": "outbound",
      "pii_count": 3,
      "pii_types": ["PERSON", "EMAIL_ADDRESS"],
      "reason": "",
      "scan_ms": 12.5,
      "timestamp": "2026-03-14T10:00:00Z",
      "user_id": "user_abc",
      "session_id": "sess_123"
    }
  ],
  "total": 1450,
  "limit": 50,
  "offset": 0
}

SSE Event: tool_security ​

During chat streaming, a tool_security server-sent event is emitted after each tool call with enforcement metadata:

json
{
  "type": "tool_security",
  "tool_name": "web_search",
  "tool_id": "call_abc123",
  "action": "tokenized",
  "pii_detected": 3,
  "pii_types": ["PERSON", "EMAIL_ADDRESS"],
  "pii_tokenized": 3,
  "scan_ms": 12.5,
  "blocked": false,
  "block_reason": "",
  "warnings": []
}
FieldTypeDescription
actionstringpassed, tokenized, blocked, warned
pii_detectedintegerTotal PII entities detected
pii_typesstring[]Entity types found
pii_tokenizedintegerPII entities that were tokenized
scan_msnumberTotal scan duration (pre + post)
blockedbooleanWhether the tool call was blocked
block_reasonstringReason for blocking (empty if not blocked)
warningsstring[]Warning messages (e.g., policy warnings)

Feature Access ​

Tool Security Center features are gated by subscription tier:

FeatureTeamBusinessEnterprise
Tool Catalog✓✓✓
Security Policies✓✓✓
Analytics✓✓✓
Anomaly Detection✓✓
Compliance Export✓✓
Policy Simulation✓✓
Enforcement Activity Feed✓✓
Supply Chain Security✓
Blast Radius Analysis✓
Chain Rules✓
Shadow Tool Detection✓

SOC 2 Type II Certified | BAA Available | HIPAA-Ready