GroundRoute

https://groundroute.ai/docs
Admin
GroundRoute is a unified search API across multiple search engines that provides price-led routing,...
Tokens:17,630
Snippets:129
Trust Score:4.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /console/keys

Source: https://groundroute.ai/docs/authentication

Lists all API keys for the tenant, returning metadata only (never the key itself).

```APIDOC
## GET /console/keys

### Description
Lists all API keys for the tenant, returning metadata only (never the key itself).

### Method
GET

### Endpoint
/console/keys

### Response
#### Success Response (200)
- **id** (string) - The key ID.
- **key_prefix** (string) - A masked display prefix.
- **name** (string) - The key name.
- **status** (string) - The key status.
- **created_at** (string) - Creation timestamp.
- **last_used_at** (string) - Last used timestamp.

#### Response Example
[
  {
    "id": "…",
    "key_prefix": "gr_live…XYZ9",
    "name": "production",
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "last_used_at": "2023-01-02T00:00:00Z"
  }
]
```

--------------------------------

### MCP Server Configuration

Source: https://groundroute.ai/docs/mcp-server

Configuration example for connecting an MCP client to the GroundRoute MCP server.

```APIDOC
## MCP Server Configuration

### Description
Configuration for connecting an MCP client to the GroundRoute MCP server.

### Endpoint
https://api.groundroute.ai/mcp

### Transport
streamable HTTP

### Authentication
Authorization: Bearer <api_key>

### Configuration Example
{
  "mcpServers": {
    "groundroute": {
      "type": "http",
      "url": "https://api.groundroute.ai/mcp",
      "headers": { "Authorization": "Bearer gr_live_YOUR_KEY" }
    }
  }
}
```

--------------------------------

### GET /v1/usage

Source: https://groundroute.ai/docs/search-api

Documentation for the GET /v1/usage endpoint, including response and error handling.

```APIDOC
## GET /v1/usage

### Description
Returns a usage summary for the authenticated tenant. Detailed usage analytics are exposed through the console API under `/v1/console`.

### Method
GET

### Endpoint
/v1/usage

### Response
#### Success Response (200)
- **usage summary** (object) - Usage summary for the authenticated tenant.

#### Response Example
```json
{
  "usage": {}
}
```

### Error Handling
Errors use the standard error envelope:
```json
{
  "error": {
    "type": "auth",
    "message": "…",
    "request_id": "…",
    "retryable": false
  }
}
```

| Status | When |
|--------|------|
| `401` | Missing / invalid / revoked key (`auth`). |
| `402` | Billing block — insufficient credit, no-free-managed, free cap exceeded, or spend hard-stop (`invalid_request`). |
| `403` | Account inactive (`invalid_request`). |
| `422` | Invalid request body. |
| `429` | Rate limit or concurrency cap (`rate_limit`). |
| `500` | Internal error (`unavailable`, retryable). |
| `200` + `degraded: true` | Partial results — one engine failed but at least one returned. **Not** an error. |
```

--------------------------------

### cURL request with API key

Source: https://groundroute.ai/docs/authentication

Example of using the API key as a Bearer token in a cURL request to the search endpoint.

```bash
curl -s https://api.groundroute.ai/v1/search \
  -H "Authorization: Bearer $GROUNDROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'
```

--------------------------------

### Call GroundRoute compatibility endpoint with httpx

Source: https://groundroute.ai/docs/integrations

Python example using httpx to POST to the /v1/search/compat endpoint. Only the URL and key change; the request body uses common SDK fields like query and max_results. Returns a Tavily/OpenAI-style body.

```python
import httpx

httpx.post(
    "https://api.groundroute.ai/v1/search/compat",   # only the URL + key change
    headers={"Authorization": f"Bearer {GROUNDROUTE_KEY}"},
    json={"query": "pgvector vs qdrant benchmark", "max_results": 5},
}.json()   # → {"answer": ..., "results": [...]}

```

--------------------------------

### Search API Request with cURL

Source: https://groundroute.ai/docs/search-api

