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:

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

Getting the Current Policy

curl https://api.trygroundai.com/policy \
  -H "Authorization: Bearer gnd_your_api_key"

Response:

{
  "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

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

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):

{
  "repo": 0.8,
  "docs_html": 0.6,
  "docs_openapi": 1.5
}

Code-focused search (boost repos):

{
  "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

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:

{
  "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:

curl -X POST https://api.trygroundai.com/policy/reset \
  -H "Authorization: Bearer gnd_your_api_key"

Best Practices

Start with defaults

The default policy is a good starting point. Adjust after observing real search behavior.

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.

Adjust priorities for your use case

If you’re building an API assistant, boost OpenAPI. For a code search tool, boost repos.

Monitor staleness

If you see frequent staleness warnings, either increase sync frequency or increase the staleness budget.

Getting Started

Core Concepts

Guides

Trust Policy

Trust Policy

Overview

Getting the Current Policy

Staleness Budget

Configuration

Common Values

Behavior

Source Priorities

Configuration

How It Works

Example Use Cases

Refusal Thresholds

Configuration

Settings

Behavior

Resetting Policy

Best Practices

​Trust Policy

​Overview

​Getting the Current Policy

​Staleness Budget

​Configuration

​Common Values

​Behavior

​Source Priorities

​Configuration

​How It Works

​Example Use Cases

​Refusal Thresholds

​Configuration

​Settings

​Behavior

​Resetting Policy

​Best Practices

Trust Policy

Overview

Getting the Current Policy

Staleness Budget

Configuration

Common Values

Behavior

Source Priorities

Configuration

How It Works

Example Use Cases

Refusal Thresholds

Configuration

Settings

Behavior

Resetting Policy

Best Practices