Skip to main content
GET
Get datasource

What it costs

The key needs search: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 of a-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

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

datasource_id
string
required

The catalog's id, 1 to 64 of a-z, 0-9 and _, a letter first, as web and courtlistener.

Pattern: ^[a-z][a-z0-9_]{0,63}$

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.

id
string
required

The entry's id, the value the search's datasources takes.

Pattern: ^[a-z][a-z0-9_]{0,63}$
Example:

"courtlistener"

display_name
string
required

The entry's display name.

Example:

"CourtListener"

group
string
required

The group the entry belongs to, web or a group the catalog publishes, an open set; a group name goes into the search's datasources too.

Example:

"web"

countries
string[]
required

The countries it covers, ISO 3166-1 alpha-2; [] means every country, as web.

Pattern: ^[A-Z]{2}$
languages
string[]
required

The languages it covers, BCP 47; [] means every language, as web.

access
object
required

How the source is reached, and its fee when it charges per query.

searchable
boolean
required

Whether getclean can search it; a source it cannot search is datasource-not-searchable when named.

filters
object
required

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.

operators
object
required

What the source honors of the ten query operators, keyed by phrase, exclusion, alternatives, site, filetype, intitle, inurl, before, after, wildcard, every name always present; alternatives stands for the or operator.

identifier_schemes
string[]
required

The identifier schemes the source resolves, values of SubjectIdentifier.scheme; [] when none.

history
boolean
required

Whether as_of_date is honored; a source without history reports no_history.

card_url
string<uri>
required

The entry's own page in the catalog, with its full description.

Example:

"https://api.getclean.ai/datasources/courtlistener"

request_id
string
required

The id of the call this entry came back in, the same as that call's Request-Id header.

Pattern: ^req_[A-Za-z0-9]{22}$
Example:

"req_02DBMPlcTpjeCo52E9vS45"

issuers
object

For each scheme that takes an issuer, ticker, docket, tax_id and registry, the issuer codes this source resolves, so your agent learns a code from the catalog and never guesses one. Present when the source resolves such a scheme.