The Negotiation Object
The following fields appear in negotiation responses across all endpoints.string
UUID of the negotiation record.
string
UUID of the contract this negotiation is tied to.
string
Current lifecycle state of the negotiation. One of:
number
Number of offer-counter-offer cycles completed so far.
number
The most recent price Tavryn put on the table (in USD).
number
The price Tavryn is aiming to close at, derived from the waste heuristic and market benchmarks.
number
Projected or confirmed annual savings in USD (
original_price - final_price).string | null
Human reviewer decision when the negotiation entered
pending_review or pending_approval. One of:How Negotiations Start
You do not need to open negotiations manually. Tavryn triggers them in two ways:- 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.
- 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 for details.
POST /api/agent/negotiate/{contractId}.
Get Negotiation Status
Retrieve the current negotiation state, full contract record, and vendor memory for a contract.Path Parameters
string
required
UUID of the contract whose negotiation status you want to retrieve.
Response
boolean
true if an active or historical negotiation record exists for this contract.object | null
The negotiation object as described above, or
null if no negotiation has been opened yet.object
The full contract record including the linked vendor.
object | null
Tavryn’s vendor memory for this business — prior negotiation outcomes, concession patterns, and relationship context used to calibrate future offers.
Example Response
Start or Advance a Negotiation
Open a new negotiation or push an existing one forward by submitting a new round with optional parameter overrides.Path Parameters
string
required
UUID of the contract to negotiate.
Request Body
All body fields are optional. Omitting them lets Tavryn use its default negotiation strategy.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.number
Maximum price (in USD) Tavryn will accept before abandoning the negotiation. Must be a positive number. Use this to enforce hard budget caps.
number
Explicit target price (in USD) you want Tavryn to negotiate toward. Overrides the heuristic-derived target.
Response
object
The outcome of the negotiation loop, including the final round state, accepted flag, vendor counter message, and updated savings figures.
Example Request
Draft Vendor Outreach Email
Generate a professional outreach email to kick off a negotiation with a real vendor contact.Path Parameters
string
required
UUID of the contract for which to draft outreach.
Response
object
The generated email draft, including subject line, body text, and the vendor contact address Tavryn resolved from the contract record.
Example Response
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.Path Parameters
string
required
UUID of the contract the reply pertains to.
Request Body
The endpoint accepts both JSON andmultipart/form-data (for email webhook ingestion). In form-data payloads, Tavryn looks for rawReply, text, body, or html fields.
string
required
The raw text of the vendor’s reply. Cannot be empty.
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
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.Path Parameters
string
required
UUID of the contract where savings were achieved.
Request Body
string
required
UUID of the negotiation record to close out.
number
required
The agreed final annual price in USD. Must be positive.
string
Optional free-text note explaining how the deal was closed (e.g.,
"Agreed over phone with account manager").Response
object
Confirmation that the negotiation has been marked
completed, the savings amount recorded, and the contract’s current_price updated.