Example of a POST request to the search endpoint using cURL, including authorization and JSON body parameters.

```bash
curl -s https://api.groundroute.ai/v1/search \
  -H "Authorization: Bearer $GROUNDROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "transformer attention complexity",
    "mode": "academic",
    "max_results": 10,
    "freshness": "static",
    "domains": ["arxiv.org"],
    "lang": "en"
  }'
```

--------------------------------

### Search API Response Structure

Source: https://groundroute.ai/docs/search-api

Example of a successful 200 OK response from the search endpoint, containing results, metadata, and usage information.

```json
{
  "request_id": "8f1c2e7a-…",      // uuid
  "tenant_id": "…",
  "results": [
    {
      "url": "https://arxiv.org/abs/...",
      "title": "Attention Is All You Need",
      "snippet": "…",
      "content": null,             // full body only when mode/engine provides it
      "score": 0.82,               // normalized relevance, 0–1, or null
      "source_engine": "exa",      // serper|brave|exa|tavily|perplexity|firecrawl
      "published_at": null,        // ISO 8601 or null
      "rank": 0                    // 0-based position as served
    }
  ],
  "answer": null,                  // synthesized answer (answer engines), or null
  "citations": [                   // present when an answer cites sources
    { "url": "https://...", "title": "…", "index": 0 }
  ],
  "degraded": false,               // true = partial results (one engine failed)

  "routing_meta": {
    "strategy": "price_led",       // price_led | learned | fanout
    "query_class": "academic",     // academic | web | news | page | answer
    "chosen_engine": "exa",
    "reason": "price_led:exa $7.00/1k (first eligible for academic, source=static)",
    "candidates": [
      { "engine": "exa",   "cost_per_1k_usd": 7.0, "eligible": true,  "picked": true,  "note": "cheapest eligible" },
      { "engine": "brave", "cost_per_1k_usd": 5.0, "eligible": true,  "picked": false, "note": null }
    ],
    "cost_usd": 0.007,             // actual provider cost incurred this request
    "latency_ms": 412,
    "degraded": false,
    "failover_from": null,         // engine that failed before chosen_engine, or null
    "missing_engines": []
  },

  "cache_meta": {
    "cache_tier": "miss",          // miss | exact_private | exact_pooled | semantic
    "poolable": false,
    "poolability_reason": "cell_not_allowlisted",
    "screens_post_nfkc": true,
    "freshness_bucket": "none",    // hourly | daily | none
    "cache_key_private": null,     // sha256 hex (no raw query)
    "cache_key_pooled": null,      // set only when poolable
    "cached_at": null,             // ISO 8601 when a hit
    "ttl_seconds": null,
    "cost_avoided_usd": 0.0,       // provider $ saved by this hit
    "similarity": null             // semantic tier only
  },

  "quality_meta": {
    "quality_score": null,         // composite 0–1, or null when not scored
    "components": {},
    "judge_sampled": false,
    "engine_agreement_rbo": null
  },

  "usage_meta": {
    "request_id": "8f1c2e7a-…",
    "tenant_id": "…",
    "account_id": "…",
    "api_key_id": "…",
    "ts": "2026-06-14T07:48:14Z",
    "billable": true,
    "searches_counted": 1,
    "provider_key_source": "platform",  // platform (managed) | byok
    "cost_usd": 0.007
  }
}
```

--------------------------------

### Use GroundRouteRetriever in LangChain

Source: https://groundroute.ai/docs/integrations

Replaces a TavilySearchAPIRetriever with GroundRouteRetriever(k=5) in LangChain. The commented lines show the previous Tavily setup. The helper is imported from groundroute_langchain.

```python
# LangChain — before:
#   from langchain_community.retrievers import TavilySearchAPIRetriever
#   retriever = TavilySearchAPIRetriever(k=5)
from groundroute_langchain import GroundRouteRetriever
retriever = GroundRouteRetriever(k=5)

```

--------------------------------

### Example normalized search response

Source: https://groundroute.ai/docs/quickstart

The response includes results plus meta blocks for routing, cache, quality, and usage. Headers also carry X-Request-Id, X-Cache-Tier, and X-Degraded.

