--- title: "Evaluate an AI Guard request" method: POST path: "/api/v2/ai-guard/evaluate" tags: ["AI Guard"] --- # Evaluate an AI Guard request `POST /api/v2/ai-guard/evaluate` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/ai-guard/evaluate` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `ai_guard_evaluate` - TypeScript: (a function with typed inputs; its response is checked against the schema) Analyzes a conversation for security threats such as prompt injection, jailbreak attempts, and other AI-specific attacks. Returns an action recommendation (`ALLOW`, `DENY`, or `ABORT`) along with the detected threat tags and their confidence scores. AI Guard must be activated for the organization, and the calling user or application key requires the `ai_guard_evaluate` permission. The action is a recommendation for the caller to enforce: ALLOW permits the interaction, DENY blocks the interaction, and ABORT terminates the workflow. This endpoint is rate limited to `700` requests per minute per organization. Organization token limits can also result in a 429 response. Malformed messages return a 400 response. Requests exceeding the raw-input limit of 1,000,000 tokens return a 413 response; this limit applies to the input context, not only the size of the HTTP request body. ## Request body - AIGuardEvaluateRequest: The request to evaluate a conversation for security threats. - `data` AIGuardEvaluateRequestData, required: The JSON:API request envelope for an AI Guard evaluation. - `attributes` AIGuardEvaluateRequestDataAttributes, required: The conversation to evaluate and its metadata. - `messages` AIGuardMessage[], required: The messages of the conversation to evaluate, in order. Must contain at least one message. - `content` union: The content of a message, either a plain string or a list of OpenAI-style content parts. - string: The message content as a plain string. - AIGuardContentPart[]: The message content as a list of content parts. The list must be non-empty for user, system, developer, and tool messages. - `image_url` AIGuardImageURL: An image referenced by URL in a message content part. - … - `text` string: The text content, required and non-empty when `type` is `text` in a user, system, developer, or tool message. - `type` 'text' | 'image_url', required: The type of the content part. - `role` 'user' | 'assistant' | 'system' | 'developer' | 'tool', required: The role of the message author in the conversation. - `tool_call_id` string: The identifier of the tool call this message responds to, present on tool result messages. - `tool_calls` AIGuardToolCall[]: The tool calls emitted by the assistant, present on assistant messages that call tools. - `function` AIGuardToolCallFunction, required: The function invoked by a tool call. - `arguments` string, required: The arguments of the function call, serialized as a JSON string. - `name` string, required: The name of the function to call. - `id` string, required: The identifier of the tool call. - `meta` AIGuardMeta: Metadata about the evaluated conversation, used to select the policy and evaluator behavior. - `coding_agent` string: The coding agent that produced the conversation. By default, a non-empty value selects the coding-agent evaluator profile, while an omitted or empty value selects the default profile. Known identifiers include `claude-code`, `codex`, `cursor`, and `github-copilot`; other identifiers are accepted. The coding-agent profile assumes the caller can ask the user to confirm Supply Chain Firewall warnings; the default profile assumes it cannot. - `confidence_threshold` union: Request-only confidence threshold override. A number sets the threshold for every threat category; an object supplies a global threshold and optional per-category overrides. Omit this field to use the stored sensitivity policy. This field is not returned in evaluation responses. - number, double: The global confidence threshold applied to every threat category. - AIGuardConfidenceThreshold: Request-level confidence threshold override. `flagging_global` is the global threshold applied to every threat category. Any other property is a per-category override keyed by an AI Guard threat tag; per-category values take precedence over `flagging_global`, and categories without an entry fall back to it. When this object omits flagging_global, the fallback is `0.5`. Recognized category keys include policy-evasion, indirect-prompt-injection, system-and-capability-discovery, credential-access, sensitive-data-collection, privilege-escalation, malicious-execution, private-network-target, destructive-or-resource-abuse, tool-abuse, poisoning-or-persistence, and `data-exfiltration`. Unknown category keys are ignored. - `flagging_global` number, double: The global confidence threshold applied to categories without a specific override. - `env` string: The environment the conversation belongs to. - `is_sds_enabled_override` boolean: Whether to run the Sensitive Data Scanner for this request, overriding the stored policy. - `service` string: The name of the service the conversation belongs to. - `tool_policies` object: A non-empty map replaces stored tool policies for this request only, keyed by tool name. Any called tool not present resolves to EVALUATE. Only takes effect when tool policies are enabled for the organization. - `type` 'evaluations', required: The JSON:API resource type for AI Guard evaluation requests and responses. Its value is `evaluations` for the action endpoint `/api/v2/ai-guard/evaluate`. ## Response `200` OK - AIGuardEvaluateResponse: The response containing the evaluation result. - `data` AIGuardEvaluateDataResponse, required: The JSON:API evaluation resource. - `attributes` AIGuardEvaluateAttributesResponse, required: The evaluation result with the recommended action and detected threat information. - `action` 'ALLOW' | 'DENY' | 'ABORT', required: The recommended action for the evaluated conversation. - `global_prob` number, double: The global threat probability, between `0` and `1`. Included only when computed. - `is_blocking_enabled` boolean, required: Whether blocking is enabled for the organization. - `reason` string, required: The explanation for the recommended action, for logging rather than user-facing display. - `redaction_replacements` AIGuardRedactionReplacement[]: The redacted replacements computed for the request. Included only when redaction applies. - `path` string, required: The path of the redacted content relative to the request attributes. - `replacement` string, required: The redacted replacement content. - `scfw_findings` AIGuardScfwFindings: The Supply Chain Firewall verdict for the version-pinned install packages found in the request. Evaluation requires Supply Chain Firewall to be enabled for the organization and the caller to have the `appsec_vm_read` permission. Without that permission, Supply Chain Firewall evaluation is skipped; the AI Guard evaluation request itself is not rejected. Findings are omitted when Supply Chain Firewall does not produce a result. The recommended action combines the package outcomes. Confirmation support is inferred from the evaluator profile, not from a separate confirmation-capability flag. By default, a non-empty `meta.coding_agent` selects the coding-agent profile, which assumes the caller can ask for confirmation and retains WARN in `recommended_action`. Omitting `meta.coding_agent` or setting it to an empty string selects the default profile, which assumes the caller cannot ask for confirmation and returns ALLOW instead of WARN in `recommended_action`. Package outcomes still retain WARN, and BLOCK is never changed to ALLOW by this rule. - `packages` AIGuardScfwPackageFinding[]: The packages the firewall evaluated, `ALLOW` ones included. - `ecosystem` string, required: The package ecosystem the firewall evaluated, such as `PyPI`, `npm`, or `crates.io`. - `matched_rules` AIGuardScfwMatchedRule[]: Every rule the firewall matched on the package. - `outcome` 'ALLOW' | 'WARN' | 'BLOCK', required: The Supply Chain Firewall outcome for a package, a matched rule, or the whole request. - `rule` string, required: The rule text the firewall reported, or the policy type when no text was reported. - `name` string, required: The name of the package. - `outcome` 'ALLOW' | 'WARN' | 'BLOCK', required: The Supply Chain Firewall outcome for a package, a matched rule, or the whole request. - `version` string, required: The version of the package. - `recommended_action` 'ALLOW' | 'WARN' | 'BLOCK', required: The Supply Chain Firewall outcome for a package, a matched rule, or the whole request. - `sds_findings` AIGuardSdsFinding[]: The sensitive data findings from the Sensitive Data Scanner. Included only when findings exist. - `category` string, required: The category of the sensitive data found. - `location` AIGuardSdsFindingLocation, required: The location of a sensitive data match within the request. - `end_index_exclusive` integer, required: The exclusive end index of the match within the located content. - `path` string, required: The path of the match relative to the request attributes. - `start_index` integer, required: The start index of the match within the located content. - `rule_display_name` string, required: The display name of the SDS rule that matched. - `rule_tag` string, required: The tag of the SDS rule that matched. - `tag_probs` object, nullable, required: The detection confidence for each threat tag, between `0` and `1`. May be null when the evaluation does not produce per-category scores. - `tags` string[], required: The threat tags detected in the conversation. - `id` string, required: The unique identifier of the evaluation. - `type` 'evaluations', required: The JSON:API resource type for AI Guard evaluation requests and responses. Its value is `evaluations` for the action endpoint `/api/v2/ai-guard/evaluate`. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `408`: Request Timeout - `413`: Payload Too Large - `429`: Too many requests --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)