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


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