# Policies

Spending policies define the rules governing what an agent vault can spend, how fast, and with whom. Policy enforcement is on-chain — changes applied via this API take effect within one Solana slot.

***

## Create a policy

`POST /v1/policies`

```bash
curl -X POST https://api.therosai.com/v1/policies \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conservative — Research Agent",
    "maxPerTx": "5.00",
    "maxPerDay": "50.00",
    "maxPerMonth": "500.00",
    "velocityCap": 20,
    "allowedRecipients": [
      "api.perplexity.ai",
      "api.tavily.com"
    ]
  }'
```

**Request body — all parameters**

| Field               | Type      | Required | Description                                                        |
| ------------------- | --------- | -------- | ------------------------------------------------------------------ |
| `name`              | string    | Yes      | Human-readable policy name.                                        |
| `maxPerTx`          | string    | No       | Max USDC per single transaction.                                   |
| `maxPerDay`         | string    | No       | Rolling 24-hour spend ceiling.                                     |
| `maxPerMonth`       | string    | No       | Calendar-month spend ceiling.                                      |
| `allowedRecipients` | string\[] | No       | Explicit recipient allowlist. Empty array = any recipient allowed. |
| `blockedCategories` | string\[] | No       | Category codes to block.                                           |
| `velocityCap`       | integer   | No       | Max transactions per hour.                                         |
| `expiry`            | string    | No       | ISO 8601 timestamp. Vault freezes after this time.                 |
| `requireCoSign`     | string    | No       | USDC threshold above which operator co-signature is required.      |

**Response `200 OK`**

```json
{
  "policy_id": "pol_7a2c4e",
  "name": "Conservative — Research Agent",
  "max_per_tx": "5.00",
  "max_per_day": "50.00",
  "max_per_month": "500.00",
  "velocity_cap": 20,
  "allowed_recipients": ["api.perplexity.ai", "api.tavily.com"],
  "blocked_categories": [],
  "require_co_sign": null,
  "expiry": null,
  "wallet_count": 0,
  "created_at": "2026-04-29T12:00:00Z"
}
```

***

## Get a policy

`GET /v1/policies/{policy_id}`

```bash
curl https://api.therosai.com/v1/policies/pol_7a2c4e \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

***

## List policies

`GET /v1/policies`

```bash
curl https://api.therosai.com/v1/policies \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

Returns all policies in the organisation, including TherosAI presets.

***

## Update a policy

`PATCH /v1/policies/{policy_id}`

Changes propagate to all vaults using this policy within one Solana slot (\~400ms). All changes are recorded in the policy audit log.

```bash
curl -X PATCH https://api.therosai.com/v1/policies/pol_7a2c4e \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxPerDay": "75.00",
    "velocityCap": 30
  }'
```

TherosAI preset policies (`pol_conservative`, `pol_moderate`, `pol_permissive`, `pol_locked`) cannot be updated. Clone them to create a custom variant.

***

## Clone a policy

`POST /v1/policies/{policy_id}/clone`

Creates a new, editable policy based on an existing one.

```bash
curl -X POST https://api.therosai.com/v1/policies/pol_conservative/clone \
  -H "Authorization: Bearer $THEROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conservative + Perplexity only",
    "allowedRecipients": ["api.perplexity.ai"]
  }'
```

***

## Delete a policy

`DELETE /v1/policies/{policy_id}`

A policy cannot be deleted while any vault is attached to it. Reassign all vaults to a different policy before deleting.

```bash
curl -X DELETE https://api.therosai.com/v1/policies/pol_7a2c4e \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

***

## Policy audit log

`GET /v1/policies/{policy_id}/audit-log`

Returns a chronological log of all changes to this policy.

```bash
curl https://api.therosai.com/v1/policies/pol_7a2c4e/audit-log \
  -H "Authorization: Bearer $THEROS_API_KEY"
```

**Response**

```json
{
  "data": [
    {
      "timestamp": "2026-04-29T14:00:00Z",
      "changed_by": "user_abc123",
      "changes": {
        "max_per_day": { "from": "50.00", "to": "75.00" },
        "velocity_cap": { "from": 20, "to": 30 }
      }
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.therosai.com/api-reference/policies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.