Guard API guide

Call Guard once per model call, before you send anything to the AI provider. Full schema: API reference.

Request

{
  "system_id": "cf84f936-95bc-45a4-bf98-9a1a16bf29c9",
  "input": "Write a reply to Jana Novakova (jana.novakova@example.com) about her refund.",
  "model": "gpt-4o-mini",
  "user_id": "user-123",
  "client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
  "expected_languages": ["en"]
}

The request body is limited to 4 MiB. Unknown fields are rejected with 400 (invalid_payload).

Response

{
  "allowed": true,
  "detected_pii": true,
  "transformed_input": "Write a reply to <PERSON_NAME_1> (<EMAIL_1>) about her refund.",
  "input_char_count": 77,
  "transformed_input_complete": true,
  "client_deanonymization_enabled": false,
  "guard_event_id": "9c1d1b8e-3f5a-4c8e-9a51-0f4f2e5c7d10",
  "client_event_id": "0467f78f-5821-4827-a09b-d59a9b08866c",
  "guard_latency_ms": 840
}

Handling the verdict

const res = await fetch("https://app.getagentid.com/api/v1/guard", {
  method: "POST",
  headers: {
    "x-agentid-api-key": process.env.AGENTID_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    system_id: process.env.AGENTID_SYSTEM_ID,
    input: userMessage,
    client_event_id: clientEventId,
  }),
});
const verdict = await res.json();

if (!verdict.allowed) {
  // Blocked by policy or fail-closed: do not call the model.
  throw new Error(`Blocked by AgentID: ${verdict.reason}`);
}

// Always send the protected text, never the original.
const protectedInput =
  typeof verdict.transformed_input === "string" ? verdict.transformed_input : userMessage;

const answer = await callModel(protectedInput);

Rules:

1. Read allowed even on HTTP 200; a fail-closed system can answer 200 with allowed: false.
2. When transformed_input is present, send it instead of input; the same goes for transformed_attachments.
3. bypassed: true means the check was skipped in a fail-open system. transformed_input is then missing; decide whether your application masks locally or continues.
4. In Shadow Mode (shadow_mode: true) nothing is masked; simulated_decision tells you what Active Guard would have done.
5. If client_placeholder_mapping is present, use it only to restore the answer for the user, in memory.

Chat history

Protect the full message history that you send to the provider, not just the latest message. Guard returns a masked version of input and the attachments only; prompt_context helps detection but is not returned masked. So:

• keep earlier turns in the masked form you already sent (the transformed_input of their own Guard call), or
• mask the assembled history locally with the SDK's protectMessageHistory() before the provider call.

Call Guard once per model call, not once per historical message.

Tool results

When an agent feeds tool output back to the model, check it with origin: "tool_output". Guard then applies tool-output rules, for example blocking instructions injected into a tool result (tool_output_prompt_injection_blocked).

Blocking reasons

Errors, limits and failure reasons are listed in Errors and rate limits.

Configuration endpoint

GET /api/v1/agent/config returns the effective guardrail flags of the key's system (Shadow Mode, failure mode, masking, restoration). The SDKs use it to decide local behaviour. See API reference.