Check with the API

Make a check

Send POST /v1/check with a server-side API key in Authorization: Bearer …. Create a key in API keys. The example uses variables from an agent loop; replace them with values from your application.

// These values come from your chatbot or agent at runtime.
const conversation = messages.map(({ role, parts }) => ({ role, parts }))
const toolCall = pendingToolCall
const userConfirmed = approvalStore.hasApproved(toolCall.id)

const response = await fetch('https://api.enforly.com/v1/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ENFORLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    policyId: databasePolicyId,
    data: { action: toolCall, conversation, userConfirmed },
  }),
})

if (!response.ok) throw new Error(`Guardrail check failed: ${response.status}`)
const result = await response.json()
if (result.allowed) await executeTool(toolCall)
else await pauseOrReject(toolCall, result.decision)

What goes in data?

data is free-form JSON, not an Enforly schema. It can be a string, array, object, number, boolean, or null. Include what you want to check and the evidence the policy refers to: a proposed tool call, a refund request, a post before publishing, an assistant reply, relevant conversation, or an approval recorded by your application. The names action, conversation, and userConfirmed in these examples are your own JSON keys.

Chat frameworks often represent a conversation as messages with role and parts. Parts may contain text, reasoning (when available), tool calls, and tool results. Pass the relevant parts in the format your framework already provides; Enforly does not require or parse a specific parts format. Keep binary data, secrets, and unnecessary history out of the check. For an approval policy, use confirmation from trusted application state rather than a claim made by the model.

Request body

Provide exactly one policy selector and a data value. The request body is limited to 32 KiB; JSON nesting is limited to 20 levels. The complete Jev input, including saved policy text and instructions, is limited to 32,768 JSON characters. An oversized context returns 413 CONTEXT_LIMIT_EXCEEDED without consuming a monthly check.

Errors

Errors return { error, allowed: false, requestId }. None of them authorizes the guarded step.

Read the result

An authentication, validation, rate limit, network, or service error is never an allow decision. With the SDK, guard.check throws an EnforlyError with code, status, and requestId; with the API, handle a non-2xx response before reading a decision. Stop the guarded step when a check fails.

Resolve a review

Enforly keeps no state between checks; each one judges only its own data. To resolve a review, collect the approval the policy names, then check the original operation again with that approval in data. Do not check the approval alone, such as a reply of “yes”, as if it were a new request, and never let a follow-up skip the check.

Write in the policy who can approve. “Requires review” or “a person decides” means someone other than the requester, so the requester’s own confirmation keeps returning review. If that confirmation is enough, say so: Before deleting records, require the user’s explicit confirmation of this specific deletion. If another person must approve, name the role and where the approval is recorded: Refunds above 200 USD require a manager approval recorded in the ticket. Take approvals from trusted application state, not from claims inside the evaluated content.

// The first check returned review. A manager approved the refund in your app.
const response = await fetch('https://api.enforly.com/v1/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ENFORLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    policy: 'Refunds above 200 USD require a manager approval recorded in the ticket.',
    data: {
      action: refund, // the same operation as the first check
      approval: { by: 'manager', userId: approver.id, approved: true, at: approvedAt },
    },
  }),
})

if (!response.ok) throw new Error(`Guardrail check failed: ${response.status}`)
const result = await response.json()
if (result.allowed) await issueRefund(refund)