```json
{
  "request_id": "8f1c…",
  "tenant_id": "…",
  "results": [
    {
      "url": "https://example.com/...",
      "title": "pgvector vs Qdrant: a benchmark",
      "snippet": "…",
      "source_engine": "serper",
      "rank": 0
    }
  ],
  "answer": null,
  "citations": [],
  "degraded": false,
  "routing_meta": { "strategy": "price_led", "chosen_engine": "serper", "cost_usd": 0.001 },
  "cache_meta":   { "cache_tier": "miss", "cost_avoided_usd": 0.0 },
  "quality_meta": { "quality_score": null },
  "usage_meta":   { "cost_usd": 0.001, "provider_key_source": "platform", "billable": true }
}

```

--------------------------------

### GET /console/provider-keys

Source: https://groundroute.ai/docs/byok

Lists all stored provider keys with masked information. Returns one entry per stored key, including id, provider, fingerprint_prefix, status, and created_at. Never returns plaintext keys.

```APIDOC
## GET /console/provider-keys

### Description
Lists all stored provider keys with masked information. Returns one entry per stored key, including id, provider, fingerprint_prefix, status, and created_at. Never returns plaintext keys.

### Method
GET

### Endpoint
/console/provider-keys

### Parameters
None

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the stored key.
- **provider** (string) - The provider name.
- **fingerprint_prefix** (string) - A short non-reversible fingerprint prefix of the key.
- **status** (string) - The status of the key.
- **created_at** (string) - The timestamp when the key was created.

#### Response Example
[
  {
    "id": "…",
    "provider": "serper",
    "fingerprint_prefix": "a1b2c3d4e5f6",
    "status": "active",
    "created_at": "2026-06-14T07:48:14Z"
  }
]
```

--------------------------------

### Use groundrouteSearch in Vercel AI SDK

Source: https://groundroute.ai/docs/integrations

Replaces a tavilySearchTool with groundrouteSearch() in the Vercel AI SDK. The commented lines show the previous setup. The helper is imported from "./groundroute".

```javascript
// Vercel AI SDK — before:
//   const tools = { search: tavilySearchTool(...) };
import { groundrouteSearch } from "./groundroute";
const tools = { search: groundrouteSearch() };

```

--------------------------------

### POST /console/keys

Source: https://groundroute.ai/docs/authentication

Creates a new API key for the tenant. Returns the plaintext key once, along with metadata.

```APIDOC
## POST /console/keys

### Description
Creates a new API key for the tenant. Returns the plaintext key once, along with metadata.

### Method
POST

### Endpoint
/console/keys

### Parameters
#### Request Body
- **name** (string) - Optional - A name for the key.

### Request Example
{
  "name": "production"
}

### Response
#### Success Response (200)
- **id** (string) - The key ID.
- **api_key** (string) - The plaintext API key, shown only once.
- **key_prefix** (string) - A masked display prefix.
- **name** (string) - The key name.

#### Response Example
{
  "id": "…",
  "api_key": "gr_live_…",
  "key_prefix": "gr_live…XYZ9",
  "name": "production"
}
```

--------------------------------

### Configure MCP server for Claude Desktop or Cursor

Source: https://groundroute.ai/docs/quickstart

Add the GroundRoute MCP server to mcp.json so an agent can call the search tool natively. Point any MCP client at https://api.groundroute.ai/mcp with the same Bearer key.

```json
{
  "mcpServers": {
    "groundroute": {
      "type": "http",
      "url": "https://api.groundroute.ai/mcp",
      "headers": { "Authorization": "Bearer gr_live_YOUR_KEY" }
    }
  }
}

```

--------------------------------

### POST /console/provider-keys

Source: https://groundroute.ai/docs/byok

Adds a new provider key. The key is validated with a live call to the provider before storage. Returns 201 on success, 400 for invalid or provider-rejected keys, and 503 if the provider is temporarily unreachable.

