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

# Negotiations API: Inspect, Drive, and Close Deal Rounds

> Inspect active deal rounds, submit vendor replies, record off-chain savings, and draft outreach emails for every contract Tavryn is negotiating.

Negotiations are Tavryn's core output. When the agent detects a savings opportunity on a contract — idle seats, usage decline, or an approaching renewal — it opens a negotiation and runs a multi-round back-and-forth with the vendor simulator (or a real vendor contact). Each negotiation tracks every round, the current offer on the table, the target price Tavryn is working toward, and any reviewer verdict. You can inspect, influence, and close negotiations programmatically through the endpoints below.

## The Negotiation Object

The following fields appear in negotiation responses across all endpoints.

**id** `string`

UUID of the negotiation record.

**contract\_id** `string`

UUID of the contract this negotiation is tied to.

**status** `string`

Current lifecycle state of the negotiation. One of:

| Value | Description |
| - | - |
| `active` | Rounds are in progress; the agent is still negotiating. |
| `completed` | A deal was reached and savings have been recorded. |
| `cancelled` | The negotiation was abandoned (walk-away ceiling hit or manual cancellation). |
| `pending_review` | The agent flagged the deal for human inspection before proceeding. |
| `pending_approval` | A transaction above the business's `human_approval_required_above` policy threshold is waiting for an approver. |

**rounds** `number`

Number of offer-counter-offer cycles completed so far.

**current\_offer** `number`

The most recent price Tavryn put on the table (in USD).

**target\_price** `number`

The price Tavryn is aiming to close at, derived from the waste heuristic and market benchmarks.

**savings\_amount** `number`

Projected or confirmed annual savings in USD (`original_price - final_price`).

**reviewer\_verdict** `string | null`

Human reviewer decision when the negotiation entered `pending_review` or `pending_approval`. One of:

| Value | Description |
| - | - |
| `AGREE` | Reviewer approved the proposed deal. |
| `CHALLENGE` | Reviewer sent the agent back to negotiate harder. |
| `REJECT` | Reviewer declined the deal and cancelled the negotiation. |
| `null` | No review has been requested or completed yet. |

***

## How Negotiations Start

You do not need to open negotiations manually. Tavryn triggers them in two ways:

