Skip to content
Cemented AI

Fetch page text

POST
/v1/contents
 
curl --request POST \
  --url https://www.cemented.ai/v1/contents \
  --header 'Content-Type: application/json' \
  --data '{ "urls": [ "https://example.org/study" ], "provider": "exa" }'

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
urls
required
Array<string>
>= 1 items <= 20 items
provider

The provider to fetch these URLs. No automatic fallback runs.

string
default: exa
Allowed values: exa firecrawl
maxCharacters
integer
default: 20000 >= 200 <= 100000
query

Optional query used to select highlights.

string
"" <= 2000 characters
highlights
Any of:
boolean
Examples
Example basic 
{
  "urls": [
    "https://example.org/study"
  ],
  "provider": "exa"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Retrieval results

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

Unique id for this search call.

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
elapsedMs
required
integer
Example 
{
  "object": "contents",
  "elapsedMs": 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