List datasources
List the places getclean can search, free; the answer may be cached for an hour.
id, its group or set:NAME goes into the search’s datasources; filters and operators say what each source honors, before any search; issuers gives the codes an identifier scheme takes, so your agent learns a code from the catalog and never guesses one. Every filter you send must match, and the order is the catalog’s own.
What it costs
The key needssearch:read. The call is free. The answer is 200 with DatasourcePage and Cache-Control: max-age=3600, so a cached answer repeats the first call’s request_id and rate figures, which describe that call and not yours.
Paging
page_size from 1, default 50, maximum 200, a larger value lowered with the notice page_size_lowered; page_token is opaque, bound to its query, alive 24 hours; next_page_token is absent on the last page, and a page that carries it holds at least one entry.
Refused before any work
A value outside its set or range,page_size above its maximum excepted, which is lowered: 400 invalid-request, not_allowed or bound, each with where it is. A token of another list: 400 page-token-invalid. An unknown query parameter: 400 invalid-request, unknown_field.
Notices this operation makes
page_size_lowered.
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. - 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
Response
One page of the catalog, in its own order; next_page_token while more remain.
One page of the catalog, the answer of list_datasources, in the catalog's own order.