NeuralTrust | Platform for Agent Security.

TrustTest’s HttpTarget provides a flexible way to connect to any LLM API accessible through HTTP.

This is currently the only model type that can be fully utilized through the TrustTest web UI.

Overview

The HttpTarget class allows you to:

Connect to any REST API endpoint
Configure custom headers, payloads, and authentication
Handle multi-turn conversations
Process various response formats (JSON, plain text)
Implement error handling and retry mechanisms

Basic Usage

Here’s a simple example of how to configure an HttpTarget:

from trusttest.targets.http import HttpTarget, PayloadConfig

target = HttpTarget(
    url="https://api.example.com/chat",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer your_token"
    },
    payload_config=PayloadConfig(
        format={
            "messages": [
                {"role": "user", "content": "{{ message }}"}
            ]
        },
        message_regex="{{ message }}"
    ),
    concatenate_field="choices.0.message.content"
)

Configuration Options

HttpTarget is configured from a small set of top-level fields plus nested config objects for the payload, auth, errors, and retries.

Top-Level Fields

url (required): The HTTP endpoint that receives the prompt.
payload_config (required): Describes the request body and transport behavior.
headers (optional): Static headers sent with every request.
token_config (optional): Fetches a bearer token before the request.
error_config (optional): Maps a specific error response into a normal model response.
response_regex (optional): Applies a regex to the extracted response text.
concatenate_field (optional): Extracts a nested field from JSON, JSON Lines, or SSE responses using dot notation such as choices.0.message.content.
retry_config (optional): Enables retries with exponential backoff.

`PayloadConfig`

PayloadConfig controls both the request body and how the HTTP request is sent:

PayloadConfig(
    format={
        "messages": [
            {"role": "system", "content": "You are a helpful assistant"},
            {"role": "user", "content": "{{ test }}"}
        ],
        "request_id": "{{ random_id }}",
        "session_id": "{{ session_id }}",
        "locale": "{{ locale }}",
    },
    message_regex="{{ test }}",
    date_regex="{{ date }}",
    random_id_placeholder="{{ random_id }}",
    request_variables={
        "session_id": "abc-123",
        "locale": "en-US",
    },
    params={"temperature": 0.7},
    timeout=30,
    rate_limit=0.2,
    ssl_verify=True,
    mtls=False,
)

format (required): JSON body template. TrustTest recursively replaces placeholders inside nested dicts and lists.
message_regex: Placeholder replaced with the prompt text. Default: {{ test }}.
date_regex: Placeholder replaced with the current date in YYYY-MM-DD format. Default: {{ date }}.
random_id_placeholder: Placeholder replaced with a UUID in both the payload and headers. Default: {{ random_id }}.
request_variables: Optional map of custom placeholder names to values. Each name: value entry is substituted wherever {{ name }} appears in the payload. Built-in placeholders ({{ test }}, {{ date }}, {{ random_id }}) take precedence over custom variables. When a test case runs, these variables are attached to the evaluation context and shown in the web UI test case execution view, so you can see the exact request configuration that produced a given response.
params: Query string parameters added to the request URL.
timeout: Request timeout in seconds. Default: 10.
rate_limit: Minimum seconds between requests. For example, 0.1 means 10 requests per second and 2.0 means one request every 2 seconds. Set to null/None to disable client-side rate limiting.
proxy: Optional HTTP proxy URL.
ssl_verify: Whether TLS certificates should be verified. Default: True.
mtls: Enables mutual TLS using the certificates pointed to by MTLS_CERT_PATH and MTLS_KEY_PATH. Default: False.

Response Handling

Use concatenate_field when the API returns structured data and you want TrustTest to extract a specific nested value:

HttpTarget(
    # ... other config
    concatenate_field="choices.0.message.content"
)

Then add response_regex if you still need to trim or normalize the extracted text.

`TokenConfig`

Use token_config when the target requires a token request before the main call:

from trusttest.targets.http import TokenConfig

target = HttpTarget(
    # ... other config
    token_config=TokenConfig(
        url="https://auth.example.com/token",
        payload={"data": {"client_id": "123", "service": "chat"}},
        headers={"Content-Type": "application/json"},
        timeout=10,
        secret="optional-hmac-secret",
    )
)

url: Token endpoint URL.
payload: Body sent to the token endpoint.
headers: Headers for the token request.
timeout: Token request timeout.
secret: Optional shared secret for HMAC-signed token flows. When set, TrustTest signs the auth payload and reuses any returned cookies across the conversation.

`ErrorHandlingConfig`

Use error_config when an API returns useful text inside a known error response and you want to treat it like a model answer instead of raising:

from trusttest.targets.http import ErrorHandlingConfig

target = HttpTarget(
    # ... other config
    error_config=ErrorHandlingConfig(
        status_code=400,
        concatenate_field="errors.0.message"
    )
)

status_code: HTTP status code to intercept.
concatenate_field: Field extracted from that error body. Default: errors.0.message.

`RetryConfig`

Set up automatic retries for transient failures:

from trusttest.targets.http import RetryConfig

