> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getclean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Put primary sources first

> Every search result says what kind of source it is: who publishes it, whether it is primary, independent, and reviewed. Rank by those facts, filter by them, or tell the ranking in your own words what matters.

A search engine orders pages for a person who will read the first one. For a report on the AI strategies of 60 countries, the order that matters is another: the ministry's own text before the commentary on it, the statistics office before the blog. A search here returns what each result is, and you can order the list by it.

## Read what a source is

Each result has a `source_profile` with 4 facts.

| Field | What it says | Values |
| - | - | - |
| `kind` | The kind of publisher. | 24 kinds, such as `state`, `court`, `regulator`, `statistics_office`, `academic`, `press`, `company`, `individual`. |
| `role` | What the page is as a source. | `primary`, `secondary`, `tertiary`. |
| `independence` | Whether the publisher writes about itself. | `self`, `independent`. |
| `review` | The review the publication states. | `peer_reviewed`, `editorial`, `audited`, `externally_validated`, `none`. |

These values are facts about the source, read from what the site declares and from public registers. They are not a score. A fact that cannot be read is `unknown`, and it is not a guess. What a source is worth for your question stays your decision.

## Put the sources that count first

`ranking_priorities` takes up to 4 of these values, in the order you give them.

| Value | Results that come first |
| - | - |
| `official` | Pages of a state body, a court, a regulator, a statistics office, an intergovernmental body, or a standards body. |
| `primary` | Primary sources. |
| `independent` | Sources that are independent of the subject of the search. |
| `reviewed` | Publications with a stated review. |

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/search \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "Brazil national AI strategy compute investment",
    "alternate_queries": [
      "Plano Brasileiro de Inteligência Artificial investimento em infraestrutura computacional",
      "estratégia brasileira de inteligência artificial supercomputador financiamento",
      "Brazil AI plan 2024-2028 budget for computing capacity"
    ],
    "purpose": "The official strategy text decides each cell of a comparison of 60 countries.",
    "ranking_priorities": ["official", "primary"],
    "ranking_instructions": "Put the strategy itself before news about it. Among versions, put the most recent first."
  }'
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean

client = GetClean()

search = client.search(
    query="Brazil national AI strategy compute investment",
    alternate_queries=[
        "Plano Brasileiro de Inteligência Artificial investimento em infraestrutura computacional",
        "estratégia brasileira de inteligência artificial supercomputador financiamento",
        "Brazil AI plan 2024-2028 budget for computing capacity",
    ],
    purpose="The official strategy text decides each cell of a comparison of 60 countries.",
    ranking_priorities=["official", "primary"],
    ranking_instructions="Put the strategy itself before news about it. Among versions, put the most recent first.",
)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const search = await client.search({
    query: "Brazil national AI strategy compute investment",
    alternate_queries: [
        "Plano Brasileiro de Inteligência Artificial investimento em infraestrutura computacional",
        "estratégia brasileira de inteligência artificial supercomputador financiamento",
        "Brazil AI plan 2024-2028 budget for computing capacity",
    ],
    purpose: "The official strategy text decides each cell of a comparison of 60 countries.",
    ranking_priorities: ["official", "primary"],
    ranking_instructions: "Put the strategy itself before news about it. Among versions, put the most recent first.",
});
```

A priority reorders the list and removes nothing. This response is cut to the title and the profile of the first 4 results.

```json 201 Created theme={"theme":"css-variables"}
{
  "candidates": [
    { "title": "Plano Brasileiro de Inteligência Artificial 2024-2028", "source_profile": { "kind": "state", "role": "primary" } },
    { "title": "National AI plan: questions and answers", "source_profile": { "kind": "state", "role": "secondary" } },
    { "title": "Brazil sets out its AI plan", "source_profile": { "kind": "press", "role": "secondary" } },
    { "title": "What the Brazilian AI plan means for cloud providers", "source_profile": { "kind": "company", "role": "secondary" } }
  ]
}
```

The official sources come first, and the news story and the commentary stay under them, where you can still read them for context. Inside each group the results are in order of relevance, or by date if you set `ranking_order` to `newest` or `oldest`.

## Remove the kinds you do not want

To remove results, use a filter. `source_kinds` returns only the kinds of publisher you name.

```json Part of a request theme={"theme":"css-variables"}
{ "source_kinds": ["state", "regulator", "statistics_office", "intergovernmental"] }
```

`source_independence` returns only sources that are independent of the subject, or only the subject's own. It needs a subject that the search can identify, which you give as an identifier, such as a company's registry number.

The response counts what a filter removed. `counts.dropped` has a number for each reason, and `get_search` returns the removed results with the reason for each, at no charge.

## Say in words what matters

The request on this page has 2 fields that take plain sentences. `purpose` says why you search. It is stored with the search and read by every step that a model makes. `ranking_instructions` says how to rank, in your own words.

`purpose` is never sent to a datasource. The response says in `ranking.instructions_applied` whether the instructions were used.

## Keep one site from filling the list

`ranking_preferred_domains` puts results from the sites you name first among results of equal relevance. `ranking_max_per_domain` sets the most results from one site, from 1 to 50.

## Count copies once

A story that 14 sites reprint is one source, and a report that counts it 14 times is wrong. The list shows one result for a group of copies, the copy with the earliest date among them, and `copy_count` says how many others there are.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.