> ## 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.

# Find, read, and cite a source in 3 calls

> Install an SDK and take one question from nothing to a passage you can cite. A search finds the source, a highlight finds the passage that bears on your question, and one more call opens that passage again.

This page takes one question, "who has to mark content that an AI system made?", from nothing to a passage you can cite. The first call finds the source. The second reads it and finds the passage. The third opens that passage again, as a reader of your report would.

## Get a key

Create an API key at `https://app.getclean.ai` and put it in your environment. The SDKs and the commands on this page read it from there.

```bash theme={"theme":"css-variables"}
export GETCLEAN_API_KEY="YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your key.

## Install an SDK

The cURL commands on this page need no install. For Python or TypeScript, install the SDK.

```bash Python theme={"theme":"css-variables"}
pip install getclean
```

```bash TypeScript theme={"theme":"css-variables"}
npm install getclean
```

## Find the source

Send the question to `search` in 4 wordings and 3 languages, and ask for official and primary sources first.

```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": "EU AI Act article 50 marking obligations",
    "alternate_queries": [
      "duty to label AI-generated content under the EU AI Act",
      "KI-Verordnung Artikel 50 Kennzeichnungspflicht",
      "règlement IA article 50 obligation de marquage"
    ],
    "ranking_priorities": ["official", "primary"],
    "max_candidates": 3
  }'
```

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

client = GetClean()

search = client.search(
    query="EU AI Act article 50 marking obligations",
    alternate_queries=[
        "duty to label AI-generated content under the EU AI Act",
        "KI-Verordnung Artikel 50 Kennzeichnungspflicht",
        "règlement IA article 50 obligation de marquage",
    ],
    ranking_priorities=["official", "primary"],
    max_candidates=3,
)
first = search.candidates[0]
print(first.title, first.source_profile.kind, first.source_profile.role)
```

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

const client = new GetClean();

const search = await client.search({
    query: "EU AI Act article 50 marking obligations",
    alternate_queries: [
        "duty to label AI-generated content under the EU AI Act",
        "KI-Verordnung Artikel 50 Kennzeichnungspflicht",
        "règlement IA article 50 obligation de marquage",
    ],
    ranking_priorities: ["official", "primary"],
    max_candidates: 3,
});
const first = search.candidates[0];
console.log(first.title, first.source_profile.kind, first.source_profile.role);
```

The results come in rank order. This response is cut to the first result and to the fields that say what it is.

```json 201 Created theme={"theme":"css-variables"}
{
  "candidates": [
    {
      "title": "Regulation (EU) 2024/1689",
      "url": "https://eur-lex.example/ai-act",
      "published_date": "2024-07-12",
      "source_profile": { "kind": "state", "role": "primary" },
      "copy_count": 2
    }
  ]
}
```

The first result is the regulation itself. Its publisher is a state body, it is a primary source, and 2 other sites have the same text.

## Find the passage in the source

Fetch the address of that result, and send your question with the fetch as a highlight. With `max_characters` set to `0`, the response has the outline of the source and the place of the passage, and no page text.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "SOURCE_URL",
    "highlights": ["Who has to mark content that an AI system made?"],
    "max_characters": 0
  }'
```

```python Python theme={"theme":"css-variables"}
record = client.fetch_contents(
    url=first.url,
    highlights=["Who has to mark content that an AI system made?"],
    max_characters=0,
)
place = record.highlights[0]
print(place.basis, place.text)
```

```typescript TypeScript theme={"theme":"css-variables"}
const record = await client.fetchContents({
    url: first.url,
    highlights: ["Who has to mark content that an AI system made?"],
    max_characters: 0,
});
const place = record.highlights?.[0];
console.log(place?.basis, place?.text);
```

In the cURL command, replace `SOURCE_URL` with the `url` of the first result.

The response is a record, the stored copy of the source. This one is cut to the highlight and to one row of the outline, and the words of the passage are shortened.

```json 201 Created theme={"theme":"css-variables"}
{
  "id": "cnt_8Lq5XFriyaJ0jEc2oPNx6E",
  "outcome": { "kind": "delivered", "reason": "whole" },
  "highlights": [
    {
      "id": "h1",
      "query_index": 0,
      "text": "Providers of AI systems … shall ensure …",
      "basis": "judged",
      "section_id": "s4",
      "block_id": "b31"
    }
  ],
  "sections": [
    { "id": "s4", "title": "Article 50", "level": 2, "characters": 9100 }
  ]
}
```

The question has no words in common with the article that bears on it, so a model chose the passage, and `basis` says `judged`. `text` has the regulation's own words, never the model's. The highlight names its place: the section "Article 50", and one block in it.

## Open the passage again

The record's id and the block's id are a citation. Anyone who has them can read the passage from the stored copy, at no charge.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/contents/CONTENTS_ID/blocks?block_ids=BLOCK_ID" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

```python Python theme={"theme":"css-variables"}
for block in client.list_blocks(contents_id=record.id, block_ids=[place.block_id]):
    print(block.text)
```

```typescript TypeScript theme={"theme":"css-variables"}
if (place) {
    for await (const block of await client.listBlocks(record.id, { block_ids: [place.block_id] })) {
        console.log(block.text);
    }
}
```

In the cURL command, replace `CONTENTS_ID` with the `id` of the record and `BLOCK_ID` with the `block_id` of the highlight.

The response has the whole block, as the source has it. A sentence of your report that rests on this passage can name the record and the block, and a reviewer can open it with this call.

## Check what the 3 calls cost

The search is charged one search unit, one unit for each datasource it ran on, and 2 model steps: one for the ranking and one for the choice of datasources. The fetch is charged one unit and one model step, because a model judged the highlight. The read of the block costs nothing. Every charged response has `cost`, with the units and the amount.

For the whole run, from a question to a checked report, see [From a question to a checked report](https://docs.getclean.ai/start/how-it-fits.md).


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