```APIDOC
## POST /console/provider-keys

### Description
Adds a new provider key for BYOK. The key is validated with a live call to the provider before storage.

### Method
POST

### Endpoint
/console/provider-keys

### Parameters
#### Request Body
- **provider** (string) - Required - The provider name (e.g., `serper`, `brave`, `exa`, `tavily`, `firecrawl`, `perplexity`).
- **key** (string) - Required - The API key for the provider.

### Request Example
{
  "provider": "serper",
  "key": "your-serper-api-key"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the stored key.
- **provider** (string) - The provider name.
- **fingerprint_prefix** (string) - A short non-reversible fingerprint prefix of the key.
- **status** (string) - The status of the key (e.g., `active`).
- **created_at** (string) - The timestamp when the key was created.

#### Response Example
{
  "id": "…",
  "provider": "serper",
  "fingerprint_prefix": "a1b2c3d4e5f6",
  "status": "active",
  "created_at": "2026-06-14T07:48:14Z"
}

#### Error Responses
- **400** - Invalid or provider-rejected key.
- **503** - Provider temporarily unreachable for validation (transient — retry).
```

--------------------------------

### Search with Python using httpx

Source: https://groundroute.ai/docs/quickstart

Perform the same search using Python and httpx. It prints each result's rank, title, and URL, plus the chosen engine and cache tier.

```python
import os, httpx

resp = httpx.post(
    "https://api.groundroute.ai/v1/search",
    headers={"Authorization": f"Bearer {os.environ['GROUNDROUTE_API_KEY']}"},
    json={"query": "pgvector vs qdrant benchmark", "mode": "auto", "max_results": 5},
    timeout=15,
)
resp.raise_for_status()
data = resp.json()
for r in data["results"]:
    print(r["rank"], r["title"], r["url"])
print("engine:", data["routing_meta"]["chosen_engine"], "| cache:", data["cache_meta"]["cache_tier"])

```

--------------------------------

### Add a provider key via POST /console/provider-keys

Source: https://groundroute.ai/docs/byok

Adds a BYOK key for a provider. The request body contains the provider and key. The response (201) returns metadata including a fingerprint prefix, but never echoes the key itself.

```json
// request
{ "provider": "serper", "key": "your-serper-api-key" }

// response (201) — note: the key itself is never echoed back
{
  "id": "…",
  "provider": "serper",
  "fingerprint_prefix": "a1b2c3d4e5f6",
  "status": "active",
  "created_at": "2026-06-14T07:48:14Z"
}
```

--------------------------------

### Error envelope JSON example

Source: https://groundroute.ai/docs/errors-and-limits

Shows the shared JSON shape of all 4xx/5xx error responses. Includes the error type, message, request_id (a UUID to quote in support requests), and a retryable flag. The type can be one of: timeout, auth, rate_limit, http, parse, unavailable, invalid_request.

```json
{
  "error": {
    "type": "rate_limit",        // see ErrorType below
    "message": "Rate limit exceeded",
    "request_id": "8f1c2e7a-…",  // uuid — quote this in support requests
    "retryable": true
  }
}
```

--------------------------------

### Set GroundRoute environment variables

Source: https://groundroute.ai/docs/integrations

Exports the GROUNDROUTE_API_KEY and GROUNDROUTE_BASE_URL environment variables required for all GroundRoute integrations. The base URL defaults to https://api.groundroute.ai.

```bash
export GROUNDROUTE_API_KEY=gr_live_...
export GROUNDROUTE_BASE_URL=https://api.groundroute.ai

```

--------------------------------

### Set GROUNDROUTE_API_KEY environment variable

Source: https://groundroute.ai/docs/quickstart

Export the API key as an environment variable. The plaintext key is shown only once, so store it in a secret manager.

```bash
export GROUNDROUTE_API_KEY="gr_live_xxxxxxxxxxxxxxxxxxxx"

```

--------------------------------

### MCP client configuration for GroundRoute

Source: https://groundroute.ai/docs/mcp-server

Add this mcpServers block to your MCP client config (Claude Desktop, Cursor, etc.) to connect to GroundRoute. Replace gr_live_YOUR_KEY with your actual API key. Restart the client to see the search tool under the groundroute server.

