Skip to main content
GET
List datasources
An entry’s 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 needs search: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

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.

Query Parameters

group
string

Only this group, web or a group the catalog publishes, an open set, 1 to 64 characters. Default none.

Required string length: 1 - 64
country
string

Only sources that cover this country, ISO 3166-1 alpha-2. Default none.

Pattern: ^[A-Z]{2}$
Example:

"US"

language
string

Only sources that cover this language, BCP 47, 1 to 35 characters. Default none.

Required string length: 1 - 35
Example:

"en"

access
string

Only sources reached this way: open, no login; registered, a login the account owner registers; paid, a fee per query. An open set. Default none.

Minimum string length: 1
Examples:

"open"

"registered"

"paid"

page_size
integer
default:50

At most this many entries on the page, from 1; default 50; the maximum, 200, stands in Limits.bounds, and a larger value is lowered with the notice page_size_lowered.

Required range: x >= 1
page_token
string

The next page, as the last answer's next_page_token gave it; opaque, at most 1,024 characters, never built by the caller. Default none, the first page.

Required string length: 1 - 1024

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.

datasources
object[]
required

The entries of this page; [] when none matches.

notices
object[]
required

This call's notices, page_size_lowered; [] 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_02EtiTZXJiQkv6q3XFlqUa"

next_page_token
string

The token for the next page; pass it as page_token. Present while more remains, and a page that carries it always has at least one entry.

Maximum string length: 1024