> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Replay a Prompt Through a Preference

> Run a fixture prompt through a saved preference (or an unsaved draft) without burning a completion call.

Replay a fixture prompt through the routing engine twice — once with the preference disabled (baseline) and once with it applied — so you can see exactly what your tuning would change before saving.

Two routes share the same response shape:

* `POST /api/v1/routing-preferences/{id}/test` — replay against a **saved** preference.
* `POST /api/v1/routing-preferences/test` — replay against an **unsaved draft** body (no DB writes). Used by the dashboard test bench on every keystroke.

## Authentication

Requires a Bearer token with the `billing` API key scope.

## Saved-preference body

<ParamField body="prompt" type="string" required>
  Prompt to replay. Up to 4096 chars.
</ParamField>

<ParamField body="mode" type="string" required>
  Caller mode to simulate (e.g. `"auto"`, `"fast"`, `"think"`).
</ParamField>

## Draft body

<ParamField body="prompt" type="string" required>
  Prompt to replay. Up to 4096 chars.
</ParamField>

<ParamField body="mode" type="string" required>
  Caller mode to simulate.
</ParamField>

<ParamField body="draft" type="object" required>
  Unsaved preference envelope. Same shape as a create body minus `scope` and `is_default`. Fields: `name`, optional `description`, `rules`, `examples`, `confidence_floor_overrides`. Validated for brand safety + regex compile + vendor-name scrubbing identically to the persisted routes.
</ParamField>

## Request Examples

<CodeGroup>
  ```bash saved theme={null}
  curl -X POST "https://www.hitheo.ai/api/v1/routing-preferences/$PREF_ID/test" \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "prompt": "Compare these two warranty sections", "mode": "auto" }'
  ```

  ```bash draft theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/routing-preferences/test \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Look at this clause",
      "mode": "auto",
      "draft": {
        "name": "ContractIQ Legal (draft)",
        "rules": [
          { "pattern": "\\b(clause|provision)\\b", "target_mode": "think", "confidence": 0.92 }
        ],
        "examples": []
      }
    }'
  ```

  ```typescript SDK theme={null}
  const diff = await theo.routingPreferences.test(prefId, {
    prompt: "Compare these two warranty sections",
    mode: "auto",
  });
  console.log(diff.baseline.resolved_mode);        // "fast"
  console.log(diff.with_preference.resolved_mode); // "think"
  ```
</CodeGroup>

## Response

Both routes return the same shape. Each blob matches the `routing` telemetry your callers receive on a real completion.

```json theme={null}
{
  "baseline": {
    "requested_mode": "auto",
    "resolved_mode": "fast",
    "promoted": false,
    "reason": "default"
  },
  "with_preference": {
    "requested_mode": "auto",
    "resolved_mode": "think",
    "promoted": true,
    "reason": "customer_preference",
    "explanation": "Routing Studio rule matched: \"clause\".",
    "customer_preference": {
      "rule_matched": "r_a4b8c01x9y",
      "examples_injected": 2
    }
  }
}
```

## Errors

* `400 routing_preference_invalid` — Draft validation failure (vendor name, uncompilable regex, etc.).
* `404 not_found` — Saved preference doesn't exist or isn't visible to the caller.