Skip to content
Cemented AI

Search the web

POST
/v1/search
 
curl --request POST \
  --url https://www.cemented.ai/v1/search \
  --header 'Content-Type: application/json' \
  --data '{ "query": "NVIDIA fiscal 2025 revenue" }'

Returns page text and verbatim highlights. Standard-retention responses cache each URL/contentSha256 pair before returning; zero-retention responses have null hashes. Use these pairs in Grounded drafts for server-backed source verification. Each successful provider call is billed, including calls completing after the response deadline. Provider failures are listed in the response; an empty result is not proof of no matches.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
query
required

Natural-language or keyword query. Longer, specific queries work best across the neural backends.

string
>= 1 characters <= 2000 characters
numResults

Results to return after merging providers (max 50). Each provider is asked for this many, so the merged list is ranked from a wider pool.

integer
default: 10 >= 1 <= 50
type

Retrieval depth. fast favors latency, deep buys multi-hop retrieval where a backend offers it (Exa deep, Parallel advanced), auto balances the two.

string
default: auto
Allowed values: fast auto deep
category

Narrow the result type. research paper also routes to OpenAlex and Firecrawl’s academic index; news routes Firecrawl to its news source.

string
Allowed values: company people research paper news personal site financial report
includeDomains

Only return pages on these domains (sec.gov also matches subdomains; docs.python.org/3 scopes a path). Applied server-side by each backend and re-checked locally.

Array<string>
<= 100 items
excludeDomains

Never return pages on these domains.

Array<string>
<= 100 items
startPublishedDate

Only pages published on or after this date (ISO 8601).

string
/^\d{4}-\d{2}-\d{2}(?:[T ][0-9:.]+(?:Z|[+-]\d{2}:?\d{2})?)?$/
endPublishedDate

Only pages published on or before this date. Undated pages are kept.

string
/^\d{4}-\d{2}-\d{2}(?:[T ][0-9:.]+(?:Z|[+-]\d{2}:?\d{2})?)?$/
includeText

Phrases that must appear in a result’s title or text (case-insensitive).

Array<string>
<= 5 items
excludeText

Phrases that must not appear in a result’s title or text.

Array<string>
<= 5 items
providers

Backends to query, in priority order. Defaults to exa, parallel, and firecrawl (plus openalex for research paper). perplexity is admin-only and skipped for other callers. Unconfigured backends are reported as unavailable rather than failing the request. Firecrawl scrapes page bodies only when it is the sole backend; in a fan-out it contributes ranked URLs and page descriptions while Exa supplies page text.

Array<string>
>= 1 items <= 5 items
Allowed values: exa parallel firecrawl perplexity openalex
contents
object
text
Any of:
boolean
highlights
Any of:
boolean
Examples
Example basic 
{
  "query": "NVIDIA fiscal 2025 revenue"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Retrieval results

Media type application/json
object
object
required
string
Allowed values: search
requestId
required

Unique id for this search call.

string
query
required
string
results
required

Merged, deduplicated results in fused-rank order.

Array<object>
object
id
required

Stable id for the result (its URL).

string
url
required
string
title
required
string
publishedDate
required

Publication date when a backend reports one. Usually ISO YYYY-MM-DD; a news backend may return a relative phrase.

string | null
author
required
string | null
score
required

Backend relevance score when one reports it (Exa, OpenAlex). Ordering uses the fused rank, not this value.

number | null
text

Page text (Exa, Firecrawl scrape) or the backend’s long excerpts joined with blank lines (Parallel, Perplexity), or a metadata header plus abstract (OpenAlex). Present unless contents.text is false.

string
highlights

Query-relevant passages, each a verbatim substring of text. Present unless contents.highlights is false.

Array<string>
snippet
required

Short backend-provided description or first excerpt.

string | null
image
required
string | null
favicon
required
string | null
providers
required

Every backend that returned this page, best-ranked first. Agreement across backends raises the fused rank.

Array<string>
Allowed values: exa parallel firecrawl perplexity openalex
doi
required

DOI parsed from the URL when the page is a scholarly work.

string | null
contentSha256
required

SHA-256 of text. For standard retention with text enabled, this hash and the exact result URL identify stored text; otherwise null. A grounded research draft can cite it as contentSha256 on a web source so quotes are verified against text Cemented retrieved rather than text the agent supplied.

string | null
providers
required

One report per backend that was asked (or skipped).

Array<object>
object
name
required
string
Allowed values: exa parallel firecrawl perplexity openalex
status
required

ok returned results; error/timeout failed for this call (the other backends still count); unavailable was requested but is not configured or not permitted for this caller.

string
Allowed values: ok error timeout aborted unavailable
resultCount
required
integer
apiMs
required

Vendor round trip in milliseconds.

integer
costUsd
required

Raw vendor cost for this call before Cemented’s markup.

number
errorCode
required

Closed-registry code when status is not ok.

string | null
errorStatus
required

The backend’s HTTP status when the failure was an HTTP error response (for example 401 for a rejected credential or 429 for rate limiting); null otherwise.

integer | null
costDollars
required

Cost of the vendor calls behind this response.

object
total
required

Summed raw vendor cost before Cemented’s markup.

number
searchTime
required

Wall-clock milliseconds for the whole fan-out.

integer
Example 
{
  "object": "search",
  "query": "NVIDIA fiscal 2025 revenue",
  "searchTime": 100,
  "requestId": "search_example",
  "results": [],
  "providers": [],
  "costDollars": {
    "total": 0
  }
}

400

Section titled “400 ”

Invalid input or unavailable provider

401

Section titled “401 ”

Authentication required

402

Section titled “402 ”

Insufficient credits or API key spend limit exceeded