# Set up the Datalab API (instructions for coding agents)

Give your project document understanding without building an OCR or parsing stack.
Datalab turns PDFs, scans, Office files, spreadsheets and images into readable
Markdown, HTML or structured JSON. Use it to feed a RAG pipeline, extract fields
from contracts and invoices, or automate document workflows with the Python SDK
and CLI.

## Pick the right capability

| Capability | Use it for | Modes and options |
| --- | --- | --- |
| Convert | Turn documents into text and layout-aware output for search, RAG and analysis. | `lite` for text, tables and lists without images or LLM passes; `fast` / `balanced` for general parsing; `accurate` for demanding layouts and tables. |
| Extract | Get the fields your application needs as JSON using your schema. | `turbo` for image-based extraction without a separate parse; `fast` for extraction with source citations; `balanced` / `accurate` for multi-pass verification. |
| Segment | Split a combined upload into its constituent documents before processing them. | Choose `fast`, `balanced` or `accurate` to suit the document. |
| Form fields and fill | Find fillable fields and fill PDF or image forms. | Use `form-fields` to inspect a form, then `fill` with the desired values. |
| Track changes | Extract edits and comments from Word documents, PDFs and scans. | Use the `track-changes` command or the SDK. |
| Document agent (open beta) | Run an existing published agent processor for a document task. | Use `agent` with the published processor ID; the open-beta API may change. |

Combine supported steps in a saved pipeline for repeatable workflows. Start with
the capability your project needs, then choose the speed, quality and cost trade-off
from the [current mode and pricing guide](https://www.datalab.to/pricing.md).
Rates differ by processor, mode and add-on; do not treat the free allowance as a
fixed number of pages. For request options and examples, follow the
[SDK documentation](https://documentation.datalab.to/docs/welcome/sdk).

Follow the setup below to make a first API call.

## Rules for the API key

- Do not ask the person to paste the API key into this chat.
- Never write the key into source files, notebooks, config that is committed, or logs.
- Keep it in the SDK's saved login, an environment variable (`DATALAB_API_KEY`), or a
  secret manager. If the project uses a `.env` file, check that `.env` is in `.gitignore`.

## 1. Install the SDK

Python 3.11 or newer:

```bash
pip install -U datalab-python-sdk
```

## 2. Sign in

If `datalab login --help` works (SDK 0.7.0 or newer), run:

```bash
datalab login
```

It prints a link and a code. Show both to the person, exactly as printed. Do not open the
link yourself with browser automation (Playwright, Puppeteer or an agent-controlled browser):
the human check fails in an automated browser. Tell the person:

1. Open the link in their own browser. Sign in, or sign up if they have no account.
2. Check that the code on the page matches, pass the check, and click Approve.
3. Type the 6-digit code that Datalab emails them into the same page.

The command waits until they finish, then saves the key to
`~/.config/datalab/config.json`, readable only by their user. The SDK and the
`datalab` CLI use it from then on.

If `datalab login` is not available, ask the person to create a key at
https://www.datalab.to/app/keys and to set it themselves, for example in their shell
profile or secret manager:

```bash
export DATALAB_API_KEY="<their key>"
```

## 3. Check that it works

Convert a document from the project, or any PDF:

```bash
datalab convert document.pdf
```

Or in Python:

```python
from datalab_sdk import DatalabClient

client = DatalabClient()  # uses the saved login or DATALAB_API_KEY
result = client.convert("document.pdf")
print(result.markdown[:500])
```

## 4. Know the limits

- New accounts get a free monthly allowance: $20 with a work email, $10 with a
  personal one. Usage depends on the processor, mode and add-ons; check the
  [current pricing](https://www.datalab.to/pricing.md) before choosing a mode.
- When the allowance runs out, the API returns HTTP 402 with the header
  `X-Datalab-Error-Code: allowance_exhausted` and a link to billing. Tell the person
  to add a card at https://www.datalab.to/app/subscription. Do not retry in a loop.

## More

- API and SDK docs for agents: https://documentation.datalab.to/llms.txt
- Processors, modes and prices: https://www.datalab.to/pricing.md
- Everything else: https://www.datalab.to/llms.txt