List links
List the links of a record, free: every link with its kind and the block and section that hold it, in document order, one page of results at a time, without the 1,000-link cap a fetch puts on formats: links.
cnt_ id and the filters you want; every filter you send must match. Use fetch_contents to read a linked page; use list_blocks for the blocks themselves.
What it costs
The key needscontents:read. The call is free.
What comes back
200 with LinkPage: the record’s id and facts, the record’s new expires_at, the links, each with its kind and its place, and next_page_token while more remain.
- The order is the document order of the blocks that hold the links.
kindis read from the address alone, a guess: no request is made for any link, so a link carries no size and no served type.externalcompares the link’s host with the final URL’s registrable domain; a link without a host,mail,phoneorfragment, is left out under either value of the filter.- No link matching:
200with[]. page_sizeis from 1, default 50, maximum 200; a larger value is lowered with the noticepage_size_lowered, never refused.page_tokenis bound to its query and its record and is alive as long as the record;next_page_tokenis absent on the last page, and a page that carries it has at least one link.
Refused before any work
- A value outside its set or range, a duplicate or an empty list:
400 invalid-request,not_allowed,boundorduplicate, each with where it is;page_sizeabove its maximum is lowered instead. - An id of the wrong kind:
400 invalid-request, before any lookup. - A token of another record or another query:
400 page-token-invalid. - A
section_idthe record does not hold:404 not-found,change.fieldnaming it. - A record that failed, was refused or needs a person:
409 record-without-content. - An unknown query parameter:
400 invalid-request,unknown_field.
Notices this operation makes
page_size_lowered, 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.
Query Parameters
Keep only links of these kinds: 1 to 7 of file, a file such as a PDF; page, another page; fragment, a place inside the same page; mail, an email address; phone, a phone number; feed, an RSS or Atom feed; other, anything else. An open set, one value per repeated key. Default: every kind.
1 - 7 elementsOne of the link kinds the field lists.
1Response
One page of the record's links, LinkPage, each with its kind and its place, with the record's id and facts and the record's new expires_at; next_page_token while more remain.
One page of a record's links, the answer of list_links. First the record's id and facts, and the record's new expires_at; then the links, each with its kind and its place; then next_page_token while more remain.