Get section
Read one section of a record, free: its text when it fits, its own text and the rows of its child sections when it does not, and a page of its text when a cut is needed.
cnt_ id and the section’s s id from the map, sections, which a fetch returns when the text did not fit or when max_characters was 0. s0 is the text before the first heading; on a page without headings it is the whole document. Use get_contents for the whole record; use list_blocks for the blocks of a section by kind.
What it costs
The key needscontents:read. The call is free.
What comes back
200 with SectionContents: first the record’s id, address, fetch time, fingerprint, version and configuration, then its new expires_at, then the section’s row, then its text in the formats asked for, or its child rows.
- The section fits
max_characters: its text comes whole in the formats asked;truncatedis false; nosections. - It does not fit and has child sections: its own text before the first child comes, with
sections, the child rows, on this first page only;truncatedis true; nonext_page_token, since each child is read by its own id. - It does not fit and has no children, or its own text alone does not fit: the text is cut at a block edge;
truncatedis true;next_page_tokencontinues it. - One block larger than the bound: the text is cut inside the block, at a row, an item, a line or a sentence edge;
truncatedis true;next_page_tokencontinues it. max_characters: 0: the row and the child rows, no text;truncatedis false.linksare the section’s links, narrowed byblock_kinds; they come under0too.- The token binds the other parameters; a change is
400 page-token-invalid. It is alive as long as the record, and a page that carriesnext_page_tokenalways has text.
Refused before any work
- A value outside its set,
max_charactersbetween 1 and 999, a duplicate or an empty list:400 invalid-request,not_allowed,boundorduplicate, each with where it is. - An id of the wrong kind:
400 invalid-request, before any lookup. - A token of another record, another section or another query:
400 page-token-invalid. - A record that failed, was refused or needs a person:
409 record-without-content,changenamingfetch_contents. - An unknown query parameter:
400 invalid-request,unknown_field.
Notices this operation makes
sections_cut, links_cut, field_not_applicable, version_retiring, after the record’s own notices.
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.fieldsayingcontents_idorsection_id. - 409
record-without-content, The record has no content. - 410
contents-expired, The record has expired. - 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
Query Parameters
The formats to return, over this section, 1 to 5 of these, one value per repeated key: markdown, the text as one markdown string; html, as clean HTML; doclang, as DocLang, an XML that keeps each block with its place on the page, on a page or an HTML file only; json, as Block objects; links, the section's links with their kinds. Default markdown. An open set; a key sent with an empty value is an empty list, refused bound, and a repeated value is refused duplicate.
1 - 5 elementsOne of the formats the field lists.
1Keep only blocks of these kinds, over this section: 1 to 10 of text, heading, code, math, divider, interactive, table, image, embed, media, an open set, one value per repeated key. Default: every kind.
1 - 10 elementsOne of the block kinds the field lists.
1Response
The section, SectionContents: the record's id and facts, the record's new expires_at, the section's row, its text in the formats asked for or its child rows, truncated, and next_page_token while a cut continues.
One section of a record, the answer of get_section. First the id and facts of the record the section comes from, and its new expires_at; then the section's row; then its text in the formats asked for, or its child rows when the whole section did not fit.