Skip to main content
POST
/
v1
/
search
Search
curl --request POST \
  --url https://search-api-staging-779189860552.europe-west1.run.app/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>"
}
'
{
  "request_id": "<string>",
  "results": [
    {
      "canonical_url": "<string>",
      "doc_id": "<string>",
      "rank": 123,
      "description": "<string>",
      "metadata": {
        "content_digest": "<string>",
        "extracted_at": "<string>",
        "first_seen_at": "<string>",
        "last_crawled_at": "<string>",
        "last_seen_at": "<string>",
        "published_at": "<string>"
      },
      "passages": [
        {
          "doc_id": "<string>",
          "ordinal": 123,
          "passage_id": "<string>",
          "text": "<string>",
          "char_end": 123,
          "char_start": 123,
          "section_heading": "<string>",
          "section_path": [
            "<string>"
          ]
        }
      ],
      "provenance": {
        "capture_id": "<string>",
        "capture_time": "<string>"
      },
      "score": {
        "value": 123
      },
      "snippet": "<string>",
      "source_url": "<string>",
      "title": "<string>"
    }
  ],
  "search_id": "<string>",
  "session_id": "<string>",
  "$schema": "<string>",
  "access": {
    "rate_limit": {
      "limit_rps": 123,
      "remaining": 123,
      "reset_at": "<string>"
    },
    "tier": "<string>"
  },
  "ranking": {
    "mode": "<string>",
    "ranker_version": "<string>",
    "score_scope": "<string>"
  },
  "truncated": true,
  "usage": {
    "approx_tokens": 123,
    "bytes_returned": 123,
    "requests": 123
  },
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "details": {}
    }
  ]
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Session-ID
string

Optional client session identifier.

Body

application/json
query
string
required

The search query, phrased as the user or agent would ask it. Drives ranking and passage selection even when search_queries supplies a rewrite.

Minimum string length: 1
Example:

"linux kernel amd gpu suspend"

client_model
string

Calling model identifier, recorded for analytics and ranking tuning.

content
object

Accepted for forward compatibility; no effect today. /v1/search returns snippets and passages only - read a result in full with /v1/document.

debug
object

Reserved for internal evaluation harnesses; ignored for public callers.

filters
object

Structured filters. Keys: country (two-letter code such as 'us' or 'de', scoping results to a market), language (two-letter code such as 'en'), exact_match (boolean; quotes the query so the index matches it verbatim).

freshness_policy
object

Recency requirements. Keys: published_after (RFC 3339 timestamp or YYYY-MM-DD date; only content published after it) and freshness (coarse window code pd, pw, pm, or py for past day, week, month, or year; ignored when published_after is set).

max_results
integer<int64>
default:10

Maximum number of ranked results to return. The response carries fewer when the index has fewer matches.

Required range: 1 <= x <= 50
mode
enum<string>
default:standard

Retrieval budget and ranking mode: fast skips the reranking stage for the lowest latency; standard (default) and research rerank results, with research spending the largest retrieval budget.

Available options:
fast,
standard,
research
objective
string

What the search is for, in plain language (e.g. 'find the canonical migration guide to cite'). Recorded for ranking evaluation; does not change retrieval today.

response
object

Optional response shaping: verbosity preset and serialized-size budget.

search_queries
string[] | null

Caller-provided query rewrites. The first entry replaces query as the text sent to the search index; query still drives reranking and passage selection. All entries are visible to the server-side query rewriter.

session_id
string<uuid>

Client session identifier (UUID). Groups related search, document, and feedback calls; equivalent to the X-Session-ID header. When omitted, the server generates one and echoes it back as session_id.

source_policy
object

Domain allow/deny policy. Keys: include_domains (array of domains; with require_domain_match true, results outside them are dropped, and a single entry is also sent to the index as a site: operator), exclude_domains (array of domains whose results are always dropped), require_domain_match (boolean). Domains match their subdomains; a leading www. is ignored.

Response

Search results.

request_id
string
required
results
object[] | null
required
search_id
string
required
session_id
string
required
$schema
string<uri>
read-only

A URL to the JSON Schema for this object.

Example:

"https://search-api-staging-779189860552.europe-west1.run.app/SearchResponse.json"

access
object
ranking
object
truncated
boolean
usage
object
warnings
object[] | null