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

# Autype Lens

> AI-powered document understanding — OCR, classification, filename generation, and structured data extraction

Autype Lens is a suite of AI-powered endpoints for document understanding. Under the hood, Lens combines modified open-source models to provide both stability and comprehensive functionality for processing PDFs, DOCX, ODT, and Markdown files.

All Lens endpoints follow the standard [tools job workflow](/api-reference/tools/placeholder-replacement#how-it-works): upload a file, create a job, poll for completion, read the result.

## Endpoints

| Endpoint                             | Description                             | Cost                                                         |
| ------------------------------------ | --------------------------------------- | ------------------------------------------------------------ |
| `POST /tools/lens/ocr`               | Extract text from a document            | 2 credits/page for `md`; 18 credits/page for `mdd` or `json` |
| `POST /tools/lens/generate-filename` | Generate a structured filename          | 6 credits (flat)                                             |
| `POST /tools/lens/classify`          | Classify a document into categories     | 6 credits (flat)                                             |
| `POST /tools/lens/extract`           | Extract structured data from a document | 14 credits per page                                          |

## Supported file types

All Lens endpoints accept the following file types:

| Format   | MIME type                                                                 |
| -------- | ------------------------------------------------------------------------- |
| PDF      | `application/pdf`                                                         |
| DOCX     | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| ODT      | `application/vnd.oasis.opendocument.text`                                 |
| Markdown | `text/markdown`                                                           |

## Limits

| Limit                               | Value                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------- |
| Maximum file size                   | 50 MB                                                                                 |
| Maximum PDF pages                   | 20 on Engine; 150 on Editor, Pro, Pro trial, and Team; custom/unlimited on Enterprise |
| Maximum pages processed (extract)   | 50 pages                                                                              |
| Maximum categories (classify)       | 50                                                                                    |
| Minimum categories (classify)       | 2                                                                                     |
| Maximum fields (extract)            | 30                                                                                    |
| OCR output formats `mdd` and `json` | PDF only                                                                              |
| Page selection (`pages` parameter)  | PDF only                                                                              |

***

## OCR

Extract text from a document. Returns the document content as Markdown.

### Output formats

| Format | Description                                                              | Supported input          |
| ------ | ------------------------------------------------------------------------ | ------------------------ |
| `md`   | Standard Markdown — raw text extraction                                  | PDF, DOCX, ODT, Markdown |
| `mdd`  | Autype extended Markdown with document settings, defaults, header/footer | PDF only                 |
| `json` | Full Autype document JSON with sections and elements                     | PDF only                 |

<Warning>
  The `mdd` and `json` output formats are only available for PDF files. For DOCX, ODT, and Markdown files, use `md`.
</Warning>

### Page selection

For PDF files with `md` output format, you can optionally select specific pages using the `pages` parameter:

```json theme={null}
{
  "fileId": "your-file-id",
  "outputFormat": "md",
  "pages": ["1", "3-5", "10-"]
}
```

Page spec syntax:

* `"3"` — single page
* `"2-5"` — page range (inclusive)
* `"10-"` — from page 10 to end

If `pages` is omitted, all pages are processed.

### Example request

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/lens/ocr \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "your-file-id",
    "outputFormat": "md"
  }'
