Skip to main content
POST
Compare contents
You get whether anything changed, a tally, and each change with both of its sides. The baseline is another record, baseline_contents_id, or the markdown you kept yourself as a record returned it, baseline_markdown with its baseline_fingerprint. It is a POST with a body that bills nothing and changes nothing but the record’s expires_at, so it is safe to repeat.

What it costs

The key needs contents:read. The call is free. The answer is 200 with Comparison; the call moves the current record’s expires_at 48 hours ahead. The body is at most 8 MiB, so that a baseline of 1,000,000 characters fits in any script.

The comparison

  • A baseline you kept yourself is checked first: the sha-256 of the text, after the same normalization as the fingerprint, must equal baseline_fingerprint, else 422 invalid-field, syntax, naming baseline_fingerprint. The text is split into blocks by the rules that made it, baseline.verified is true, and the before sides carry text without ids.
  • Both sides must share one execution.version and one record_scope, else 422 records-incomparable with change naming which. A difference in the kind of source or the configuration is the notice fingerprint_incomparable, and the comparison runs. A baseline you kept names its version and scope in baseline_version and baseline_scope, or takes the current record’s.
  • The unit is the block. Text is compared after Unicode normalization with the formatting marks removed; tables cell by cell; no model.
  • changed blocks are paired in order when they are alike above a published similarity; moved is the same text at another position in the block order; added and removed are the rest, removed blocks at the place they held. A page number differing alone is no change, and a paragraph that runs across a page break is one block.
  • changed true with changes [] means only inline formatting moved. The same id on both sides is changed false with changes [].
  • Two records of different URLs or documents are allowed; you know what you compare. paywall_declared is repeated when either side carries it.

Paging

changes is paged, counts the whole tally on every page before the rows; page_size from 1, default 50, maximum 200, a larger value lowered with the notice page_size_lowered; page_token binds the body’s other fields, page_size included; a token of another comparison, or of this one with another body, is 400 page-token-invalid.

Refused before any work

baseline_contents_id and baseline_markdown both present: invalid-field, exclusive; neither: required; baseline_markdown without baseline_fingerprint or the reverse: dependent; baseline_version or baseline_scope with baseline_contents_id: dependent. The text does not hash to baseline_fingerprint: invalid-field, syntax. A bound passed, page_size above its maximum excepted, which is lowered: bound; an unknown field: unknown_field. Another version or scope: 422 records-incomparable, change.field naming baseline_version or baseline_scope, baseline_contents_id for a baseline that is a record. Either record without content: 409 record-without-content, change.field naming the side. A token of another comparison, or of this one with another body: 400 page-token-invalid. An id of the wrong kind: 400 invalid-request. Every violation of the body is reported at once in violations.

Notices this operation makes

fingerprint_incomparable, paywall_declared, page_size_lowered, version_retiring.

Problem types

  • 400 invalid-request, The request is invalid; page-token-invalid, The page token is invalid.
  • 401 unauthorized, The key is missing or rejected.
  • 403 insufficient-scope, The key lacks a scope this call needs.
  • 404 not-found, Not found, change.field saying which id.
  • 409 record-without-content, The record has no content.
  • 410 contents-expired, The record has expired, detail naming which record.
  • 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; records-incomparable, The records cannot be compared.
  • 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

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 current record, a cnt_ id.

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

Body

application/json

The request of compare_contents: the baseline, a record you already have by baseline_contents_id or a text you hold yourself by baseline_markdown with baseline_fingerprint, one of the two required; and the page of changes wanted. An explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused invalid-field, unknown_field.

baseline_contents_id
string

The baseline record, a cnt_ id kept by the same account. One of baseline_contents_id and baseline_markdown is required; both at once are refused exclusive.

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

"cnt_3Fk9abaUhNX7t2eKkgfd3e"

baseline_markdown
string

The markdown you kept, as a record returned it, whole, at most 1,000,000 characters; a partial text cannot be compared, since its hash is checked. With baseline_fingerprint, each refused dependent without the other.

Required string length: 1 - 1000000
baseline_fingerprint
string

The fingerprint of baseline_markdown as the record returned it; a text that does not hash to it is refused syntax.

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

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

baseline_version
string

The execution.version of the record your text came from, at most 64 characters, so the one-version rule can be checked and the text split by the rules that made it; with baseline_markdown only, refused dependent with baseline_contents_id. Default the current record's.

Required string length: 1 - 64
Example:

"1.0.0"

baseline_scope
enum<string>

The record_scope of the record your text came from; with baseline_markdown only, refused dependent with baseline_contents_id. Default the current record's.

Available options:
main,
whole_page
page_size
integer
default:50

At most this many changes on the page, from 1; default 50; the maximum, 200, stands in Limits.bounds, and a larger value is lowered with the notice page_size_lowered.

Required range: x >= 1
page_token
string

The next page of changes, as the last answer's next_page_token gave it; bound to this comparison and the body's other fields, page_size included. Default none, the first page.

Required string length: 1 - 1024

Response

Both sides with their fingerprints, whether anything changed, the tally, and the changes block by block, paged.

The answer of compare_contents: both sides with their fingerprints, whether anything changed, the whole tally on every page, and the changes block by block, paged.

contents_id
string
required

The current record.

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

"cnt_9Zze6X8RDFg2XxyKyLlV5T"

expires_at
string<date-time>
required

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

Example:

"2026-11-13T08:40:02Z"

current
object
required

The current record's side.

baseline
object
required

The baseline's side; fetched_at is absent when the baseline is a text you hold yourself.

changed
boolean
required

Whether anything differs; true with changes [] means the words are the same and only their inline formatting moved.

counts
object
required

The whole tally, on every page, before the rows.

changes
object[]
required

The changes of this page, block by block; [] when none.

notices
object[]
required

This call's notices, fingerprint_incomparable, paywall_declared, page_size_lowered, version_retiring; [] 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_01JONfNiPNrnysSRQjsH2k"

baseline_contents_id
string

The baseline record. Present when given.

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

"cnt_3Fk9abaUhNX7t2eKkgfd3e"

next_page_token
string

The token for the next page of changes; pass it as page_token. Present while more remains, and a page that carries it always has at least one change.

Maximum string length: 1024