Skip to main content

​
Search API

Search across all indexed sources with hybrid retrieval.
​
query
string
required
Search query
​
source_ids
string
Comma-separated source IDs to filter (optional)
​
max_tokens
integer
Maximum total tokens in results (default: 4000, max: 32000)
​
top_k
integer
Maximum number of results (default: 10, max: 50)
​
include_stale
boolean
Include stale results with warning (default: true)
# GET request
curl "https://api.trygroundai.com/search?query=how+to+authenticate&top_k=10"

# POST request
curl -X POST https://api.trygroundai.com/search \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to authenticate",
    "top_k": 10,
    "max_tokens": 4000,
    "source_ids": ["source-uuid-1", "source-uuid-2"]
  }'

{
  "results": [
    {
      "content": "# POST /auth/login\nOperation ID: login\n\nAuthenticate with username and password...",
      "score": 0.92,
      "token_count": 150,
      "citation": {
        "chunk_id": "chunk-uuid",
        "source_id": "source-uuid",
        "source_name": "Auth API",
        "path": "https://api.example.com/openapi.json",
        "symbol": "login",
        "version_ref": "v2.0.0",
        "language": "openapi",
        "chunk_type": "openapi"
      },
      "freshness_days": 5.2,
      "is_stale": false
    }
  ],
  "total_results": 10,
  "total_tokens": 1500,
  "sources_searched": 3,
  "sources_with_results": 2,
  "evidence_quality": {
    "score": 0.75,
    "evidence_count": 10,
    "avg_freshness_days": 8.5,
    "has_conflicts": false,
    "confidence": "high"
  },
  "staleness_summary": {
    "total_sources": 3,
    "fresh_sources": 2,
    "stale_sources": 1,
    "staleness_budget_days": 30,
    "stale_source_names": ["Old Docs"]
  },
  "conflicts": [],
  "warnings": [],
  "query": "how to authenticate",
  "search_time_ms": 45
}

​
Response Fields

​
SearchResult

FieldTypeDescription
contentstringChunk content
scorefloatRelevance score (0-1+)
token_countintegerTokens in this result
citationCitationProvenance information
freshness_daysfloatDays since source sync
is_stalebooleanWhether source is stale

​
Citation

FieldTypeDescription
chunk_idstringUnique chunk ID
source_idstringSource ID
source_namestringSource name
pathstringFile path or URL
symbolstringFunction/class/operation name
start_lineintegerStart line (code only)
end_lineintegerEnd line (code only)
version_refstringCommit SHA or version
languagestringLanguage/format
chunk_typestringcode, docs, openapi

​
EvidenceQuality

FieldTypeDescription
scorefloatQuality score (0-1)
evidence_countintegerNumber of results
avg_freshness_daysfloatAverage age
has_conflictsbooleanConflicts detected
confidencestringhigh, medium, low, insufficient

​
Conflict

FieldTypeDescription
endpoint_keystringConflicting endpoint
sourcesstring[]Sources involved
schema_hashesstring[]Different schema hashes
descriptionstringHuman-readable description

​
No Evidence Response

When no relevant content is found: 
{
  "message": "No relevant evidence found",
  "query": "obscure query",
  "sources_searched": 5,
  "suggestions": [
    "Try a broader or different query",
    "Check if relevant sources are synced",
    "Sources older than 30 days are filtered - sync stale sources"
  ]
}