Skip to main content
A reviewer who checks a report opens the source and looks for the sentence behind each claim. highlight_contents does that search. It takes a record, which is the copy of a page or a document that getclean stores after a fetch or an upload, and it returns every place in the record that bears on each of your strings. Each place is one highlight.

Ask up to 5 questions in one call

Send from 1 to 5 strings in highlights. A string is a phrase to find word for word, or a question in plain words, of at most 4,000 characters. This request asks 5 things of a credit agreement that was uploaded before: 2 defined terms, 2 questions, and a phrase. With max_characters set to 0, the response has the highlights and no text.
Replace CONTENTS_ID with the id of a record, such as cnt_3Fk9abaUhNX7t2eKkgfd3e. The response lists every highlight. This one is cut to the highlights of the first 3 strings, and each highlight to the fields that this section explains.
200 OK
Each highlight names the string that found it in query_index, counted from 0. The term “Change of Control” is in the agreement twice, in its definition and in the clause that uses it, so it has 2 highlights. Every occurrence of a string is a highlight of its own, in the order of the document, up to 50 in one call. If there are more, the notice highlights_cut says so. The question has no words in common with the clause that answers it. A model chose the block that bears on it, and text has the agreement’s own words, never the model’s.

Get the passages with their marks

To get the text with the highlights, set max_characters above 0. The response then has the sections that contain a highlight, in the order of the document, and each highlight is inside a mark.
formats takes markdown, html, and json. In json the text comes as blocks, and each block lists its highlights as highlight_ids. The record’s own text is never changed by a call. The marks are in the response only. If the sections with highlights are larger than max_characters, they come while they fit, and the last one is cut at the edge of a block with its marked blocks inside. truncated is then true.

Give each question its own color

A screen that shows the source needs one more step: a color for each string. The mark’s id leads to its highlight, and the highlight’s query_index leads to the string. This function adds a class to each mark of an html response.
The reader of a contract review then sees 5 questions answered in 5 colors on the agreement itself, and your code has split no text and searched no text.

Tell a quote from a judgment

Each highlight says in basis how it was found. A quotation in a report should rest on an exact or a near highlight, because those are found without a model and are the same on every call. Treat a judged highlight as a passage to read. A model chose it, and another run can choose another block. To allow only highlights found word for word, send deterministic_only as true. No model runs then. A string that is not in the text makes the notice highlight_not_found, one notice for each string, and the call still succeeds. On a scanned page the strings are matched against the recognized words, and each highlight has the confidence of its block. A recognition error in the scan is not forgiven by exact or by near.

Cite a highlight by its block

The place of a highlight is a section, a block, and the words as found: each highlight has a section_id and a block_id. On a document with pages it also has page_number, the position of the page in the file, and page_label, the number printed on the page. Inside a table it has row and column. The place is never a count of characters, because a count would change with every format and every mark. The ids of sections and blocks are the same on every read of a record. A citation that names the record and the block can be opened again by you, by a second agent that checks the work, or by a person. To read the whole block around a highlight, list the record’s blocks by id.
Replace BLOCK_ID with the block_id of the highlight.

Highlight while you fetch

fetch_contents and upload_contents take the same highlights field, so a source can be fetched and searched in one call. A search takes it for the results that it fetches, in contents.highlights.
Replace SOURCE_URL with the address of a page or a document. On a fetch the highlights also decide which text comes back from a long source. If the text is larger than max_characters and a highlight was found, the response has the sections that contain highlights, with the reason matching_sections, and the outline of the whole. You get the passages that bear on your questions, and the rest of the source stays in the record for a later read. The record stores the highlights of its fetch. get_contents returns them later with the marks in whatever text it returns.

Check what a call costs

A call in which every string is found word for word costs nothing. If a model judges any string, the call costs one model step, whatever the number of strings. highlight_contents needs a key with the scope contents:read. It also needs contents:model, because a string can need a model, unless the request sends deterministic_only as true.