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

# Authenticate a request

> Send an API key or an access token as a bearer credential with every call. Each key has a list of scopes, and a call outside that list is refused before any work is done or charged.

Every call has one header, `Authorization`, with a bearer credential: an API key, or an access token. The credential says which account the call belongs to and what the call can do.

## Send the key

Create an API key at `https://app.getclean.ai` and put it in the environment variable `GETCLEAN_API_KEY`. The SDKs read it from there.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/limits \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

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

client = GetClean()

limits = client.get_limits()
```

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

const client = new GetClean();

const limits = await client.getLimits();
```

`get_limits` costs nothing and returns what the key can do, so it is a good first call. To give the key in code, pass it as `api_key` in Python and as `apiKey` in TypeScript.

## Give a key the scopes it needs

A key has a list of scopes, and it can do nothing that is not on the list. A key for an agent that only reads stored records needs one scope, and a stolen copy of it cannot fetch or spend.

| Scope | What it allows |
| - | - |
| `contents:fetch` | To fetch a page or a document, to upload a file, and to fetch a batch. |
| `contents:read` | To read a stored record, its sections, blocks, and links, to list records, and to compare 2 records. |
| `contents:model` | To ask for a summary, a filled schema, or highlights that a model can judge. |
| `contents:delete` | To delete a record. |
| `search:run` | To search and to run a batch of searches, with the fetches a search makes. |
| `search:read` | To read a stored search and the catalog of datasources. |
| `jobs:read` | To read the jobs of long uploads. |
| `jobs:cancel` | To cancel a job. |
| `limits:read` | To read the account's balance, prices, and limits. |

`contents:model` depends on the request. A fetch needs it only if the request asks for work by a model: a summary, a schema, or highlights without `deterministic_only`.

## Use an access token for a person

A program that acts for a person can send an access token in place of a key. The token is issued at `https://auth.getclean.ai/realms/getclean` after the person signs in, and its scopes are the ones that person approved. The steps of the sign-in are at `https://auth.getclean.ai/auth.md`.

A token expires, so the SDKs also take a function in place of the value. The function is called once for each call and returns the current token.

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


def current_token() -> str:
    return load_token()


client = GetClean(api_key=current_token)
```

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

async function currentToken(): Promise<string> {
    return loadToken();
}

const client = new GetClean({ apiKey: currentToken });
```

`load_token` and `loadToken` are your own functions that return the token your sign-in stored.

## Act on a refused credential

A call without a credential that the API accepts returns the problem `unauthorized`, with the status code 401. Its `detail` says which of 3 things happened: no credential was sent, the credential is unknown, expired, or revoked, or the credential was put in the address of the request, where it is ignored.

A call with a credential that lacks a scope returns the problem `insufficient-scope`, with the status code 403. This response is cut to the fields that say what to do.

```json 403 Forbidden theme={"theme":"css-variables"}
{
  "type": "https://api.getclean.ai/problems/insufficient-scope",
  "title": "The key lacks a scope this call needs",
  "who_must_act": "account_owner",
  "retryable": false,
  "scopes_required": ["contents:model"]
}
```

`scopes_required` lists every scope the call needs. For an API key, the owner of the account adds the scope. For an access token, ask the person to approve it.

Both refusals come before any work, so nothing is charged. For the other problems, see [Errors](https://docs.getclean.ai/understand/errors.md).

## Keep the key on a server

A key is a secret of a server or a program. The API sends no headers that let a web page call it from a browser, so a key that is put into a page fails at once and is not leaked by use.

The API takes HTTPS only. A request over plain HTTP is refused and not redirected, so a key and a request body are not sent a second time in the clear.


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