Mapping Examples
Practical examples showing how to configure request and response mappings for different API patterns. Each example includes the request body template, response mapping, and a description of how Rhesis translates between platform-managed variables and your API.
Simple Query-Response API
The most basic pattern: a single input field and a top-level output field.
API contract: Your API expects \{"prompt": "..."\} and returns \{"text": "..."\}.
Request body template:
Response mapping:
Rhesis maps its input variable to your API’s prompt field, and extracts
your API’s text field into the platform’s output variable.
OpenAI-Compatible API
For APIs that follow the OpenAI chat completions format.
Request body template:
Response mapping:
The response text is nested inside choices[0].message.content. The metadata
field captures token usage statistics for reference.
Multi-turn conversations: This example sends a single user message. Since
OpenAI-compatible APIs are stateless, you can use "messages": "{{ messages }}"
instead to let Rhesis manage the full conversation history automatically. The
response mapping stays the same. See the
Stateless Endpoint example below or
Multi-Turn Conversations
for details.
Anthropic Claude API
For APIs following Anthropic’s message format.
Request body template:
Response mapping:
Anthropic returns the response in content[0].text rather than
choices[0].message.content.
Multi-turn conversations: Like OpenAI, the Anthropic API is stateless.
Replace the hardcoded messages array with "messages": "{{ messages }}" to
let Rhesis manage conversation history across multiple turns. See
Multi-Turn Conversations
for details.
Google Gemini API
For the Google Gemini (Vertex AI) chat format.
Request body template:
Response mapping:
Gemini uses a deeply nested structure with candidates, content, and parts.
Multi-turn conversations: The Gemini API is also stateless. For
multi-turn testing, replace the hardcoded contents array with
"contents": "{{ messages }}" to let Rhesis manage the conversation
history. See
Multi-Turn Conversations
for details.
RAG Endpoint with Context
For retrieval-augmented generation APIs that return source documents alongside the answer.
API contract: Your API expects a query and returns an answer with sources.
Request body template:
Response mapping:
The context variable captures the retrieved sources, which Rhesis can use for
context-dependent metrics like faithfulness and relevance.
Fallback Response Paths
When your API might return the response in different locations depending on the
request type, use Jinja2 templates with jsonpath() for fallback logic.
Response mapping:
Rhesis tries each JSONPath expression in order and uses the first non-empty result. This is useful for APIs that have different response shapes for different endpoints or error conditions.
Stateful Conversation Endpoint
For APIs that manage their own session state and return a conversation identifier.
Request body template:
Response mapping:
On the first turn, conversation_id renders as null. The API returns a new
conversation ID, which Rhesis automatically includes in subsequent requests.
See Multi-Turn Conversations
for details.
Stateless Conversation Endpoint
For APIs that expect the full message history with every request (e.g., direct LLM provider APIs).
Request body template:
Response mapping:
Rhesis detects the messages variable and manages conversation history
internally. The system_prompt is prepended to the messages array and removed
from the request body before sending. See
Multi-Turn Conversations for
details.
Custom Business Fields
For APIs that require domain-specific fields beyond the standard platform variables. Custom fields are passed through from the test input.
Request body template:
Response mapping:
Custom fields like policy_number and tier must be included in the test input
or API request body when invoking the endpoint. Use the default filter to
provide fallback values for optional fields.
API with Authentication in the Body
Some APIs require authentication tokens or API keys in the request body rather than in headers.
Request body template:
Response mapping:
The auth_token variable is automatically populated from the authentication
token configured in your endpoint settings. See
Platform-Managed Variables
for details.
Deeply Nested Response
For APIs with complex, deeply nested response structures.
Response mapping:
The metadata field uses a Jinja2 template to construct a custom object from
multiple response paths. This is useful when you want to aggregate data from
different parts of the response.
WebSocket Endpoint
WebSocket endpoints use the same mapping syntax. The request template defines the message format sent over the WebSocket connection.
Request body template:
Response mapping:
The mapping works the same regardless of transport protocol (REST or WebSocket).
Next Steps
- Learn about Single-Turn Endpoints for template syntax details
- Configure Multi-Turn Conversations for conversational testing
- Explore SDK Endpoints for code-first endpoint definition