> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygroundai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Policy

> Configure staleness budgets, source priorities, and refusal thresholds

# Trust Policy

The trust policy controls how Ground handles search results, including staleness filtering, source prioritization, and refusal thresholds.

## Overview

Ground's trust policy answers:

1. **How old is too old?** → Staleness budget
2. **Which sources matter more?** → Source priorities
3. **When should we refuse to answer?** → Refusal thresholds

## Getting the Current Policy

```bash theme={null}
curl https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key"
```

Response:

```json theme={null}
{
  "id": "default",
  "name": "default",
  "staleness_budget_seconds": 2592000,
  "staleness_budget_days": 30,
  "source_priorities": {
    "repo": 1.0,
    "docs_html": 0.8,
    "docs_openapi": 1.2
  },
  "min_evidence_count": 1,
  "min_evidence_score": 0.3,
  "enforce_staleness": true,
  "enforce_refusal": false,
  "created_at": "2026-01-17T00:00:00Z",
  "updated_at": "2026-01-17T00:00:00Z"
}
```

## Staleness Budget

Controls when content is considered stale.

### Configuration

```bash theme={null}
curl -X PUT https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "staleness_budget_seconds": 604800,
    "enforce_staleness": true
  }'
```

| Setting                    | Description                                |
| -------------------------- | ------------------------------------------ |
| `staleness_budget_seconds` | Seconds since sync before content is stale |
| `enforce_staleness`        | Whether to filter stale results            |

### Common Values

| Days | Seconds | Use Case             |
| ---- | ------- | -------------------- |
| 7    | 604800  | Fast-changing APIs   |
| 14   | 1209600 | Active development   |
| 30   | 2592000 | Default, stable docs |
| 90   | 7776000 | Archival content     |

### Behavior

When `enforce_staleness: true`:

* Stale results marked with `is_stale: true`
* Warning added to response
* If search request has `include_stale: false`, stale results filtered out

When `enforce_staleness: false`:

* All results included regardless of age
* No staleness warnings

## Source Priorities

Control which source types rank higher in results.

### Configuration

```bash theme={null}
curl -X PUT https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_priorities": {
      "repo": 1.0,
      "docs_html": 0.8,
      "docs_openapi": 1.5
    }
  }'
```

### How It Works

Source priority is a multiplier applied to the combined search score:

```
weighted_score = combined_score × source_priority
```

| Priority | Effect                   |
| -------- | ------------------------ |
| > 1.0    | Boosted in ranking       |
| 1.0      | Neutral                  |
| \< 1.0   | Penalized in ranking     |
| 0.0      | Effectively filtered out |

### Example Use Cases

**API-focused search** (boost OpenAPI):

```json theme={null}
{
  "repo": 0.8,
  "docs_html": 0.6,
  "docs_openapi": 1.5
}
```

**Code-focused search** (boost repos):

```json theme={null}
{
  "repo": 1.5,
  "docs_html": 0.8,
  "docs_openapi": 1.0
}
```

## Refusal Thresholds

Control when Ground refuses to return results due to insufficient evidence.

### Configuration

```bash theme={null}
curl -X PUT https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "min_evidence_count": 2,
    "min_evidence_score": 0.5,
    "enforce_refusal": true
  }'
```

### Settings

| Setting              | Description                         |
| -------------------- | ----------------------------------- |
| `min_evidence_count` | Minimum number of results required  |
| `min_evidence_score` | Minimum score for top result        |
| `enforce_refusal`    | Whether to enforce these thresholds |

### Behavior

When thresholds aren't met and `enforce_refusal: true`:

```json theme={null}
{
  "message": "Insufficient evidence to provide a confident answer",
  "query": "obscure topic",
  "sources_searched": 0,
  "suggestions": [
    "Found 1 result(s) but policy requires at least 2",
    "Max evidence score 0.35 below policy threshold 0.5",
    "Add more relevant sources or adjust trust policy via PUT /policy"
  ]
}
```

## Resetting Policy

Reset all settings to defaults:

```bash theme={null}
curl -X POST https://api.trygroundai.com/policy/reset \
  -H "Authorization: Bearer gnd_your_api_key"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start with defaults">
    The default policy is a good starting point. Adjust after observing real search behavior.
  </Accordion>

  <Accordion title="Use refusal thresholds carefully">
    `enforce_refusal: true` can be frustrating if thresholds are too strict. Start with it disabled and enable once you have sufficient content indexed.
  </Accordion>

  <Accordion title="Adjust priorities for your use case">
    If you're building an API assistant, boost OpenAPI. For a code search tool, boost repos.
  </Accordion>

  <Accordion title="Monitor staleness">
    If you see frequent staleness warnings, either increase sync frequency or increase the staleness budget.
  </Accordion>
</AccordionGroup>