Skip to main content
POST
Run a guardrails check

Authorizations

x-api-key
string
header
required

Project API key. Manage keys in the Zespan dashboard under project settings.

Headers

x-zespan-deadline-ms
integer

How long, in milliseconds, the caller will wait for the response. Any value outside 50 to 60000 is ignored.

Required range: 50 <= x <= 60000

Body

application/json
text
string
required
Required string length: 1 - 50000
Example:

"My card number is 4111 1111 1111 1111."

phase
enum<string>
required

Whether this is checking input (pre) or output (post).

Available options:
pre,
post
traceId
string
spanId
string
model
string
Example:

"gpt-4o"

operation
string
estimatedCost
number
inputTokens
integer
agentName
string
Maximum string length: 200
toolName
string
Maximum string length: 200
recentToolCalls
object[]
Maximum array length: 100
confirmations
object[]

Only read by a require_confirmation rule (at most 10 entries are read; a malformed entry is dropped on its own). The confirmations your own app recorded for the current tool call, sent by the SDK. Each entry has ref (an opaque id), toolName, optional argsHash, kind, outcome, optional actorRole and ageMs. Text, tool results and arguments never count as a confirmation.

Maximum array length: 50
ledger
object

Present as { "v": 1 } when the caller keeps a confirmation ledger. Without it a require_confirmation rule cannot tell "no confirmation" from "an SDK that sends none", so it reports sdk_no_ledger and blocks nothing.

Response

Guardrail evaluation result.

allowed
boolean
Example:

false

results
object[]
modifiedText
string | null
Example:

"My card number is [REDACTED]."

skippedForDeadline
string[]

Slugs of AI guardrails that were not started because the x-zespan-deadline-ms budget ran out. Present only when at least one was skipped.