Run Procurement Scan
Trigger an immediate full procurement cycle — the same job the daily cron runs — for one or all businesses. Tavryn scans every active contract, scores each for savings potential, and opens negotiation rounds for any contract that clears the minimum-savings policy threshold.Request Body
string
UUID of a specific business to scan. When omitted, Tavryn runs the procurement cycle for all businesses registered in the system.
boolean
default:"false"
Set to
true to bypass the idempotency guard and re-evaluate all contracts even if they were scanned recently. Useful for testing and for forcing a re-scan after you update contract data.Response
string
Human-readable summary of what the agent did (e.g.,
"Agent executed: 3 negotiations initiated, 3 notifications created.").object
Structured outcome of the scan.
Example Request
Example Response
Status Codes
Analyze a Contract
Run Tavryn’s full waste-detection analysis on a single contract. The agent evaluates seat utilization, usage telemetry, market benchmarks, and renewal proximity to produce a scored opportunity report — without opening a negotiation round.Analysis is read-only and never mutates contract or negotiation records. Use it to preview savings potential before committing to a negotiation.
Path Parameters
string
required
UUID of the contract to analyze.
Rate Limit
20 requests per minute percontractId. Returns HTTP 429 with resetMs on breach.
Response
object
The full analysis report for the contract.
Example Request
Example Response
Run a Negotiation Loop
Execute one or more offer-counter-offer rounds against the vendor for a specific contract. See the Negotiations API for the full reference — this is a summary of the endpoint signature.Path Parameters
string
required
UUID of the contract to negotiate.
POST Request Body (all optional)
number
Maximum rounds before Tavryn walks away. Integer
1–20.number
Hard upper price limit in USD. Tavryn cancels the negotiation if it cannot get the vendor below this number.
number
Explicit target price in USD. Overrides the heuristic-derived target.
Rate Limit
20 requests per minute percontractId on POST. No rate limit on GET.
Ask Tavryn (Command Bar)
Send a natural-language question or instruction to Tavryn and receive a structured answer — the same engine that powers the Cmd+K command bar in the dashboard. Supports both streaming (Server-Sent Events) and standard JSON responses.Request Body
string
required
The question or instruction for Tavryn. Maximum 2,000 characters. Examples:
"Which contracts renew in the next 30 days?", "Start a negotiation for Notion", "How much have we saved this quarter?".string
UUID of the business context to query. When omitted, Tavryn resolves the first available business automatically.
boolean
default:"true"
Set to
false to receive a single JSON response instead of a Server-Sent Events stream. Streaming is recommended for UI integrations to display typewriter-style output.array
Up to 10 prior conversation turns to maintain context across multi-turn queries. Each turn is an object with
role ("user" or "assistant") and content (string, max 2,000 chars).Rate Limit
30 requests per minute per business. Returns HTTP429 with resetMs on breach.
Streaming Response (SSE)
Whenstream is true and the Accept header includes text/event-stream or */*, the response is a text/event-stream with three event types:
SSE event
Incremental text fragment. Contains
chunk (the new words), and fullText (the full response so far).SSE event
A structured data card for rendering rich UI components (tables, charts, action buttons). Present only when the query returns actionable structured data.
SSE event
Terminal event signalling the response is complete.
JSON Response (non-streaming)
string
The full natural-language response from Tavryn.
object | null
Structured data card, if applicable.
array
List of internal tool names Tavryn invoked to answer the question (for debugging and audit purposes).
string
The business UUID the response was scoped to.
Example Request (streaming)
Example Request (JSON)
Example JSON Response
Confirm a Command Action
When a command bar query results in a suggested action (e.g., “Start a negotiation for Notion”), Tavryn returns a confirmation prompt before executing. Use this endpoint to confirm and execute that action.Request Body
string
required
The action to execute. Must be one of:
string
UUID of the business context. Resolved automatically if omitted.
object
Key-value parameters required by the action (e.g.,
{ "contractId": "..." } for start_negotiation). Defaults to {}.Response
string
The action that was executed.
boolean
true if the action completed without error.string
Human-readable description of what was done.
object
Action-specific result data (e.g., the new negotiation record for
start_negotiation).