Verdict API

Overview

The Verdict API is for customers who own and operate their own API or MCP server. Instead of routing agent traffic through the ShieldAgent proxy, your server calls POST /tenants/:tenantId/scan with the incoming request payload. ShieldAgent runs the full multi-stage security pipeline and returns a verdict — allow, block, or human_review. Your code enforces it.

The agent's traffic flow is completely unchanged. The agent talks to your server normally. Your server makes a separate HTTP call to ShieldAgent and decides whether to execute the tool.

When to Use the Verdict API

Quick Start

SDK examples have been retired. For a supported integration, use the OpenAPI reference.

Scan Request

The REST client calls POST /tenants/:tenantId/scan on the ShieldAgent API. Authenticate with a tenant API key (Bearer token).

{
  "agentId": "agent-uuid",          // OPTIONAL — omit if server cannot identify the agent
  "clientHint": "Claude Desktop",   // OPTIONAL — from MCP clientInfo.name, for best-effort matching
  "toolName": "read_file",
  "params": { "path": "/etc/passwd" },
  "include_findings": false,        // opt-in; requires verdictDetailedFindings tenant permission
  "context": {
    "transport": "mcp",             // "mcp" | "rest" | "custom"
    "sourceIp": "10.0.1.5",         // optional — used for rate limiting
    "sessionId": "sess-123"         // optional — enables excessive agency detection
  }
}

Scan Response

Default (all tenants)

{
  "action": "block",                        // "allow" | "block" | "human_review"
  "reason": "Security threat detected",     // generic — no detection detail
  "riskScore": 87,
  "auditEventId": "evt-uuid",               // audit event was written
  "reviewId": null                          // set when action is "human_review"
}

Detailed findings ((requires include_findings: true + tenant permission))

{
  "action": "block",
  "reason": "Prompt injection detected in tool arguments",
  "findings": [
    {
      "type": "injection",
      "severity": "critical",
      "detail": "Path traversal pattern detected"
    }
  ],
  "riskScore": 87,
  "auditEventId": "evt-uuid",
  "reviewId": null
}

Detailed findings are disabled by default. Without tiering, an attacker with Verdict API access could iteratively probe which scanner caught their payload and craft evasion attempts. Enable only for trusted internal tooling via the tenant settings in the ShieldAgent dashboard.

Security Checks

The Verdict API applies the same comprehensive security checks as the inline proxy. Your request is evaluated against all configured protections before returning a verdict.

• Authentication and tenant validation
• Rate limiting (per-tenant and per-agent)
• Tool access control (approved tools allowlist)
• Policy evaluation against your configured rules
• Security scanning (prompt injection, DLP, tool drift, cross-origin, excessive agency)
• Risk score evaluation
• Audit trail logging

Agent Identity

agentId is optional. The MCP protocol does not expose agent identity — clientInfo from the MCP initialize handshake identifies the client software (e.g., "Claude Desktop"), not the individual agent. Your API or MCP server may not know which specific agent is calling.

Enforcement Observability

Because your code enforces the verdict (not ShieldAgent infrastructure), the audit trail cannot automatically confirm whether a block verdict was honored. Use POST /tenants/:tenantId/verdict-confirmations to submit your own execution report; ShieldAgent does not independently verify it.

SDK examples have been retired. For a supported integration, use the OpenAPI reference.

Shared Responsibility Model

The Verdict API shifts enforcement from the inline proxy to your code. Whether your deployment blocks threats depends on your implementation; ShieldAgent documents its detection and pipeline capabilities, not the behavior of your code.

REST contract

SDK examples have been retired. For a supported integration, use the OpenAPI reference.

Related

• Architecture Overview →All deployment positions and integration patterns
• OpenAPI reference →Supported REST request and response schemas
• Risk Scoring Model →How riskScore in the verdict response is calculated
• Compliance Frameworks →EU AI Act Art. 9 and Annex IV implications for Verdict API deployments