```json
{
  "mcpServers": {
    "groundroute": {
      "type": "http",
      "url": "https://api.groundroute.ai/mcp",
      "headers": { "Authorization": "Bearer gr_live_YOUR_KEY" }
    }
  }
}
```

--------------------------------

### search tool

Source: https://groundroute.ai/docs/mcp-server

The search tool allows MCP-capable agents to search the web via GroundRoute. It returns ranked results, an optional synthesized answer, and citations.

```APIDOC
## search tool

### Description
Search the web via GroundRoute. Returns ranked results, an optional synthesized answer, and citations.

### Parameters

| Parameter | Type | Default | Notes |
|-----------|------|---------|-------|
| query | string | - | Required. |
| mode | string | auto | auto, web, news, academic, answer, or page. Unknown values fall back to auto. |
| max_results | int | 10 | Clamped to 1-50. |
| freshness | string | null | fresh, semi, or static. Other values ignored. |
| domains | string[] | null | Include-filter. |
| lang | string | null | ISO 639-1. |
| country | string | null | ISO 3166-1 alpha-2. |

### Result Shape
{
  "results": [
    {
      "url": "https://...",
      "title": "...",
      "snippet": "...",
      "source_engine": "serper",
      "published_at": null
    }
  ],
  "answer": null,
  "citations": [
    { "url": "https://...", "title": "...", "index": 0 }
  ],
  "meta": {
    "request_id": "...",
    "cache_tier": "miss",
    "degraded": false,
    "cost_usd": 0.001
  }
}
```

--------------------------------

### Set default routing policy via API

Source: https://groundroute.ai/docs/routing-and-policies

Updates the workspace default routing policy using the console API. The policy must be one of price, quality, latency, or balanced.

```bash
curl -s -X PUT https://api.groundroute.ai/v1/console/settings \
  -H "Content-Type: application/json" \
  --cookie "gr_session=…" \
  -d '{"default_policy": "balanced"}'
```

--------------------------------

### DELETE /console/provider-keys/{key_id}

Source: https://groundroute.ai/docs/byok

Revokes a stored provider key. Returns 404 if the key does not belong to the user.

```APIDOC
## DELETE /console/provider-keys/{key_id}

### Description
Revokes a stored provider key. Returns 404 if the key does not belong to the user.

### Method
DELETE

### Endpoint
/console/provider-keys/{key_id}

### Parameters
#### Path Parameters
- **key_id** (string) - Required - The unique identifier of the key to delete.

### Response
#### Success Response (200)
No content.

#### Error Responses
- **404** - Key not found or not owned by the user.
```

--------------------------------

### POST /console/keys/{key_id}/rotate

Source: https://groundroute.ai/docs/authentication

Revokes the old key and issues a new one in a single step. Returns the new plaintext key once.

```APIDOC
## POST /console/keys/{key_id}/rotate

### Description
Revokes the old key and issues a new one in a single step. Returns the new plaintext key once.

### Method
POST

### Endpoint
/console/keys/{key_id}/rotate

### Parameters
#### Path Parameters
- **key_id** (string) - Required - The ID of the key to rotate.

### Response
#### Success Response (200)
- **api_key** (string) - The new plaintext API key, shown only once.

#### Response Example
{
  "api_key": "gr_live_…"
}
```

--------------------------------

### Search with curl using Bearer token

Source: https://groundroute.ai/docs/quickstart

Send a search request to POST /v1/search with the API key as a Bearer token. The response is normalized and includes meta blocks.

```bash
curl -s https://api.groundroute.ai/v1/search \
  -H "Authorization: Bearer $GROUNDROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "pgvector vs qdrant benchmark", "mode": "auto", "max_results": 5}'

```

--------------------------------

### Create API key response

Source: https://groundroute.ai/docs/authentication

The JSON response returned when creating a new API key, which includes the plaintext key that must be stored immediately.

```json
{
  "id": "…",
  "api_key": "gr_live_…",   // shown once — store it now
  "key_prefix": "gr_live…XYZ9",
  "name": "production"
}
```

