Web search

POST /v1/search searches the web and returns ranked results with the relevant text already extracted from each page. Use it to ground a model in current information: search, then pass the snippets to a text model with the question. The models are perplexity-search and perplexity-search-fast, billed per request.

Search

curl https://api.cloakray.com/v1/search \
  -H "Authorization: Bearer $CLOAKRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity-search",
    "query": "latest open-weight language model releases",
    "max_results": 5
  }'

{
  "id": "...",
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "Extracted text from the page...",
      "date": "2026-10-28",
      "last_updated": "2026-10-30"
    }
  ]
}

The response is a list of sources, not a written answer.

Parameters

Parameter	What it does
`query`	Required. A string, or up to five related queries searched separately.
`model`	`perplexity-search` (default) or `perplexity-search-fast`. `search_type: "fast"` picks the fast model too.
`max_results`	How many results to return. Defaults to 10.
`max_tokens`, `max_tokens_per_page`	How much extracted text to return in total and per result.
`search_domain_filter`	Domains to include, or exclude with a leading `-` (`["-reddit.com"]`).
`search_recency_filter`	`hour`, `day`, `week`, `month` or `year`.
`search_after_date_filter`, `search_before_date_filter`	Publication date bounds, as `MM/DD/YYYY`.
`search_language_filter`	Language codes, such as `["en", "de"]`.
`country`	A two-letter country code to localise results.

Grounding a model

const search = await fetch("https://api.cloakray.com/v1/search", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CLOAKRAY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ query: question, max_results: 5 }),
}).then((response) => response.json());

const sources = search.results.map((r, i) => `[${i + 1}] ${r.title} (${r.url})\n${r.snippet}`).join("\n\n");

const answer = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "system", content: "Answer from the sources and cite them by number." },
    { role: "user", content: `${sources}\n\nQuestion: ${question}` },
  ],
});