# Parse

> Extract structural layout and text from complex documents into clean Markdown.

A **Parsing** turns a Document into a structured Parsed Document of pages and blocks (headings, paragraphs, tables, images), which you can read as Markdown, text, HTML or JSON.

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Raw Document<br/>&#x22;] --> B[&#x22;Parsing<br/><small>fast or accurate</small>&#x22;]
  B --> C[&#x22;Clean Markdown<br/><small>Structure intact</small>&#x22;]
`"
/>

* **Headers are preserved** as logical hierarchy nodes (`#`, `##`, `###`).
* **Tables are formatted** into native Markdown tables.
* **Reading order** is reconstructed to ensure text flow matches human intent.

Every [Operation](https://docs.axelered.com/jobs_guide) parses its Document the same way, with the `parsing` field of its configuration.

***

## 🏗️ Configuration

| Parameter   | Type                | Default    | Description                                                                |
| :---------- | :------------------ | :--------- | :------------------------------------------------------------------------- |
| `tier`      | `string`            | `fast`     | The Parsing Tier: `fast` or `accurate`, see below.                         |
| `pages`     | `string` or `array` | all pages  | Pages to parse, as a list of indexes or a string like `"0,2-4"` (0-based). |
| `perimeter` | `string`            | `external` | Where your data may go. See [Perimeters](https://docs.axelered.com/config_guide).                   |

### Parsing Tiers

| Tier       | Description                                                                                                                                                                                               |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fast`     | Default. Extracts the text the file already contains. Best for digital files (DOCX, XLSX, HTML, text).                                                                                                    |
| `accurate` | Reads PDFs, images and presentations page by page with an OCR model: layout, scans and complex tables. Formats that are already text (Word, spreadsheets, HTML, CSV, JSON, text) are read as with `fast`. |

`accurate` runs on the OCR model of the [Perimeter](https://docs.axelered.com/config_guide); on PDFs, images and presentations it reads at most 100 pages and costs one Credit per page; `fast` costs one Credit per Document.

***

## 🛠️ Parse a Document

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

### [Submit a Parsing](https://docs.axelered.com/reference/parsings/api_create_parsings_post)

```bash
curl -X POST "https://api.axelered.com/v1/parsings?wait=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F 'config={"tier": "accurate", "pages": "0-4"}'
```

The response is the Parsing: `200` when it finished within `wait`, `202` while it is still running. See [Lifecycle](https://docs.axelered.com/jobs_guide#-lifecycle).

### [Read the Parsed Document](https://docs.axelered.com/reference/parsings/api_output_parsings__job_id__output_get)

Once the Parsing is `done`, read its Parsed Document as `markdown` (default), `text`, `html` or `json`:

```bash
curl "https://api.axelered.com/v1/parsings/{parsing_id}/output?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

| Parameter        | Default    | Description                                                   |
| :--------------- | :--------- | :------------------------------------------------------------ |
| `format`         | `markdown` | `markdown`, `text`, `html` or `json`.                         |
| `include_images` | `true`     | `false` replaces images with a placeholder.                   |
| `include_bbox`   | `true`     | `false` drops the bounding boxes of the blocks (`json` only). |

`format=json` returns the full structure, with the bounding box of each block. Before the Parsing finishes, the Output returns `425 output_not_ready`; a `failed` Parsing has no Output (`404`).

### List, Read & Delete

* [**List Parsings**](https://docs.axelered.com/reference/parsings/api_list_parsings_get): newest first, optionally for one Document with `?documentId=`.
* [**Read Parsing**](https://docs.axelered.com/reference/parsings/api_read_parsings__job_id__get): status and credits, with optional `wait`.
* [**Delete Parsing**](https://docs.axelered.com/reference/parsings/api_delete_parsings__job_id__delete): hide a Parsing. Its Document is kept.