--------------------------------

### DELETE /console/keys/{key_id}

Source: https://groundroute.ai/docs/authentication

Revokes the key immediately. The revoked key's auth cache is purged so it stops authenticating at once.

```APIDOC
## DELETE /console/keys/{key_id}

### Description
Revokes the key immediately. The revoked key's auth cache is purged so it stops authenticating at once.

### Method
DELETE

### Endpoint
/console/keys/{key_id}

### Parameters
#### Path Parameters
- **key_id** (string) - Required - The ID of the key to revoke.

### Response
#### Success Response (200)
No content.
```

--------------------------------

### Request processing flow for POST /v1/search

Source: https://groundroute.ai/docs

Visual representation of the request lifecycle, showing authentication, rate limiting, cache lookup, engine routing, and metadata return.

```text
client → POST /v1/search → auth → rate-limit → cache lookup
                                         │
                              hit ───────┘ (return cached, $ avoided)
                              miss → classify → route to cheapest engine
                                         │
                              engine fails → failover → engine
                                         │
                              return results + routing_meta + cache_meta + usage_meta
```

--------------------------------

### GroundRoute AI Langflow component methods

Source: https://groundroute.ai/docs/integrations/langflow

This snippet contains the core methods of the GroundRoute AI Langflow component: _to_records, _meta, _error, search_data, and search_dataframe. It handles API requests, error responses, and formats results for Langflow.

```python
    @staticmethod
    def _to_records(resp: dict[str, Any]) -> list[dict[str, Any]]:
        records: list[dict[str, Any]] = []
        for r in resp.get("results", []) or []:
            records.append({
                "url": r.get("url", ""),
                "title": r.get("title", ""),
                "snippet": r.get("snippet", ""),
                "content": r.get("content"),
                "source_engine": r.get("source_engine", ""),
                "published_at": r.get("published_at"),
            })
        return records

    @staticmethod
    def _meta(resp: dict[str, Any]) -> dict[str, Any]:
        cache_meta = resp.get("cache_meta") or {}
        usage_meta = resp.get("usage_meta") or {}
        return {
            "request_id": resp.get("request_id"),
            "cache_tier": cache_meta.get("cache_tier"),
            "degraded": resp.get("degraded", False),
            "cost_usd": usage_meta.get("cost_usd"),
        }

    def _error(self, message: str) -> list[Data]:
        logger.error(message)
        self.status = message
        return [Data(data={"error": message})]

    def search_data(self) -> list[Data]:
        if not self.api_key:
            return self._error(
                "GroundRoute API key is required. Get one at https://groundroute.ai/keys?utm_source=langflow"
            )
        try:
            response = httpx.post(
                f"{_BASE_URL}/v1/search",
                json=self._build_payload(),
                headers={"Authorization": f"Bearer {self.api_key}"},
                timeout=_TIMEOUT_S,
            )
        except httpx.HTTPError as exc:
            return self._error(f"GroundRoute request failed: {exc}")
        if response.status_code != 200:
            return self._error(
                f"GroundRoute returned HTTP {response.status_code}: {response.text[:300]}"
            )
        try:
            resp: dict[str, Any] = response.json()
        except ValueError as exc:
            return self._error(f"GroundRoute returned a non-JSON body: {exc}")

        records = self._to_records(resp)
        meta = self._meta(resp)
        data_list = [Data(data=rec) for rec in records]

        if resp.get("answer"):
            data_list.insert(
                0,
                Data(data={"answer": resp["answer"], "citations": resp.get("citations", []), **meta}),
            )

        engines = sorted({rec["source_engine"] for rec in records if rec.get("source_engine")})
        suffix = " (degraded)" if meta["degraded"] else ""
        self.status = f"{len(records)} results via {', '.join(engines) or 'cache'}{suffix}"
        return data_list or [Data(data={"warning": "no results", **meta})]

    def search_dataframe(self) -> DataFrame:
        return DataFrame(self.search_data())
```
Tokens:
Raw