```

### Example result

```json theme={null}
{
  "id": "job-id",
  "action": "lens.ocr",
  "status": "COMPLETED",
  "result": {
    "outputFormat": "md",
    "content": "# Invoice\n\nInvoice Number: INV-2026-001\nDate: 2026-03-15\n\n| Item | Amount |\n|------|--------|\n| Service A | €500.00 |\n| Service B | €250.00 |\n\n**Total: €750.00**"
  }
}
```

### Cost

Plain `md` output costs **2 credits per processed page**. Document recovery
to `mdd` or `json` costs **18 credits per processed page**. For DOCX, ODT,
and Markdown files, plain Markdown extraction is counted as one page.

***

## Generate Filename

Generate a structured filename for a document based on a naming schema with placeholders. The AI reads the document and fills in the placeholder values.

### Request

```json theme={null}
{
  "fileId": "your-file-id",
  "filenameSchema": "invoice-{invoiceNr}-{dateCreated}"
}
```

| Property         | Type   | Required | Description                                                |
| ---------------- | ------ | -------- | ---------------------------------------------------------- |
| `fileId`         | string | **Yes**  | File ID of the uploaded document.                          |
| `filenameSchema` | string | **Yes**  | Filename template with `{placeholder}` tags.               |
| `webhook`        | object | No       | Optional [webhook configuration](/api-reference/webhooks). |

### Example result

```json theme={null}
{
  "id": "job-id",
  "action": "lens.generate-filename",
  "status": "COMPLETED",
  "result": {
    "generatedFilename": "invoice-INV-2026-001-2026-03-15",
    "placeholders": {
      "invoiceNr": "INV-2026-001",
      "dateCreated": "2026-03-15"
    }
  }
}
```

If a placeholder value cannot be found in the document, it is replaced with `unknown`.

### Cost

**6 credits** per request. For PDFs, only the first three pages are sent to OCR.

***

## Classify

Classify a document into one of the provided categories. The AI reads the first 3 pages of the document and picks the best matching category.

### Request

```json theme={null}
{
  "fileId": "your-file-id",
  "categories": ["Invoice", "Contract", "Offer", "Delivery Note", "Other"]
}
```

| Property     | Type      | Required | Description                                                |
| ------------ | --------- | -------- | ---------------------------------------------------------- |
| `fileId`     | string    | **Yes**  | File ID of the uploaded document.                          |
| `categories` | string\[] | **Yes**  | Array of category names (min 2, max 50).                   |
| `webhook`    | object    | No       | Optional [webhook configuration](/api-reference/webhooks). |

### Example result

```json theme={null}
{
  "id": "job-id",
  "action": "lens.classify",
  "status": "COMPLETED",
  "result": {
    "category": "Invoice",
    "confidence": 0.95,
    "reasoning": "The document contains an invoice number, line items with prices, and a total amount, which are characteristic of an invoice."
  }
}
```

### Result fields

| Field        | Type   | Description                                                    |
| ------------ | ------ | -------------------------------------------------------------- |
| `category`   | string | The selected category — always one of the provided categories. |
| `confidence` | number | Confidence score between 0 and 1.                              |
| `reasoning`  | string | Brief explanation of why this category was chosen.             |

### Edge cases

* **Empty document**: Returns the first category with `confidence: 0` and a message indicating the document is empty.
* **No clear match**: The closest category is returned with a low confidence score.
* The AI will never invent new categories — it always picks from the provided list.

### Cost

**6 credits** per request. For PDFs, only the first three pages are sent to OCR.

***

## Extract

Extract structured data from a document based on a user-defined field schema. Define field names, types, and optional descriptions. The AI reads the document and returns a JSON object with the extracted values.

### Request

```json theme={null}
{
  "fileId": "your-file-id",
  "fields": {
    "invoiceNumber": {
      "type": "string",
      "description": "The invoice number, usually in format INV-XXXX"
    },
    "totalAmount": {
      "type": "number",
      "description": "Total amount including VAT"
    },
    "invoiceDate": {
      "type": "date",
      "description": "Date the invoice was issued"
    },
    "isPaid": {
      "type": "boolean"
    },
    "lineItems": {
      "type": "array",
      "description": "List of line items with description and amount"
    }
  },
  "pages": ["1-2"]
}
```

| Property  | Type      | Required | Description                                                                                                   |
| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `fileId`  | string    | **Yes**  | File ID of the uploaded document.                                                                             |
| `fields`  | object    | **Yes**  | Field definitions (min 1, max 30). Each key is a field name, value defines `type` and optional `description`. |
| `pages`   | string\[] | No       | Page selection for PDFs (same syntax as OCR). If omitted, up to 50 pages are processed.                       |
| `webhook` | object    | No       | Optional [webhook configuration](/api-reference/webhooks).                                                    |

### Field types

| Type      | Description    | Example value                                   |
| --------- | -------------- | ----------------------------------------------- |
| `string`  | Text value     | `"INV-2026-001"`                                |
| `number`  | Numeric value  | `750.00`                                        |
| `boolean` | True/false     | `true`                                          |
| `date`    | Date value     | `"2026-03-15"`                                  |
| `array`   | List of values | `[{"description": "Service A", "amount": 500}]` |

Adding a `description` to a field helps the AI understand what to look for and significantly improves extraction accuracy.

### Example result

```json theme={null}
{
  "id": "job-id",
  "action": "lens.extract",
  "status": "COMPLETED",
  "result": {
    "data": {
      "invoiceNumber": "INV-2026-001",
      "totalAmount": 750.00,
      "invoiceDate": "2026-03-15",
      "isPaid": false,
      "lineItems": [
        { "description": "Service A", "amount": 500.00 },
        { "description": "Service B", "amount": 250.00 }
      ]
    },
    "fieldsMissing": []
  }
}
```

### Result fields

| Field           | Type      | Description                                                                         |
| --------------- | --------- | ----------------------------------------------------------------------------------- |
| `data`          | object    | Extracted values. Keys match the field names from the request.                      |
| `fieldsMissing` | string\[] | List of field names that could not be found in the document (values set to `null`). |

### Edge cases

* **Field not found**: The field is set to `null` and its name is added to `fieldsMissing`.
* **Empty document**: All fields are returned as `null` and all field names appear in `fieldsMissing`.
* **PDF exceeds 50 pages**: Only the first 50 pages are processed when no `pages` parameter is specified.

### Cost

**14 credits per page** processed. For DOCX, ODT, and Markdown files, cost is
14 credits (counted as one page).

***

## General workflow

All Lens endpoints follow the same async job pattern:

### 1. Upload the document

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/files/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@document.pdf"
```

### 2. Create a Lens job

```bash theme={null}
curl -X POST https://api.autype.com/api/v1/dev/tools/lens/classify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "your-file-id",
    "categories": ["Invoice", "Contract", "Report"]
  }'
```

### 3. Poll for completion

```bash theme={null}
curl https://api.autype.com/api/v1/dev/tools/jobs/{jobId} \
  -H "X-API-Key: YOUR_API_KEY"
```

Poll until `status` is `COMPLETED` or `FAILED`. Alternatively, use a [webhook](/api-reference/webhooks) to receive a notification when the job finishes.

### 4. Read the result

The result is returned directly in the job response under the `result` field — there is no separate file to download. This applies to all Lens endpoints.

<Info>
  Unlike PDF tool jobs (merge, split, etc.), Lens jobs return structured data in the `result` field instead of producing an output file. You do not need to call the download endpoint.
</Info>