> ## 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.

# Tavryn REST API — Endpoints & Response Format

> A complete reference for Tavryn's REST API: response envelopes, HTTP status codes, rate limits, and every available endpoint grouped by function.

The Tavryn REST API lets you drive the full procurement automation lifecycle programmatically: ingest SaaS and cloud contracts, trigger autonomous negotiation agents, approve spending decisions, query USDC wallet balances, and retrieve verified savings receipts. All API routes are served from your Tavryn deployment URL and every response is JSON.

## Base URL

All API endpoints are relative to your Tavryn deployment URL. Replace `<your-deployment-url>` in every example with the origin of your Tavryn instance (for example, `https://tavryn.app` if you are using the hosted service).

```
https://<your-deployment-url>
```

> [!NOTE]
>
> If you are using the Tavryn hosted service, your base URL is `https://tavryn.app`. Self-hosted deployments use the domain you configured during setup.

## Response Envelope

Every Tavryn endpoint wraps its payload in a standard envelope so you can check `success` before processing `data`.

**Successful response**

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

**Error response**

```json theme={null}
{
  "success": false,
  "error": "A human-readable error message",
  "details": [ ... ]
}
```

The optional `details` field appears on validation errors and carries structured diagnostic information — for example, the list of specific fields that failed schema validation. For non-validation errors `details` is omitted.

## HTTP Status Codes

| Status | Meaning |
| - | - |
| `200` | Request succeeded |
| `201` | Resource created |
| `400` | Bad request — invalid or missing parameters |
| `401` | Unauthorized — not authenticated |
| `403` | Forbidden — authenticated but not permitted for this resource |
| `404` | Not found — the requested resource does not exist |
| `429` | Too many requests — rate limit exceeded |
| `500` | Internal server error |

## Rate Limiting

Tavryn uses a **sliding-window rate limiter** on agent and cron routes to protect the autonomous pipeline from runaway callers. When you exceed the limit, the API returns HTTP `429` with a `resetMs` field indicating exactly how many milliseconds remain before your window resets.

> [!WARNING]
>
> Different agent routes carry different per-minute limits. `POST /api/agent/run-now` and `GET /api/cron/daily` are the most restrictive at **10 requests per minute**. Other agent sub-routes (analyze, negotiate, reply, command) allow **20–30 requests per minute**. Always implement backoff logic using the `resetMs` value returned in the `429` response body.

**HTTP 429 response body**

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded",
  "details": {
    "resetMs": 43200
  }
}
```

| Field | Type | Description |
| - | - | - |
| `resetMs` | `number` | Milliseconds until the oldest request exits the sliding window and a new slot opens |

## Available Endpoints

### Contracts

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/contracts` | Create or update a SaaS/cloud contract record for the agent to monitor |

### Agent

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/agent/run-now` | Trigger the full autonomous procurement loop immediately (rate-limited to 10 req/min) |
| `POST` | `/api/agent/negotiate/[contractId]` | Start or continue a multi-round vendor negotiation for a contract (rate-limited to 20 req/min) |
| `POST` | `/api/agent/analyze/[contractId]` | Run waste analysis and NPV comparison for a contract (rate-limited to 20 req/min) |
| `POST` | `/api/agent/command` | Send a natural-language command to the Tavryn agent via the Command Bar (rate-limited to 30 req/min) |

### Approvals

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/approve/[token]` | Preview a pending 1-tap HMAC approval link (read-only) |
| `POST` | `/api/approve/[token]` | Consume an approval token to authorize a spending decision |
| `GET` | `/api/approvals/count` | Return the count of pending approvals for your organization |

### Transactions & Receipts

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/receipts` | List verified savings receipts for your organization |
| `GET` | `/api/metrics` | Retrieve aggregated savings and spend metrics |

### Business & Settings

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/business/{id}/settings` | Fetch organization settings and spending policies |
| `PUT` | `/api/business/{id}/settings` | Update organization settings and spending policies |
| `POST` | `/api/business/{id}/settings` | Send a test notification to your configured webhook URL |

### Wallet

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/wallet/balance` | Query your organization's USDC balance on the Arc network |

### Import

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/import/file` | Upload a CSV or spreadsheet of contracts for bulk ingestion |

### Webhooks

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/webhooks/circle` | Receive Circle payment event notifications (Circle-signed only) |

### Cron (Server-to-Server)

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/cron/daily` | Trigger the daily renewal evaluation pipeline (requires `CRON_SECRET`, rate-limited to 10 req/min) |
| `GET` | `/api/cron/weekly` | Trigger the weekly procurement summary pipeline (requires `CRON_SECRET`) |

### Demo

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/demo/session` | Initialize a sandboxed demo session without requiring sign-in |
| `POST` | `/api/demo/reset-and-run` | Reset demo data and execute the full 7-stage autonomous loop |

> [!NOTE]
>
> All endpoints (except `/api/demo/session` and `/api/demo/reset-and-run`) require an authenticated session or the appropriate secret header. See the [Authentication](https://tavryn.mintlify.site/api-reference/authentication.md) page for details.

## Explore the Reference

> [card] [Authentication](https://tavryn.mintlify.site/api-reference/authentication.md)
>
> Learn how session cookies, the `businessId` tenant scope, and the `CRON_SECRET` header work together to authenticate every API call.

> [card] [Contracts](https://tavryn.mintlify.site/api-reference/contracts.md)
>
> Create and manage the SaaS and cloud contracts that Tavryn monitors for upcoming renewal waste.

> [card] [Agent](https://tavryn.mintlify.site/api-reference/agent.md)
>
> Trigger autonomous negotiation, waste analysis, and the full procurement loop on demand.

> [card] [Approvals](https://tavryn.mintlify.site/api-reference/approvals.md)
>
> Preview and consume cryptographically signed 1-tap approval links for spending decisions.

> [card] [Wallet & Receipts](https://tavryn.mintlify.site/api-reference/transactions.md)
>
> Query your USDC balance on the Arc network and retrieve verified savings receipts.

> [card] [Business Settings](https://tavryn.mintlify.site/api-reference/business-settings.md)
>
> Fetch and update your organization's spending policies and category budgets.


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