# Classify

> AI taxonomy classification to categorize documents automatically.

A **Classification** picks the category of a document out of a list you define. It reads the document content and maps it to the most relevant category, with a motivation, enabling automated sorting and routing of incoming files.

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Incoming File<br/><small>e.g. Scanned legal form</small>&#x22;] --> B[&#x22;Language Model<br/><small>[invoice, contract]</small>&#x22;]
  B --> C[&#x22;category:<br/><small>&quot;contract&quot;</small>&#x22;]
`"
/>

* **Your Taxonomy**: each category has a name and a description that tells the model when to pick it.
* **Semantic Reasoning**: the model understands context and intent, classifying files even without specific keyword matches.
* **No Forced Choice**: by default the model may return no category when the file fits none.

***

## 🏗️ Configuration

A Classification is an [Operation](https://docs.axelered.com/jobs_guide): it parses the Document, then classifies it.

| Parameter      | Type      | Default              | Description                                                                  |
| :------------- | :-------- | :------------------- | :--------------------------------------------------------------------------- |
| `categories`   | `array`   | required             | At least one `{ "name", "description" }`.                                    |
| `allowEmpty`   | `boolean` | `true`               | Whether the model may return no category.                                    |
| `tier`         | `string`  | `fast`               | `fast` or `accurate`. See [Operation Tiers](https://docs.axelered.com/config_guide#-operation-tiers). |
| `instructions` | `string`  | none                 | Extra instructions for the model.                                            |
| `parsing`      | `object`  | `{ "tier": "fast" }` | How the Document is parsed: `tier` and `pages`. See [Parse](https://docs.axelered.com/parse).         |
| `perimeter`    | `string`  | `external`           | Where your data may go. See [Perimeters](https://docs.axelered.com/config_guide).                     |

The model reads the first 5,000 characters of the parsed Document; when it is longer, the Output reports `truncated: true`.

***

## 🛠️ Classify a Document

For every field and parameter, see the [**Classifications reference**](https://docs.axelered.com/reference#classifications).

### [Submit a Classification](https://docs.axelered.com/reference/classifications/api_create_classifications_post)

```bash
curl -X POST "https://api.axelered.com/v1/classifications?wait=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/legal_form.pdf" \
  -F 'config={
    "categories": [
      { "name": "invoice", "description": "A bill for goods or services" },
      { "name": "contract", "description": "An agreement between parties" }
    ],
    "allowEmpty": false
  }'
```

Once the Classification is `done`, the category is in its `output`:

```json
{
  "status": "done",
  "output": {
    "value": {
      "category": { "name": "contract", "description": "An agreement between parties" },
      "motivation": "..."
    },
    "truncated": false
  }
}
```

### List, Read & Delete

* [**List Classifications**](https://docs.axelered.com/reference/classifications/api_list_classifications_get): newest first, optionally for one Document with `?documentId=`. Lists leave out the `output`.
* [**Read Classification**](https://docs.axelered.com/reference/classifications/api_read_classifications__job_id__get): status, credits and `output`, with optional `wait`.
* [**Delete Classification**](https://docs.axelered.com/reference/classifications/api_delete_classifications__job_id__delete): hide a Classification. Its Document is kept.