Preview source evidence

POST/api/v1/citations/source-previewhttps://api.webcite.co

When to use it

For a web page, send url. For a file, send asset_id with a 1-based page, or a spreadsheet cell and optional full. For immutable evidence, send source_version_id, representation_id, and source_unit_id together. IDs must belong to the authenticated account.

A reflowed match uses a prepared OCR reading and remains subject to review. Preserve the original matched_text and the rescue provenance. See evidence and review.

Request

1 credit.

Examples run on your server. Set WEBCITE_API_KEY first. Python examples use the requests package.

curl

curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/citations/source-preview' \
  -H "x-api-key: $WEBCITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://www.toureiffel.paris/en/the-monument/key-figures",
  "quote": "330 meters"
}'

Request body

asset_idstring

Uploaded asset ID to preview (from POST /upload). Provide this OR url. Also accepts an "asset://" citation url.

cellstring

A1 cell anchor for a legacy spreadsheet preview.

fullboolean

Return the capped full sheet instead of a cell window.

highlight_termsstring[]

Terms to highlight in the preview.

pagenumber

1-based page (PDF) or sheet index (spreadsheet) to preview.

Default: 1

quotestring

The cited quote. It is bound back against the resolved source text; the response reports whether it was found (grounded) and how it matched.

representation_idstring

Exact parser representation, never latest.

source_unit_idstring

Exact unit within the immutable representation.

source_version_idstring

Immutable source version. Requires representation_id and source_unit_id.

titlestring

Optional title for a web source.

urlstring

Web source URL to preview. Provide this OR asset_id. Returns a text-fragment deep link that scrolls to the quote.

Response

Returns a source preview and binding information. Check binding.grounded, binding.method, and the matched passage before presenting the quote as source-backed.

200 response

application/json

anchorstring

asset_idstring

Asset ID (kind=page|grid).

bindingobjectrequired

bindBack result , whether the quote is grounded in the source.

Show binding fields

groundedbooleanrequired

True when the quote was found in the resolved source.

matched_quotestring

The matched substring, when grounded verbatim.

matched_textstring

The best-matching passage found in the source , present even when unbound, so a reviewer sees the closest evidence.

methodstringrequired

How the quote matched: exact/normalized substring, fuzzy passage match, reflowed OCR reading, or unbound.

Values: "exact""normalized""fuzzy""reflowed""unbound"

readingstring

Derived body reading with page furniture removed; absent for stored text.

Values: "body"

rescueobject

OCR rescue outcome: attempted=false with code/reason, attempted=true and rescued=false (optionally ambiguous), or rescued=true with transformations, raw dropped lines and retained spans. Unknown or unattempted is never a failed rescue.

Show rescue fields

Variant 1

attemptedbooleanrequired

Values: false

codestringrequired

Values: "not_ocr""labels_not_available""judge_unavailable""not_prepared""disabled""resource_limit"

reasonstringrequired

Variant 2

ambiguousboolean

Values: true

attemptedbooleanrequired

Values: true

rescuedbooleanrequired

Values: false

Variant 3

attemptedbooleanrequired

Values: true

basisstringrequired

Values: "code""measured"

calibrationKeystringrequired

decidedAtstringrequired

droppedLinesstring[]required

modelstring | nullrequired

readingstringrequired

Derived matching text; display the raw preview text instead.

rescuedbooleanrequired

Values: true

retainedSpansobject[]required

Show retainedSpans fields

fromLineintegerrequired

pageintegerrequired

toLineintegerrequired

transformationsobject[]required

Show transformations fields

afterLineinteger

atLineinteger

kindstringrequired

Values: "dehyphenate""join""drop"

linestring

sourcestring

Values: "element_label""repetition""page_number""margin_band"

scorenumber

Similarity of the best match, 0..1.

cellsstring[]

Bounded rows of cells with A1 refs, values and anchor flags.

deep_linkstringrequired

Deep link to the source at the cited location: url#:~:text=quote for web, asset_url#page=N for documents.

highlight_termsstring[]

Highlight terms.

image_base64string

judgmentobject

kindstringrequired

Preview shape.

Values: "web""page""grid""unit""image"

locatorobject

mime_typestring

Values: "application/pdf"

pagenumber

Page/sheet number (kind=page|grid).

quotestring

The cited quote.

representation_idstring

sheetstring

Sheet name (kind=grid).

source_unit_idstring

source_version_idstring

stateobject

textstring

Resolved source text (kind=page|grid).

titlestring

Web source title (kind=web).

urlstring

Web source URL (kind=web).

Errors

For 400, check the request fields and source identifiers. For 401, check your API key. For 429, wait for the retry interval. See the errors guide before retrying a billable request.

400: Provide a web url or an asset_id
401: Unauthorized - API key required
429: Rate limit exceeded

Error handling and retry guidance