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

# Business Settings API: Manage Policies and Config

> Retrieve and update your business's procurement policy, webhook URL, and spending configuration. Includes a live webhook test endpoint.

The Business Settings API gives you programmatic control over the rules that govern how Tavryn's autonomous agent behaves on your behalf. Through this API you can tune the monetary thresholds that determine when the agent acts autonomously versus when it pauses for human approval, configure per-category spending budgets, and connect a webhook URL for real-time notifications. Changes take effect immediately — the agent reads your policy on every decision cycle.

***

## GET /api/business/{id}/settings

Retrieve the current configuration for a business, including both the business profile (wallet address, treasury balance, notification settings) and the full policy rule set.

**Path parameters**

**id** `string` *required*

UUID of the business whose settings you want to retrieve.

**Response fields**

**business** `object`

**business fields**

**id** `string`

UUID of the business.

**name** `string`

Display name of the organization.

**wallet\_address** `string`

The Arc-network wallet address used for USDC settlements.

**default\_currency** `string`

Default currency for reporting. Typically `"USD"`.

**treasury\_balance** `number`

Current USDC balance in the business treasury wallet, in USD.

**webhook\_url** `string | null`

The URL where Tavryn sends event notifications. `null` if no webhook is configured.

**policy** `object`

**policy fields**

**max\_auto\_transaction** `number`

Maximum USDC amount (in USD) that the agent can commit to a single transaction without requiring human approval. Transactions above this threshold are paused and an approval token is dispatched to the reviewer. Default: `2000`.

**min\_savings** `number`

Minimum dollar savings (in USD) that a negotiation must achieve before the agent is allowed to proceed. If the negotiated saving falls below this floor, the agent abandons the cycle. Default: `200`.

**human\_approval\_required\_above** `number`

Dollar threshold above which every transaction — regardless of savings — requires a human one-tap approval before execution. Typically set equal to `max_auto_transaction`. Default: `2000`.

**allowed\_categories** `array of strings`

The spend categories in which the agent is permitted to negotiate. The agent will not touch contracts in categories outside this list.

**category\_budgets** `object`

Per-category annual spending ceilings as a key-value map. Keys are category names; values are USD amounts. Example: `{ "software": 25000, "cloud": 50000 }`.

> [!NOTE]
>
> Valid values for `allowed_categories` are: `software`, `cloud`, `contractors`, `infrastructure`, `legal`, and `marketing`. Any category not in this list will be rejected by the settings validation layer.

**Example request**

```bash theme={null}
curl https://tavryn.network/api/business/biz-uuid/settings
```

**Example response**

```json theme={null}
{
  "business": {
    "id": "biz-uuid",
    "name": "Acme Corp",
    "wallet_address": "0xAbCd1234...",
    "default_currency": "USD",
    "treasury_balance": 85000,
    "webhook_url": "https://hooks.acmecorp.com/tavryn"
  },
  "policy": {
    "max_auto_transaction": 5000,
    "min_savings": 500,
    "human_approval_required_above": 5000,
    "allowed_categories": ["software", "cloud", "contractors"],
    "category_budgets": {
      "software": 25000,
      "cloud": 50000,
      "contractors": 25000
    }
  }
}
```

**Error responses**

| Status | Condition |
| - | - |
| `400` | Missing or malformed business ID |
| `404` | Business not found |

***

## PUT /api/business/{id}/settings

Update your business's webhook URL and/or procurement policy. You can update either field independently — omit the key you don't want to change. All updates are written to the database and logged to the immutable audit trail.

**Path parameters**

**id** `string` *required*

UUID of the business to update.

**Request body**

**webhook\_url** `string | null`

New webhook URL for Tavryn notifications. Must be a valid HTTPS URL. Pass `null` or an empty string `""` to remove the current webhook.

**policy** `object`

**policy fields**

**max\_auto\_transaction** `number` *required*

Maximum USDC transaction amount (USD) the agent can execute autonomously. Must be ≥ 0.

**min\_savings** `number` *required*

Minimum acceptable savings in USD for a negotiation to proceed. Must be ≥ 0.

**human\_approval\_required\_above** `number` *required*

USD threshold above which human approval is mandatory. Must be ≥ 0.

**allowed\_categories** `array of strings` *required*

Categories the agent may negotiate in. Must include at least one value. Valid values: `software`, `cloud`, `contractors`, `infrastructure`, `legal`, `marketing`.

**category\_budgets** `object`

Key-value map of category name to annual USD budget ceiling. Optional — if omitted, defaults to `{ software: 25000, cloud: 50000, contractors: 25000 }`.

**Example request — update policy thresholds**

```bash theme={null}
curl -X PUT https://tavryn.network/api/business/biz-uuid/settings \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "max_auto_transaction": 10000,
      "min_savings": 1000,
      "human_approval_required_above": 10000,
      "allowed_categories": ["software", "cloud", "infrastructure"],
      "category_budgets": {
        "software": 50000,
        "cloud": 100000,
        "infrastructure": 30000
      }
    }
  }'
```

**Example request — update webhook URL only**

```bash theme={null}
curl -X PUT https://tavryn.network/api/business/biz-uuid/settings \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://hooks.acmecorp.com/tavryn-v2" }'
```

**Example response**

```json theme={null}
{
  "message": "Settings updated successfully",
  "businessId": "biz-uuid"
}
```

**Error responses**

| Status | Condition |
| - | - |
| `400` | Malformed JSON, invalid URL format, or policy validation failure |
| `404` | Business not found |

***

## POST /api/business/{id}/settings

Fire a live test notification to a webhook URL. Use this to verify connectivity before saving a new webhook endpoint, or to re-test an existing one after infrastructure changes. Tavryn dispatches a test message to the target URL and reports whether delivery succeeded.

**Path parameters**

**id** `string` *required*

UUID of the business performing the test.

**Request body**

**webhook\_url** `string` *required*

The URL to send the test notification to. This does not need to match the currently saved `webhook_url` — you can test any URL before committing it.

**Response fields**

**sent** `boolean`

`true` if the test notification was delivered successfully; `false` if the target URL was unreachable or returned an error.

**reason** `string`

Human-readable description of the delivery result. Present whether the test succeeded or failed.

**message** `string`

Summary message confirming the test was dispatched.

**Example request**

```bash theme={null}
curl -X POST https://tavryn.network/api/business/biz-uuid/settings \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://hooks.acmecorp.com/tavryn-test" }'
```

**Example response — success**

```json theme={null}
{
  "sent": true,
  "reason": "OK",
  "message": "Webhook test notification dispatched successfully"
}
```

**Example response — failure**

```json theme={null}
{
  "sent": false,
  "reason": "Connection refused",
  "message": "Webhook test completed: Connection refused"
}
```

> [!TIP]
>
> Always test your webhook before storing it with `PUT`. The test endpoint sends a clearly labelled `🔔 Tavryn Webhook Integration Test` message so your receiving server can identify and handle it separately from live procurement events.

**Error responses**

| Status | Condition |
| - | - |
| `400` | Missing `webhook_url` in request body |
| `500` | Internal error dispatching the test notification |


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