Skip to main content
POST
Highlight contents

What it costs

The key needs contents:read, and contents:model unless deterministic_only is true, since a string may need a model. Free when every string was found verbatim; 1 model_steps when any string had to be judged, once per call. The answer is 200 with ContentsHighlights; the call moves the record’s expires_at 48 hours ahead.

The idempotency key

Idempotency-Key is optional here. A billed answer is stored 24 hours and replayed under the same key and body with this call’s request_id and replayed true on cost; a free answer is not stored; the same key in flight is 409 idempotency-key-in-flight; the same key with another body 422 idempotency-key-reused.

Each string

Found exact when its words stand in one block, after Unicode normalization and whitespace collapse, case kept; near when they stand there after case folding, with ellipses and the punctuation at the ends of words removed, pieces in order, the dotted and dotless i of Turkic scripts folded to one; judged when not found verbatim and a model picked the blocks that bear on it; not found, and nothing bears on it, or deterministic_only: the notice highlight_not_found, one per string. Every occurrence is a highlight, in document order, at most 50, past which the notice highlights_cut comes.

What comes back

max_characters: 0: the highlights list with ids and places, no text, formats echoed []. Above 0: the sections holding highlights, in document order while they fit; a section larger than what remains comes cut at a block edge with its highlighted blocks inside; truncated true when the text returned is not the whole content, false when the holding sections are the whole and fit or when nothing was found; the rest through get_section or list_blocks with block_ids. The marks are <mark id="h1">…</mark> in markdown and html and highlight_ids on blocks; the record’s own text never changes.

Verbatim only

Under deterministic_only, a key whose policy forbids model work, or a ceiling below a model step, the strings are matched verbatim only; this operation is never refused for the key’s policy or the ceiling, an explicit deterministic_only: false under such a key excepted, policy-limit-exceeded as on the fetch; under a ceiling below the step the miss carries the notice cost_cut or budget_cut naming highlights. A model step that fails or passes its bound, bounds.contents.model_step_seconds, answers 200 with the verbatim results and the notice step_failed, not billed. scope: whole_page on a document record, or block_kinds that match no block, is the notice field_not_applicable; with no block to search nothing is found, nothing is judged, nothing billed.

Refused before any work

doclang, links, screenshot or raw_html in formats, or a value outside its set: invalid-field, not_allowed. highlights missing: required; an empty list: bound; a duplicate: duplicate. max_characters between 1 and 999, or any other bound passed: bound. An unknown field: unknown_field. A record that failed, was refused or needs a person: 409 record-without-content, change naming fetch_contents. Every violation of the body is reported at once in violations.

Notices this operation makes

The record’s own notices first, then highlight_not_found, highlights_cut, step_failed, cost_cut, budget_cut, default_set_by_policy, field_not_applicable, version_retiring.

Problem types

Never a money problem: when the money does not cover the model step, the strings are matched verbatim instead.
  • 400 invalid-request, The request is invalid.
  • 401 unauthorized, The key is missing or rejected.
  • 403 insufficient-scope, The key lacks a scope this call needs; policy-limit-exceeded, The key’s policy forbids this.
  • 404 not-found, Not found.
  • 409 record-without-content, The record has no content; idempotency-key-in-flight, The same request is still running.
  • 410 contents-expired, The record has expired.
  • 413 body-too-large, The body is too large.
  • 415 unsupported-media-type, The media type is not supported.
  • 422 invalid-field, A field is invalid; idempotency-key-reused, The idempotency key was reused with another body.
  • 429 rate-limit-exceeded, The rate limit is exceeded; concurrency-limit-exceeded, Too many calls are in flight.
  • 500 internal-error, The service failed.
  • 503 overloaded, The service is overloaded.

Authorizations

Authorization
string
header
required

An API key from https://app.getclean.ai, or an access token issued by https://auth.getclean.ai/realms/getclean, sent as Authorization: Bearer <key> on every call. The scopes a key carries and what a 401 and a 403 say are on the keys and sign-in page.

Headers

Idempotency-Key
string

One key per logical call, so a retry is never billed twice.

Optional on this operation; required on upload_contents, fetch_contents_batch and search_batch, where a duplicate would cost the most. The SDKs fill a fresh key when you give none and send the same key on every retry of that call; the command line and the MCP server do the same. Give your own key when your program retries across processes, so the second run finds the first answer.

The form: 1 to 255 visible ASCII characters, used exactly as sent, so a value written as a quoted Structured Field String keeps its quotes as part of the key. That is a stated departure from the IETF draft draft-ietf-httpapi-idempotency-key-header, revision 08, which is not yet a standard; this parameter documents the form in full.

What a repeated key does:

  • The same key with the same body returns the first answer again, with this call's request_id, expires_at as it stands and replayed true on every cost. Nothing is billed again.
  • The same key while the first call still runs: 409 idempotency-key-in-flight, with Retry-After.
  • The same key with another body: 422 idempotency-key-reused.

