Search

curl --request POST \
  --url https://alpha.api.trycaesar.com/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "linux kernel amd gpu suspend"
}
'

import requests

url = "https://alpha.api.trycaesar.com/v1/search"

payload = { "query": "linux kernel amd gpu suspend" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'linux kernel amd gpu suspend'})
};

fetch('https://alpha.api.trycaesar.com/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "request_id": "<string>",
  "results": [
    {
      "canonical_url": "<string>",
      "doc_id": "<string>",
      "rank": 123,
      "description": "<string>",
      "index": "<string>",
      "labels": [
        "<string>"
      ],
      "metadata": {
        "content_digest": "<string>",
        "extracted_at": "<string>",
        "first_seen_at": "<string>",
        "last_crawled_at": "<string>",
        "last_seen_at": "<string>",
        "published_at": "<string>"
      },
      "mime": "<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_uri": "<string>",
      "source_url": "<string>",
      "title": "<string>"
    }
  ],
  "search_id": "<string>",
  "session_id": "<string>",
  "$schema": "https://alpha.api.trycaesar.com/SearchResponse.json",
  "access": {
    "rate_limit": {
      "limit_rps": 123,
      "remaining": 123,
      "reset_at": "<string>"
    }
  },
  "integration_results": {
    "href": "<string>",
    "selected": 123,
    "total": 123
  },
  "ranking": {
    "ranker_version": "<string>",
    "score_scope": "<string>"
  },
  "truncated": true,
  "usage": {
    "bytes_returned": 123,
    "requests": 123
  },
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "details": {}
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

POST

curl --request POST \
  --url https://alpha.api.trycaesar.com/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "linux kernel amd gpu suspend"
}
'

import requests

url = "https://alpha.api.trycaesar.com/v1/search"

payload = { "query": "linux kernel amd gpu suspend" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: 'linux kernel amd gpu suspend'})
};

fetch('https://alpha.api.trycaesar.com/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "request_id": "<string>",
  "results": [
    {
      "canonical_url": "<string>",
      "doc_id": "<string>",
      "rank": 123,
      "description": "<string>",
      "index": "<string>",
      "labels": [
        "<string>"
      ],
      "metadata": {
        "content_digest": "<string>",
        "extracted_at": "<string>",
        "first_seen_at": "<string>",
        "last_crawled_at": "<string>",
        "last_seen_at": "<string>",
        "published_at": "<string>"
      },
      "mime": "<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_uri": "<string>",
      "source_url": "<string>",
      "title": "<string>"
    }
  ],
  "search_id": "<string>",
  "session_id": "<string>",
  "$schema": "https://alpha.api.trycaesar.com/SearchResponse.json",
  "access": {
    "rate_limit": {
      "limit_rps": 123,
      "remaining": 123,
      "reset_at": "<string>"
    }
  },
  "integration_results": {
    "href": "<string>",
    "selected": 123,
    "total": 123
  },
  "ranking": {
    "ranker_version": "<string>",
    "score_scope": "<string>"
  },
  "truncated": true,
  "usage": {
    "bytes_returned": 123,
    "requests": 123
  },
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>",
      "details": {}
    }
  ]
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>",
  "type": "error",
  "$schema": "https://alpha.api.trycaesar.com/ErrorEnvelope.json"
}

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.

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

Show child attributes

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

Show child attributes

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

response

object

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

Show child attributes

scope

object

Which indexes to search. Omit it for the web index. Additive: existing clients are unaffected.

Show child attributes

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.

Show child attributes

Response

Search results.

request_id

string

required

results

object[] | null

required

Show child attributes

search_id

string

required

session_id

string

required

$schema

string<uri>

read-only

A URL to the JSON Schema for this object.

Example:

"https://alpha.api.trycaesar.com/SearchResponse.json"

access

object

Show child attributes

integration_results

object

Show child attributes

ranking

object

Show child attributes

truncated

boolean

usage

object

Show child attributes

warnings

object[] | null

Show child attributes

API reference

Endpoints

Authorizations

Headers

Body

Response