target = HttpTarget(
    # ... other config
    retry_config=RetryConfig(
        max_retries=3,
        base_delay=1.0,
        max_delay=10.0,
        exponential_base=2.0
    )
)

max_retries: Number of retries after the initial failed request.
base_delay: Starting delay in seconds.
max_delay: Maximum delay between attempts.
exponential_base: Backoff multiplier applied after each failed attempt.

Example Implementation

This example shows how to create an HttpTarget for a chat API endpoint:

from trusttest.targets.http import HttpTarget, PayloadConfig

target = HttpTarget(
    url="https://chat.neuraltrust.ai/api/chat",
    headers={
        "Content-Type": "application/json"
    },
    payload_config=PayloadConfig(
        format={
            "messages": [
                {"role": "system", "content": "**Welcome to Airline Assistant**."},
                {"role": "user", "content": "{{ test }}"},
            ]
        },
        message_regex="{{ test }}",
    ),
    concatenate_field=".",
)

After configuring your model, you can use it in evaluation scenarios:

from trusttest.evaluation_scenarios import EvaluationScenario
from trusttest.evaluator_suite import EvaluatorSuite
from trusttest.evaluators import CorrectnessEvaluator, ToneEvaluator
from trusttest.dataset_builder import Dataset
from trusttest.probes import DatasetProbe
from trusttest.targets.http import HttpTarget, PayloadConfig


target = HttpTarget(...)

# Create an evaluation scenario
scenario = EvaluationScenario(
    name="Functional Test",
    description="Testing API functionality and responses",
    evaluator_suite=EvaluatorSuite(
        evaluators=[
            CorrectnessEvaluator(),
            ToneEvaluator(),
        ],
        criteria="any_fail",
    ),
)

# Load test data and run the evaluation
dataset = Dataset.from_json(path="data/qa_dataset.json")
test_set = DatasetProbe(target=target, dataset=dataset).get_test_set()
results = scenario.evaluate(test_set)
results.display()

Configure Web UI

In the TrustTest web UI, the Target field accepts the same HttpTarget config in YAML form. The config is parsed with HttpTarget.from_dict, so the field names below should match your Python config one-to-one.

Standard HTTP Target

url: "https://api.example.com/chat"
headers:
  Content-Type: application/json
response_regex: null
concatenate_field: "choices.0.message.content"
payload_config:
  format:
    messages:
      - role: system
        content: "You are a helpful assistant."
      - role: user
        content: "{{ test }}"
    request_id: "{{ random_id }}"
  message_regex: "{{ test }}"
  date_regex: "{{ date }}"
  random_id_placeholder: "{{ random_id }}"
  request_variables:
    session_id: "abc-123"
    locale: "en-US"
  params: {}
  timeout: 30
  rate_limit: 0.2
  proxy: null
  ssl_verify: true
  mtls: false
token_config:
  url: "https://auth.example.com/token"
  payload:
    data:
      client_id: "123"
      service: "chat"
  headers:
    Content-Type: application/json
  timeout: 10
  secret: null
error_config:
  status_code: 400
  concatenate_field: "errors.0.message"
retry_config:
  max_retries: 3
  base_delay: 1.0
  max_delay: 10.0
  exponential_base: 2.0

Azure OIDC in Web UI

If your target uses Azure OIDC, set payload_config.auth_type: azure_oidc and provide the Azure credentials inside payload_config.azure_oidc_config. The backend loader converts that UI shape into an AzureOIDCTarget.

url: "https://api.example.com/chat"
headers:
  Content-Type: application/json
concatenate_field: "choices.0.message.content"
payload_config:
  auth_type: azure_oidc
  format:
    messages:
      - role: user
        content: "{{ test }}"
  message_regex: "{{ test }}"
  timeout: 30
  rate_limit: 0.2
  ssl_verify: true
  mtls: false
  azure_oidc_config:
    tenant_id: "your-tenant-id"
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    scope: "api://your-app-id/.default"
    auth_flow: "client_credentials"

For Azure password-based auth, change auth_flow to password or ropc and add username plus password inside azure_oidc_config.

Getting Started

Core Concepts

Connect your app

Create tests

Evaluate results

HTTP Target

Overview

Basic Usage

Configuration Options

Top-Level Fields

`PayloadConfig`

Response Handling

`TokenConfig`

`ErrorHandlingConfig`

`RetryConfig`

Example Implementation

Configure Web UI

Standard HTTP Target

Azure OIDC in Web UI

​Overview

​Basic Usage

​Configuration Options

​Top-Level Fields

​PayloadConfig

​Response Handling

​TokenConfig

​ErrorHandlingConfig

​RetryConfig

​Example Implementation

​Configure Web UI

​Standard HTTP Target

​Azure OIDC in Web UI

Overview

Basic Usage

Configuration Options

Top-Level Fields

`PayloadConfig`

Response Handling

`TokenConfig`

`ErrorHandlingConfig`

`RetryConfig`

Example Implementation

Configure Web UI

Standard HTTP Target

Azure OIDC in Web UI