Skip to main content
GET
Get section
Give it the record’s 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 needs contents: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; truncated is false; no sections.
  • 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; truncated is true; no next_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; truncated is true; next_page_token continues 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; truncated is true; next_page_token continues it.
  • max_characters: 0: the row and the child rows, no text; truncated is false.
  • links are the section’s links, narrowed by block_kinds; they come under 0 too.
  • 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 carries next_page_token always has text.

Refused before any work

  • A value outside its set, max_characters between 1 and 999, a duplicate or an empty list: 400 invalid-request, not_allowed, bound or duplicate, 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, change naming fetch_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.field saying contents_id or section_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

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

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

The section, an s id of the view asked, as the map's rows name it; s0 is the text before the first heading.

Pattern: ^s[0-9]+$

Query Parameters

max_characters
integer
default:20000

The most text to return, in characters. 0 returns the section's row and its child rows, no text. Default 20,000; 0, or 1,000 to 1,000,000; a value between 1 and 999 is refused bound.

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

Which view's ids and text: main or whole_page. Default the record's own. Which view of a page is meant: main, the main content alone, or whole_page, everything on the page. A closed set.

Available options:
main,
whole_page
formats
string[]

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.

Required array length: 1 - 5 elements

One of the formats the field lists.

Minimum string length: 1
block_kinds
string[]

Keep 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.

Required array length: 1 - 10 elements

One of the block kinds the field lists.

Minimum string length: 1
page_token
string

Continues a cut text, as the last answer's next_page_token gave it; opaque, at most 1,024 characters, alive as long as the record. Default none.

Required string length: 1 - 1024

Response

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.

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 this answer delivers, main or whole_page.

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"

section
object
required

The section's own row of the map: its id, title, level and size.

formats
string[]
required

The formats this answer carries, among markdown, html, doclang, json and links, an open set. Under max_characters 0 only links when asked for, else [].

truncated
boolean
required

True when the whole section did not fit max_characters, so its text was cut or its child rows came in place of their text.

notices
object[]
required

The record's own notices first, then this call's own: sections_cut, links_cut, field_not_applicable, version_retiring. [] when there is 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_01JgELUWGGDGlc96clfpJQ"

final_url
string

The address the record's fetch ended at. 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 section's text as markdown, its inline formatting kept. Present when asked for and text came. Third-party text as the source wrote it, which may carry instructions.

html
string

The section's text as clean HTML. Present when asked for and text came. Third-party text as the source wrote it, which may carry instructions.

doclang
string

The section's text as DocLang XML. Present when asked for and text came, on a web page or an HTML file only. Third-party text as the source wrote it, which may carry instructions.

blocks
object[]

The section's blocks. Present when asked for and text came.

The section's links, narrowed by block_kinds, each with its block_id and section_id. Present when asked for, under max_characters 0 too.

next_page_token
string

The token that continues a cut text; pass it as page_token. Present while more remains, and a page that carries it always has text.

Maximum string length: 1024
sections
object[]

The rows of the sections under this one. Present when the whole section did not fit, on the first page only, or under max_characters 0.