> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runautomat.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runautomat.com/_mcp/server.

# Extractors

## What is an Extractor?

An extractor is a reusable configuration that defines:

1. **Schema** - What fields to extract and their types
2. **Model Tier** - Which AI model to use (Mini, Pro, or Max)
3. **Validation Rules** - Optional constraints on extracted values

Think of an extractor as a template that tells Automat exactly what information to pull from
your documents.

## Creating an Extractor

### Via Dashboard

1. Navigate to your project in the [Automat Dashboard](https://studio.runautomat.com)
2. Click **Create Extractor**
3. Name your extractor (e.g., "Invoice Extractor")
4. Define your schema using the visual editor or JSON
5. Test with sample documents
6. Publish when ready

### Schema Definition

Schemas define the structure of extracted data:

```json
{
  "invoice_number": {
    "type": "string",
    "description": "The unique invoice identifier"
  },
  "date": {
    "type": "string",
    "description": "Invoice date in YYYY-MM-DD format"
  },
  "total_amount": {
    "type": "number",
    "description": "Total amount due"
  },
  "line_items": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "description": { "type": "string" },
        "quantity": { "type": "number" },
        "unit_price": { "type": "number" }
      }
    }
  }
}
```

## Supported Field Types

| Type      | Description                         | Example                                     |
| --------- | ----------------------------------- | ------------------------------------------- |
| `string`  | Text values                         | `"INV-001"`                                 |
| `number`  | Numeric values (integer or decimal) | `1250.00`                                   |
| `boolean` | True/false values                   | `true`                                      |
| `array`   | List of values                      | `["item1", "item2"]`                        |
| `object`  | Nested object                       | `{ "name": "...", "address": "..." }`       |
| `enum`    | Predefined set of values            | `"approved"` \| `"pending"` \| `"rejected"` |

## Model Tiers

Choose the right model tier for your use case:

#### Mini

**Speed-first** Optimized for simple extraction tasks and high volume. *Default backend: Google Gemini 3.5
Flash-Lite (`gemini-3.5-flash-lite`)*

#### Pro

**Balanced** Reliable accuracy with moderate latency—good default for most production documents. *Default backend:
Google Gemini 3.7 Flash (`gemini-3.7-flash`)*

#### Max

**Highest accuracy** Reasoning-oriented model for difficult layouts, poor scans, or critical fields. *Default
backend: Google Gemini 3.1 Pro (`gemini-3.1-pro-preview`)*

## Using Extractors

### Get Extractor ID

Every extractor has a unique ID (e.g., `ext_abc123`). Find it in:

* The extractor detail page in your dashboard
* The URL when viewing an extractor

### Make Extraction Requests

```bash
curl -X POST https://studio.runautomat.com/api/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "extractorId=ext_abc123" \
  -F "file=@document.pdf"
```

## Versioning

Extractors support versioning for production stability:

* **Draft** - Work in progress, can be modified freely
* **Published** - Locked version for production use
* Multiple published versions can exist simultaneously

> **Note**
>
> When you publish an extractor, the model configuration is frozen. This ensures consistent extraction results even as
> underlying models improve.

## Best Practices

#### Use Descriptive Field Names

Clear field names help the AI understand what to extract:

✅ `invoice_date`, `total_amount_due`, `vendor_address`

❌ `field1`, `date`, `val`

#### Add Field Descriptions

Include descriptions to guide extraction, especially for ambiguous fields:

```json
{
  "effective_date": {
    "type": "string",
    "description": "The date the contract becomes effective, not the signing date"
  }
}
```

#### Test with Varied Documents

Before publishing, test your extractor with documents that have:

* Different layouts
* Various quality levels
* Edge cases (missing fields, unusual formats)

#### Start Simple, Then Expand

Begin with core fields, validate accuracy, then add more complex extractions.

## Next Steps

#### [Schema Reference](/guides/concepts/schemas)

Advanced schema configuration

#### [API Reference](/api-reference)

Extract endpoint documentation