1. **Daily cron** — Tavryn's procurement engine runs every day, scans all active contracts approaching renewal, scores them for savings potential using seat-optimization and usage-decline heuristics, and opens negotiations autonomously.
2. **On-demand via `POST /api/agent/run-now`** — You can trigger an immediate scan for a specific business (or all businesses) at any time. See the [Agent API](https://tavryn.mintlify.site/api-reference/agent.md) for details.

To start a negotiation directly against a single contract, use `POST /api/agent/negotiate/{contractId}`.

***

## Get Negotiation Status

Retrieve the current negotiation state, full contract record, and vendor memory for a contract.

```http theme={null}
GET /api/agent/negotiate/{contractId}
```

### Path Parameters

**contractId** `string` *required*

UUID of the contract whose negotiation status you want to retrieve.

### Response

**exists** `boolean`

`true` if an active or historical negotiation record exists for this contract.

**negotiation** `object | null`

The negotiation object as described above, or `null` if no negotiation has been opened yet.

**contract** `object`

The full contract record including the linked vendor.

**memory** `object | null`

Tavryn's vendor memory for this business — prior negotiation outcomes, concession patterns, and relationship context used to calibrate future offers.

### Example Response

```json theme={null}
{
  "exists": true,
  "negotiation": {
    "id": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "contract_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "active",
    "rounds": 2,
    "current_offer": 9800,
    "target_price": 9200,
    "savings_amount": 2800,
    "reviewer_verdict": null
  },
  "contract": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "service": "Team Plan",
    "current_price": 12000,
    "renewal_date": "2025-11-01T00:00:00.000Z",
    "seat_count": 50,
    "active_seats": 31,
    "status": "active"
  },
  "memory": {
    "prior_deals": 1,
    "average_concession_pct": 18.4,
    "last_outcome": "completed"
  }
}
```

***

## Start or Advance a Negotiation

Open a new negotiation or push an existing one forward by submitting a new round with optional parameter overrides.

```http theme={null}
POST /api/agent/negotiate/{contractId}
```

> [!WARNING]
>
> This endpoint is rate-limited to **20 requests per minute per contract**. Exceeding the limit returns HTTP `429` with a `resetMs` field indicating when the window resets.

### Path Parameters

**contractId** `string` *required*

UUID of the contract to negotiate.

### Request Body

All body fields are optional. Omitting them lets Tavryn use its default negotiation strategy.

**maxRounds** `number`

Maximum number of offer-counter-offer rounds before the agent walks away. Integer between `1` and `20`. Defaults to the agent's internal strategy setting.

**walkAwayCeiling** `number`

Maximum price (in USD) Tavryn will accept before abandoning the negotiation. Must be a positive number. Use this to enforce hard budget caps.

**targetPrice** `number`

Explicit target price (in USD) you want Tavryn to negotiate toward. Overrides the heuristic-derived target.

### Response

**result** `object`

The outcome of the negotiation loop, including the final round state, accepted flag, vendor counter message, and updated savings figures.

### Example Request

```bash theme={null}
curl -X POST https://your-tavryn-instance.com/api/agent/negotiate/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -d '{
    "maxRounds": 5,
    "targetPrice": 9000
  }'
```

***

## Draft Vendor Outreach Email

Generate a professional outreach email to kick off a negotiation with a real vendor contact.

```http theme={null}
POST /api/agent/negotiate/{contractId}/outreach
```

### Path Parameters

**contractId** `string` *required*

UUID of the contract for which to draft outreach.

### Response

**draft** `object`

The generated email draft, including subject line, body text, and the vendor contact address Tavryn resolved from the contract record.

### Example Response

```json theme={null}
{
  "draft": {
    "to": "procurement@notion.com",
    "subject": "Renewal Discussion — Notion Team Plan",
    "body": "Hi team,\n\nWe're approaching our renewal window for the Notion Team Plan and wanted to open a conversation about pricing for the coming year..."
  }
}
```

***

## Submit a Vendor Reply

Feed a vendor's email response back into Tavryn so the agent can parse their position, update the negotiation state, and formulate the next offer.

```http theme={null}
POST /api/agent/negotiate/{contractId}/reply
```

### Path Parameters

**contractId** `string` *required*

UUID of the contract the reply pertains to.

### Request Body

The endpoint accepts both JSON and `multipart/form-data` (for email webhook ingestion). In form-data payloads, Tavryn looks for `rawReply`, `text`, `body`, or `html` fields.

**rawReply** `string` *required*

The raw text of the vendor's reply. Cannot be empty.

**acceptsUsdcOverride** `boolean`

Set to `true` to manually signal that the vendor has agreed to accept payment in USDC on the Arc network, bypassing the AI's extraction of that consent from the reply text.

### Response

**result** `object`

The parsed reply outcome — detected counter-offer price, sentiment classification, updated negotiation status, and the next action Tavryn will take.

***

## Record Off-Chain Savings

Manually record a negotiated saving when the deal was closed outside Tavryn (phone call, direct email, etc.) without an on-chain USDC payment.

```http theme={null}
POST /api/agent/negotiate/{contractId}/record-savings
```

### Path Parameters

**contractId** `string` *required*

UUID of the contract where savings were achieved.

### Request Body

**negotiationId** `string` *required*

UUID of the negotiation record to close out.

**finalPrice** `number` *required*

The agreed final annual price in USD. Must be positive.

**reason** `string`

Optional free-text note explaining how the deal was closed (e.g., `"Agreed over phone with account manager"`).

### Response

**result** `object`

Confirmation that the negotiation has been marked `completed`, the savings amount recorded, and the contract's `current_price` updated.

### Example Request

```bash theme={null}
curl -X POST https://your-tavryn-instance.com/api/agent/negotiate/a1b2c3d4-e5f6-7890-abcd-ef1234567890/record-savings \
  -H "Content-Type: application/json" \
  -d '{
    "negotiationId": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "finalPrice": 9200,
    "reason": "Agreed via account manager call on 2025-09-15"
  }'
```

### Example Response

```json theme={null}
{
  "result": {
    "negotiation_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "status": "completed",
    "savings_amount": 2800,
    "final_price": 9200,
    "original_price": 12000
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.