--- title: "Evaluate Interactions" method: POST path: "/detection/v2/interaction-evaluations" tags: ["interactions-v2_other"] --- # Evaluate Interactions `POST /detection/v2/interaction-evaluations` [BETA] This endpoint is not GA or Production ready and is subject to changes at any time. Breaking changes may occur. Performs synchronous security evaluation on an LLM **interaction**. The interaction can be a standalone user prompt, a standalone model response, a partial exchange, or a long multi-turn message history. The endpoint imposes no requirement that the messages form a complete request/response pair. The request carries `metadata` and an `interaction` payload. The `interaction` field accepts either: - the **canonical**, provider-agnostic form (`CanonicalInteraction`) — an ordered sequence of messages (user, assistant, system, tool) with their role and content parts, and optionally the tool catalog that was in scope; or - a **native LLM-provider payload** passed through verbatim. Supported provider formats: - [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat) - [OpenAI Responses](https://platform.openai.com/docs/api-reference/responses) - [Anthropic Messages](https://docs.anthropic.com/en/api/messages) Returns the evaluation context (`evaluated_interaction`): the canonicalized messages with per-message signals and findings attached. Also returns the policy outcome, which carries the enforcement action, threat level, any detections, and the effective payload the caller should forward (`outcome.effective_interaction`). Use this endpoint when you need full evaluation results. For inline pass-through (provider request/response payloads returned in the same provider format), use the request-evaluations and response-evaluations endpoints instead. ## Headers - `HL-Project-Id` string ## Request body - InteractionEvaluationRequest — Request payload for synchronous evaluation of an LLM interaction. The interaction a standalone user prompt, a standalone model response, a partial exchange, or a long multi-turn message history. There is no requirement that the messages form a complete request/response pair. The `interaction` field accepts either the canonical, provider-agnostic form (`CanonicalInteraction`) or a native LLM-provider payload passed through verbatim. Supported provider formats are OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. - `metadata` InteractionEvaluationRequestMetadata, required — Metadata about the LLM interactions being evaluated. - `model` string, required — The model identifier used for the interaction. - `requester_id` string, required — Identifier for the entity making the request. Could be a user ID, service account, or agent identifier. - `provider` string, required — The LLM provider (e.g., openai, anthropic, azure, bedrock). - `external_session_id` string — An externally-defined session identifier to group interactions into a single session. The identifier should be unique across all sessions. - `interaction` union, required — The interaction to evaluate. Accepts either the canonical form (`CanonicalInteraction` — `messages` and optional `tools_available`) or a native LLM-provider payload passed through verbatim. Supported provider formats are OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. `ProviderPayload` is intentionally permissive (any JSON object) so callers can supply provider-native shapes without schema constraints. - CanonicalInteraction — The canonical (provider-agnostic) form of an LLM interaction: an ordered sequence of messages, optionally with the tool catalog that was in scope. Use this form to evaluate interactions independently of any specific provider's payload structure. - `messages` CanonicalInteractionMessage[], required — Ordered sequence of messages to evaluate, in chronological order. May contain any combination of user input, assistant output, system prompts, and tool calls/results — and may be a single message or many. There is no requirement that the messages form a complete request/response pair. - `role` string, required — The role of the message sender. Standard roles include: - `user`: End-user input - `assistant`: LLM/agent response - `system`: System instructions or context - `tool`: Tool result message - `content` ContentPart[], required — Array of content parts representing the message content. Each part has a `type` field indicating the content type. - union — A content part within an individual message. - TextPart — A text content part within a message. - … - ToolUsePart — A tool invocation part representing a tool call by the assistant. - … - ToolResultPart — A tool result part containing the output from a tool execution. - … - `timestamp` object — Optional timestamp for when this message was created. When supplied, `value` is required. - `value` string, date-time, required — The timestamp in ISO 8601 / RFC 3339 format. - `tools_available` ToolBase[] — Tool definitions available to the model in the context of these messages. - `name` string, required — Name of the tool. - `description` string — Human-readable description of what the tool does. - `parameters` object — JSON Schema defining the tool's input parameters. Stored as a flexible object to support various schema formats. - ProviderPayload — A pass-through payload in the native format of the LLM provider. Any valid provider request or response payload is accepted as-is and returned in the same format. ## Response `200` Successful evaluation. Returns the evaluation context (`evaluated_interaction`) and the policy outcome — action, threat level, detections, and the effective payload. - InteractionEvaluationResponse — Response payload from synchronous evaluation of an LLM interaction. Contains metadata about the call, the evaluation context (`evaluated_interaction`) that detection rules ran against, and the policy outcome — which carries the enforcement action, threat level, detections, and the effective payload the caller should forward (`outcome.effective_interaction`). `evaluated_interaction` is always the canonicalized form of the request, enriched per-message with signals and findings from signal extraction — a uniform shape that detection rules target regardless of which form the request supplied. `outcome.effective_interaction` mirrors the shape of the request's `interaction` field — canonical or provider-native — with any redactions, substitutions, or tool modifications from the outcome's action applied in place. - `metadata` InteractionEvaluationResponseMetadata, required — Metadata about the completed evaluation of the interactions. - `evaluation_id` string, uuid, required — Server-generated unique identifier for this evaluation. Persisted on the stored interaction record and referenced in structured logs for correlation. - `evaluated_at` string, date-time, required — Timestamp when the evaluation was performed. - `provider` string, required — The LLM provider from the request. - `model` string, required — The model identifier from the request. - `requester_id` string, required — The requester identifier from the request. - `project` InteractionEvaluationProjectContext, required — Project context resolved for this evaluation. - `project_id` string, uuid, required — The unique identifier for the Project. - `project_alias` string — A custom alias for the Project. - `policy_id` string, uuid, required — The unique identifier for the Policy applied to this interaction. - `configuration_id` string, uuid, required — The unique identifier for the Configuration used during evaluation. - `processing_time_ms` number, float, required — Total time taken to perform the evaluation, in milliseconds. - `evaluated_interaction` InteractionPayload, required — The canonicalized interaction as seen by the evaluator — messages and tool catalog — annotated per-message with signals and their findings. Used for `evaluated_interaction` regardless of which form the request supplied: when the request used a native provider payload, the evaluator canonicalizes it into this shape so detection rules can target a uniform structure. - `messages` InteractionPayloadMessage[], required — Ordered sequence of canonicalized messages. Each message is annotated with the signals that fired against it (and findings produced by those signals). - `role` string, required — The role of the message sender. Standard roles include: - `user`: End-user input - `assistant`: LLM/agent response - `system`: System instructions or context - `tool`: Tool result message - `content` ContentPart[], required — Array of content parts representing the message content. Each part has a `type` field indicating the content type. - union — A content part within an individual message. - TextPart — A text content part within a message. - `type` 'text', required — Content part type for text. - `text` string, required — The text content. - ToolUsePart — A tool invocation part representing a tool call by the assistant. - `type` 'tool_use', required — Content part type for tool invocation. - `id` string, required — Tool call identifier. Used to correlate tool invocations with their results. - `tool_name` string, required — Name of the tool being invoked. - `tool_input` object — Tool arguments/input as a key-value object. - ToolResultPart — A tool result part containing the output from a tool execution. - `type` 'tool_result', required — Content part type for tool result. - `id` string, required — Tool call identifier. Used to correlate this result with the original tool invocation. - `result` string, required — The tool execution result content. - `success` boolean — Whether the tool execution succeeded. - `timestamp` object — Optional timestamp for when this message was created. When supplied, `value` is required. - `value` string, date-time, required — The timestamp in ISO 8601 / RFC 3339 format. - `analysis` InteractionMessageAnalysis — Per-message security analysis from signal extraction. `signals` mirrors the production-signals dictionary fed into the policy evaluation context — each key is a signal name (e.g., `prompt_injection`, `code`), each value is the opaque finding object that signal produced. - `signals` object, required — Production signal findings for this message, keyed by signal name. All known production signal types are always present (populated with schema defaults when nothing fired). Values are opaque finding objects whose internal shape may evolve. - `tools_available` ToolBase[] — The canonicalized tool catalog that was in scope during evaluation. Present only when tools were provided in the request. - `name` string, required — Name of the tool. - `description` string — Human-readable description of what the tool does. - `parameters` object — JSON Schema defining the tool's input parameters. Stored as a flexible object to support various schema formats. - `outcome` InteractionEvaluationOutcome, required — The policy outcome for the evaluated interactions. Carries the enforcement action, threat level, any detections produced by detection rules against `evaluated_interaction`, and the effective payload the caller should forward. - `action` 'NONE' | 'DETECT' | 'REDACT' | 'BLOCK', required — The action applied based on policy evaluation. `NONE` means policy evaluation produced no detections — either no rules fired or no findings were emitted; the `detections` array is empty and the effective payload is unchanged. `DETECT`, `REDACT`, and `BLOCK` all mean one or more detections were produced; they differ in what the policy did with the payload. `DETECT` is an intentional observe-only outcome (detections are surfaced but the effective payload is unchanged); `REDACT` modifies the payload in place; `BLOCK` substitutes a canned block response. - `threat_level` 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL', required — The highest threat level across all detections, based on interaction analysis and configured tenant security rules. Values are ordered by severity from least to most: NONE, LOW, MEDIUM, HIGH, CRITICAL. - `detections` InteractionEvaluationDetection[], required — Security detections produced by detection rules running against the evaluation context. Always present; an empty array means no rules triggered. - `rule_name` string, required — The human-readable name of the detection rule (e.g., prompt_injection, sensitive_pii_exposed). - `risk_level` 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL', required — Categorical risk level for this detection. - `effective_interaction` union, required — The payload the caller should forward downstream. Mirrors the shape of the request's `interaction` field: if the request supplied the canonical form (`CanonicalInteraction`), the response returns the canonical form here; if the request supplied a native LLM-provider payload (OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages), the response returns that same provider-native shape. Any redactions, substitutions, or tool modifications from the outcome's `action` are applied in place. - CanonicalInteraction — The canonical (provider-agnostic) form of an LLM interaction: an ordered sequence of messages, optionally with the tool catalog that was in scope. Use this form to evaluate interactions independently of any specific provider's payload structure. - `messages` CanonicalInteractionMessage[], required — Ordered sequence of messages to evaluate, in chronological order. May contain any combination of user input, assistant output, system prompts, and tool calls/results — and may be a single message or many. There is no requirement that the messages form a complete request/response pair. - `role` string, required — The role of the message sender. Standard roles include: - `user`: End-user input - `assistant`: LLM/agent response - `system`: System instructions or context - `tool`: Tool result message - `content` ContentPart[], required — Array of content parts representing the message content. Each part has a `type` field indicating the content type. - union — A content part within an individual message. - … - `timestamp` object — Optional timestamp for when this message was created. When supplied, `value` is required. - `value` string, date-time, required — The timestamp in ISO 8601 / RFC 3339 format. - `tools_available` ToolBase[] — Tool definitions available to the model in the context of these messages. - `name` string, required — Name of the tool. - `description` string — Human-readable description of what the tool does. - `parameters` object — JSON Schema defining the tool's input parameters. Stored as a flexible object to support various schema formats. - ProviderPayload — A pass-through payload in the native format of the LLM provider. Any valid provider request or response payload is accepted as-is and returned in the same format. ## Other responses - `400` — Malformed request — the request body could not be parsed as JSON or is structurally invalid. - `401` — Authentication Error - `403` — Forbidden Error - `422` — Validation error — the request was parseable but failed schema validation (e.g., missing required fields, unknown enum values, empty `messages` array). - `500` — Server-side failure while performing the analysis — e.g., canonicalization, signal extraction, or policy evaluation failed for internal reasons. The request itself was well-formed and valid. --- [API](https://skmtc.net/hiddenlayerai/apis/hiddenlayer-audit-api.md) · [All operations](https://skmtc.net/hiddenlayerai/apis/hiddenlayer-audit-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hiddenlayerai/hiddenlayer-audit-api/revisions/d8c55b669109/schema)