Skip to navigation
Guard APIGuard

Screen content for threats

The guard API endpoint is the integration point for GenAI applications using AI Guardrails. It allows you to call on all of AI Guardrails’ defenses with a single API call.

For an overview and integration guidance please see here.

Using guard, you can submit the content of an LLM interaction to AI Guardrails. This include inputs from the user, reference documents, and the LLM output. The guardrails configured in the policy will screen the interaction, and a flagging response will indicate whether any threats were detected, in line with your policy.

Your application can then be programmed to take mitigating action based on the flagging response, such as blocking the interaction, warning the end user, or generating an internal security alert.

A request must contain messages, tools, or both. Send tools on its own to screen tool definitions independently of a conversation.

Authentication

AuthorizationBearer

Bearer authentication using API key. Generate an API key from the AI Guardrails Dashboard. Example: Bearer sk_123…

Request

This endpoint expects an object.
messageslist of objectsOptional

List of messages comprising the interaction history with the LLM in OpenAI API Chat Completions format. Can be multiple messages of any role: user, assistant, system, tool, or developer. Required unless tools is provided.

toolslist of objectsOptional

List of tool definitions exposed to the model, in OpenAI function-calling format. Each definition is screened on every request if your policy applies Prompt Defense to the Tool Definition role (screening location tool_definition::content). Can be sent without messages. See Tool definitions.

project_idstringOptional
ID of the relevant project. The request will be screened according to the policy assigned to the project. If no project ID is passed then the AI Guardrails Default Policy will be used for screening.
payloadbooleanOptional
When true the response will return a payload object containing any PII, profanity or custom detector regex matches detected, along with their location within the contents.
breakdownbooleanOptional
When true the response will return a breakdown list of the detectors that were run, as defined in the policy, and whether each of them detected something or not.
metadataobjectOptional

Metadata tags can be attached to screening requests as an object that can contain any arbitrary key-value pairs. Common use cases include specifying the user or session ID.

dev_infobooleanOptional
When true the response will return an object with developer information about the build of AI Guardrails.

Response

Screening result
flaggedbooleanOptional

Depends on the action configured for the project. If action is enforce, flagged is true if any threats were detected with sufficient confidence. But if action is detect, flagged is always false. See Project Mode for more details.

actionenumOptional

The action configured for the project screening this request. enforce means full enforcement: the top-level flagged is true whenever a detector triggers. detect surfaces detections in the breakdown but forces the top-level flagged to false, letting you observe detector behavior without blocking traffic. Configured on the project level.

Allowed values:
payloadlist of objectsOptional

Contains detected PII, profanity, or custom regex matches with their locations. Only returned if payload=true in request.

breakdownlist of objectsOptional

List of detectors run and their results. Only returned if breakdown=true in request.

toolsobjectOptional

Screening results for the tool definitions in the request’s tools array, separate from the message-level results. Only returned if the request contains tools, the policy applies a detector to the Tool Definition role, and breakdown is true.

dev_infoobjectOptional

Build information. Only returned if dev_info=true in request.

metadataobjectOptional
Metadata returned from the request

Errors

400
Bad Request Error
401
Unauthorized Error
429
Too Many Requests Error
500
Internal Server Error