# Summarize

> Generate configurable AI summaries at multiple depths.

A **Summarization** distills a document into a title and a summary, at the depth you choose.

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Raw Document&#x22;<small><br/>e.g. 50-Page Legal Policy</small>] --> B[&#x22;Language Model<br/><small>Length: &quot;short&quot;</small>&#x22;]
  B --> C[&#x22;Title + Summary&#x22;]
`"
/>

* **Adjustable Depth**: choose between a brief overview and a detailed summary.
* **Contextual Instructions**: add instructions to steer the focus or the language of the summary.

***

## 🏗️ Configuration

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

| Parameter      | Type     | Default              | Description                                                                  |
| :------------- | :------- | :------------------- | :--------------------------------------------------------------------------- |
| `length`       | `string` | `medium`             | Summary depth: `short`, `medium`, or `long`.                                 |
| `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 10,000 characters of the parsed Document; when it is longer, the Output reports `truncated: true`.

***

## 🛠️ Summarize a Document

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

### [Submit a Summarization](https://docs.axelered.com/reference/summarizations/api_create_summarizations_post)

```bash
curl -X POST "https://api.axelered.com/v1/summarizations?wait=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/legal_policy.pdf" \
  -F 'config={"length": "short", "parsing": {"tier": "accurate"}}'
```

Once the Summarization is `done`, the summary is in its `output`:

```json
{
  "status": "done",
  "output": {
    "value": { "length": "short", "title": "...", "summary": "..." },
    "truncated": false
  }
}
```

### List, Read & Delete

* [**List Summarizations**](https://docs.axelered.com/reference/summarizations/api_list_summarizations_get): newest first, optionally for one Document with `?documentId=`. Lists leave out the `output`.
* [**Read Summarization**](https://docs.axelered.com/reference/summarizations/api_read_summarizations__job_id__get): status, credits and `output`, with optional `wait`.
* [**Delete Summarization**](https://docs.axelered.com/reference/summarizations/api_delete_summarizations__job_id__delete): hide a Summarization. Its Document is kept.