Skip to main content

​
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

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
  }'
SettingDescription
staleness_budget_secondsSeconds since sync before content is stale
enforce_stalenessWhether to filter stale results

​
Common Values

DaysSecondsUse Case
7604800Fast-changing APIs
141209600Active development
302592000Default, stable docs
907776000Archival 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
PriorityEffect
> 1.0Boosted in ranking
1.0Neutral
< 1.0Penalized in ranking
0.0Effectively 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

SettingDescription
min_evidence_countMinimum number of results required
min_evidence_scoreMinimum score for top result
enforce_refusalWhether 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

The default policy is a good starting point. Adjust after observing real search behavior.
enforce_refusal: true can be frustrating if thresholds are too strict. Start with it disabled and enable once you have sufficient content indexed.
If you’re building an API assistant, boost OpenAPI. For a code search tool, boost repos.
If you see frequent staleness warnings, either increase sync frequency or increase the staleness budget.