Evaluate Interactions
[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:
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
The ID or alias for the Project to govern the request processing.
Request body
Example request
{
"metadata": {
"model": "gpt-4-turbo",
"requester_id": "user-12345",
"provider": "openai",
"external_session_id": "sess_4b8cde94604f4c389406a0b2f806069a"
},
"interaction": {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, how can I help you today?"
}
],
"timestamp": {
"value": "2024-02-10T12:00:00Z"
}
}
],
"tools_available": [
{
"name": "web_search",
"description": "Search the web for current information"
}
]
}
}Response
Successful evaluation. Returns the evaluation context (evaluated_interaction) and the policy outcome — action, threat level, detections, and the effective payload.
Example response
{
"metadata": {
"evaluation_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"evaluated_at": "2024-01-15T10:30:00.000Z",
"provider": "openai",
"model": "gpt-4-turbo",
"requester_id": "user-12345",
"project": {
"project_id": "ca87b009-90bd-4724-91c2-f23326acd51a",
"project_alias": "enterprise-search",
"policy_id": "dfaf7f57-2290-435f-b14a-d0e4da4b4ce2",
"configuration_id": "b5d7d261-b7be-451a-b943-0d408ab88aab"
},
"processing_time_ms": 15.34
},
"evaluated_interaction": {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, how can I help you today?"
}
],
"timestamp": {
"value": "2024-02-10T12:00:00Z"
}
}
],
"tools_available": [
{
"name": "web_search",
"description": "Search the web for current information"
}
]
},
"outcome": {
"action": "REDACT",
"threat_level": "MEDIUM",
"detections": [
{
"rule_name": "prompt_injection",
"risk_level": "HIGH"
}
],
"effective_interaction": {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, how can I help you today?"
}
],
"timestamp": {
"value": "2024-02-10T12:00:00Z"
}
}
],
"tools_available": [
{
"name": "web_search",
"description": "Search the web for current information"
}
]
}
}
}