> ## 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.

# Search API

> Search indexed content with citations

# Search API

Search across all indexed sources with hybrid retrieval.

## Search

<ParamField query="query" type="string" required>
  Search query
</ParamField>

<ParamField query="source_ids" type="string">
  Comma-separated source IDs to filter (optional)
</ParamField>

<ParamField query="max_tokens" type="integer">
  Maximum total tokens in results (default: 4000, max: 32000)
</ParamField>

<ParamField query="top_k" type="integer">
  Maximum number of results (default: 10, max: 50)
</ParamField>

<ParamField query="include_stale" type="boolean">
  Include stale results with warning (default: true)
</ParamField>

<RequestExample>
  ```bash theme={null}
  # GET request
  curl "https://api.trygroundai.com/search?query=how+to+authenticate&top_k=10" \
    -H "Authorization: Bearer gnd_your_api_key"

  # 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"]
    }'
  ```
</RequestExample>

For deeper retrieval (neighbor expansion + optional second pass), use **[RMH search](/api-reference/rmh-search)** (`POST /search/rmh`).

<ResponseExample>
  ```json theme={null}
  {
    "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
  }
  ```
</ResponseExample>

## Response Fields

### SearchResult

| Field            | Type     | Description             |
| ---------------- | -------- | ----------------------- |
| `content`        | string   | Chunk content           |
| `score`          | float    | Relevance score (0-1+)  |
| `token_count`    | integer  | Tokens in this result   |
| `citation`       | Citation | Provenance information  |
| `freshness_days` | float    | Days since source sync  |
| `is_stale`       | boolean  | Whether source is stale |

### Citation

| Field         | Type    | Description                   |
| ------------- | ------- | ----------------------------- |
| `chunk_id`    | string  | Unique chunk ID               |
| `source_id`   | string  | Source ID                     |
| `source_name` | string  | Source name                   |
| `path`        | string  | File path or URL              |
| `symbol`      | string  | Function/class/operation name |
| `start_line`  | integer | Start line (code only)        |
| `end_line`    | integer | End line (code only)          |
| `version_ref` | string  | Commit SHA or version         |
| `language`    | string  | Language/format               |
| `chunk_type`  | string  | `code`, `docs`, `openapi`     |

### EvidenceQuality

| Field                | Type    | Description                             |
| -------------------- | ------- | --------------------------------------- |
| `score`              | float   | Quality score (0-1)                     |
| `evidence_count`     | integer | Number of results                       |
| `avg_freshness_days` | float   | Average age                             |
| `has_conflicts`      | boolean | Conflicts detected                      |
| `confidence`         | string  | `high`, `medium`, `low`, `insufficient` |

### Conflict

| Field           | Type      | Description                |
| --------------- | --------- | -------------------------- |
| `endpoint_key`  | string    | Conflicting endpoint       |
| `sources`       | string\[] | Sources involved           |
| `schema_hashes` | string\[] | Different schema hashes    |
| `description`   | string    | Human-readable description |

## No Evidence Response

When no relevant content is found:

```json theme={null}
{
  "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"
  ]
}
```