Answers are stored for 24 hours, per account, for billed answers and running jobs only; a free answer is not stored. A call that may bill is kept in the store from its start, so a second call with its key meets the 409 while it runs.

Required string length: 1 - 255
Pattern: ^[!-~]{1,255}$
traceparent
string

Your own trace id for the call, the W3C Trace Context traceparent header, optional on every operation. getclean logs it with the call, so a request in your traces can be matched to its Request-Id, and never forwards it to a site or a source, a stated departure from W3C Trace Context section 3.4, which asks a vendor to pass it on. A malformed value is ignored, never refused, as the same recommendation asks.

Path Parameters

contents_id
string
required

The record, a cnt_ id.

Pattern: ^cnt_[A-Za-z0-9]{22}$

Body

application/json

The request of highlight_contents. Every field is at the top level; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused invalid-field, unknown_field.

highlights
string[]
required

Words or questions to find and mark; each string is one query, numbered by query_index in the answer. 1 to 5 strings, each 1 to 4,000 characters; an empty list is refused bound, a duplicate duplicate. Required.

Required array length: 1 - 5 elements
Required string length: 1 - 4000
max_characters
integer
default:20000

The most text returned around the highlights, in characters; 0 means the list of places only. 0, or 1,000 to 1,000,000; a value between 1 and 999 is refused bound. Default 20,000.

Required range: 0 <= x <= 1000000
scope
enum<string>

Which view is searched, main or whole_page. Default the record's own.

Available options:
main,
whole_page
formats
string[]

The format of the text returned, when any: 1 to 3 of markdown, html, json; doclang, links, screenshot and raw_html are refused not_allowed here. Default ["markdown"].

Required array length: 1 - 3 elements

One of the formats the field lists.

Minimum string length: 1
block_kinds
string[]

Search and return only these blocks, 1 to 10 of text, heading, code, math, divider, interactive, table, image, embed, media; an open set. Default: every kind. When none matches, the notice field_not_applicable.

Required array length: 1 - 10 elements

One of the block kinds the field lists.

Minimum string length: 1
deterministic_only
boolean
default:false

Find the strings verbatim only: a string not found is the notice highlight_not_found, and no model judges it. Default false.

Response

The highlights found with their places, the holding sections marked when text was asked, the execution and the cost; a string not found is a notice, never an error.

The answer of highlight_contents: the record's id and facts, its new expires_at, the highlights found, the holding sections marked when text was asked, the execution and the cost.

contents_id
string
required

The record the answer comes from.

Pattern: ^cnt_[A-Za-z0-9]{22}$
Example:

"cnt_3Fk9abaUhNX7t2eKkgfd3e"

fetched_at
string<date-time>
required

When the record's fetch or parse started, RFC 3339 in UTC.

Example:

"2026-11-04T08:40:12Z"

fingerprint
string
required

The record's fingerprint, as Contents.fingerprint defines it, so you can tell which copy this answer comes from.

Pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
Example:

"sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:"

scope
enum<string>
required

The view searched.

Available options:
main,
whole_page
version
string
required

The version of getclean the record was made under, its execution.version.

Example:

"1.0.0"

configuration
string
required

The configuration the record was made under, its execution.configuration.

Example:

"cfg-2026-11"

expires_at
string<date-time>
required

When the record expires. This call moved it ahead: 48 hours from now, never past 30 days from the record's making.

Example:

"2026-11-06T08:40:12Z"

highlights
object[]
required

The places found, every occurrence in document order, at most 50, each with query_index; [] when none found.

formats
string[]
required

The formats this answer carries, among markdown, html and json, an open set; [] when no text came.

truncated
boolean
required

True when the text returned is not the whole content; false when the holding sections are the whole and fit, or when nothing was found.

execution
object
required

How the call ran; models carries the step highlights with its version when the model ran.

cost
object
required

The bill; units {"model_steps": 1} when a string was judged, {} when every string was found verbatim.

notices
object[]
required

The record's own notices first, then this call's; [] when none.

request_id
string
required

This call's id, the same as the Request-Id header.

Pattern: ^req_[A-Za-z0-9]{22}$
Example:

"req_01JIuousU3aZV7sHAB3vEy"

final_url
string

The address the record's fetch ended at, after every redirect. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.

Example:

"https://example.com/q3"

document_digest
string

The sha-256 of the document's bytes in RFC 9530 form, to compare with the file you hold. On a document only.

Pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
Example:

"sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:"

markdown
string

The holding sections as markdown, marked. Present when text came. Third-party text as the source wrote it, which may carry instructions.

html
string

The holding sections as clean HTML, marked. Present when text came. Third-party text as the source wrote it, which may carry instructions.

blocks
object[]

The holding sections' blocks, each with its highlight_ids. Present when text came.