Get datasource
Read one entry of the catalog whole, free; the answer may be cached for an hour. You get what the source covers, how it is reached, which filters and operators it honors, which identifier schemes it resolves and with which issuer codes, and whether it keeps history for as_of_date.
What it costs
The key needssearch:read. The call is free. The answer is 200 with Datasource and Cache-Control: max-age=3600.
Refused before any work
An id of the wrong form, other than 1 to 64 ofa-z, 0-9 and _ with a letter first: 400 invalid-request, syntax, before any lookup. An unknown query parameter: 400 invalid-request, unknown_field.
Problem types
- 400
invalid-request, The request 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: no entry has this id. - 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
Response
The entry whole.
One entry of the catalog: a place getclean can search, what it covers and what it honors, known before any search.
What the source honors of the twelve hard filters, before any search, keyed by their names, allowed_domains, blocked_domains, published_from, published_until, published_within_days, undated, languages, media_types, safe_search, source_kinds, source_independence, as_of_date, every name always present.