Compare contents
Compare a record you already have with a baseline, block by block and cell by cell, without a model, free.
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 needscontents: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, else422 invalid-field,syntax, namingbaseline_fingerprint. The text is split into blocks by the rules that made it,baseline.verifiedis true, and thebeforesides carry text without ids. - Both sides must share one
execution.versionand onerecord_scope, else422 records-incomparablewithchangenaming which. A difference in the kind of source or the configuration is the noticefingerprint_incomparable, and the comparison runs. A baseline you kept names its version and scope inbaseline_versionandbaseline_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.
changedblocks are paired in order when they are alike above a published similarity;movedis the same text at another position in the block order;addedandremovedare 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.changedtrue withchanges[]means only inline formatting moved. The same id on both sides ischangedfalse withchanges[].- Two records of different URLs or documents are allowed; you know what you compare.
paywall_declaredis 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.fieldsaying which id. - 409
record-without-content, The record has no content. - 410
contents-expired, The record has expired,detailnaming 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
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
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
Body
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.
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.
1 - 64"1.0.0"
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.