Skip to main content
The Agent API gives you direct access to the autonomous engine that powers Tavryn. Use it to kick off full procurement scans on demand, deep-dive into a single contract’s waste profile, drive negotiation rounds, and query Tavryn conversationally through the same command bar exposed by the Cmd+K interface. Every endpoint is idempotent-safe and rate-limited so you can integrate it safely into CI pipelines, internal tools, and webhook handlers.

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.
This endpoint is rate-limited to 10 requests per minute across all callers. Exceeding the limit returns HTTP 429 with a resetMs field (milliseconds until the window resets). Space your calls accordingly in automation scripts.
Pass "force": true during development and testing to override the agent’s idempotency window. Without force, Tavryn skips contracts it has already evaluated within the current cycle to avoid duplicate negotiations. Setting force: true re-evaluates every contract regardless of prior scan timestamps.

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 per contractId. 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 per contractId 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 HTTP 429 with resetMs on breach.

Streaming Response (SSE)

When stream 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).

Example Request

Example Response