---
title: "Simulate Negotiation Settings"
method: POST
path: "/v1/settings/negotiation/simulate"
tags: ["settings"]
---

# Simulate Negotiation Settings

`POST /v1/settings/negotiation/simulate`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v1/settings/negotiation/simulate`
- Auth: HTTP bearer

Dry-run an unsaved pricing config through the real negotiation strategy. Persists nothing.

## Headers

- `mentium-workspace-id` string, nullable

## Request body

- SimulateNegotiationRequestSchema: A hypothetical load envelope, a settings payload, and what the carrier says each round.
  - `settings` object, required: An unsaved tms.pricing.settings payload to try out.
  - `opening_carrier_rate_amount` union, required: What the agent opens at.
    - number
    - string
  - `max_carrier_rate_amount` union, required: The max load offer carrier rate, never shown to an agent.
    - number
    - string
  - `opened_by` 'ai_agent' | 'carrier': Which role names the first number. 'carrier' is an inbound carrier quoting before the agent has offered.
  - `opening_carrier_rate_source` string, nullable: What the opening was derived from, for take-it-or-leave-it bases.
  - `rounds` SimulationRoundInput[]
    - `carrier_ask_amount` union: What the carrier asks for on this round.
      - number
      - string
    - `human_agent_quote_amount` union: A number you put on the table yourself instead of the agent's, for this round.
      - number
      - string

## Response `200`

Successful Response

- SimulateNegotiationResponseSchema
  - `opening_carrier_rate_amount` string, required
  - `max_carrier_rate_amount` string, required
  - `rounds` SimulatedRound[], required
    - `round` integer, required
    - `carrier_ask_amount` string, nullable
    - `agent_quote_amount` string, nullable
    - `agent_role` 'ai_agent' | 'human_agent', required
    - `outcome` 'opening' | 'quote' | 'hold' | 'accept' | 'stop' | 'undercut' | 'broker_override' | 'no_carrier_ask', required
    - `moved_by` string, nullable: Change from the agent's previous rate.
    - `detail` RoundDetail, required: Everything the negotiation strategy reported for one round.
      - `action` string, nullable: The negotiation strategy's raw action for this round.
      - `raw_carrier_rate_amount` string, nullable: The rate before it was rounded to the increment.
      - `negotiation_round_before` integer, required
      - `negotiation_round_after` integer, required
      - `negotiation_moves` integer, required: How many genuine concessions the carrier has made so far.
      - `undercut_rounds_used` integer, required
      - `recorded` boolean, required: Whether this round put an agent-side rate on the record.
      - `recorded_as` string, nullable: The event source it was recorded under.
      - `note` string, required: Why the negotiation strategy did what it did, in plain language.

## Other responses

- `404`: Not found
- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)