## Queue text extraction of a document (tenant:dms:write)

`POST /api/dms/v1/documents/{id}/extract`

Module: DMS · operationId: `requestDocumentExtraction` · Tag: Text · Auth: access token (`Authorization: Bearer <accessToken>`)

Queues the current version for extraction. Without `force` a queued, running or finished
(`DONE`, `PARTIAL`) extraction is left alone and its status returned; `force: true` discards
the stored text and extracts again. The body is optional. Encrypted documents are never
extracted (`400`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Request body

`application/json`

- `force` (boolean): Discard the stored text and extract again (default `false`)

Example:

```json
{
  "force": true
}
```

### Responses

- **202** Queued (or already queued, running or finished) (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 202 answer:

- `documentId` (string (uuid), required): Document id
- `status` (ExtractionStatus, required): (one of `NONE`, `PENDING`, `PROCESSING`, `DONE`, `PARTIAL`, `SKIPPED`, `FAILED`)

Example 202 answer:

```json
{
  "documentId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
  "status": "PENDING"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/dms/v1/documents/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/extract' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"force":true}'
```
