# Document operations

Parse, sanitize, preview, or validate one document without choosing a
conversion pair. All routes require a bearer token and use `POST` with a JSON
body.

Every request requires `bucket_id` (a non-nil dashed UUID), active bucket
Management membership and the exact action capability. Select a bucket
through [Buckets and membership](https://m7.org/docs/api/api.document.m7.org/buckets.md). For organization-owned
buckets, retain the same [workspace selection](https://m7.org/docs/api/api.document.m7.org/workspaces.md) on submission
and every job request.

## Routes

| Route | Required fields | Optional fields | Success result |
| --- | --- | --- | --- |
| `/v1/document/parse` | `bucket_id`, `source`, `input_format` | `bbcode`, `bbcode_options` | Structured document data. |
| `/v1/document/sanitize` | `bucket_id`, `source`, `input_format` | `bbcode`, `bbcode_options` | Sanitized HTML. |
| `/v1/document/preview` | `bucket_id`, `source`, `input_format` | `bbcode`, `bbcode_options` | HTML preview. |
| `/v1/document/validate` | `bucket_id`, `source`, `input_format` | `output_format`, `bbcode`, `bbcode_options` | Validation state and issues. |

## Request fields

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `bucket_id` | Yes | UUID | Selected authorized bucket. |
| `source` | Yes | String | Non-empty document content. Leading and trailing whitespace is removed before processing. |
| `input_format` | Yes | String | Supported input format `name` or dashed UUID. |
| `output_format` | Only for a target validation | String | Format `name` or dashed UUID to validate. Omit it to validate preview processing. |
| `bbcode` | No | Object | BBCode parsing options. Takes precedence over `bbcode_options`. |
| `bbcode_options` | No | Object | BBCode parsing options if `bbcode` is absent. |
| `job_ttl` | No | Integer | Retention for the operation's job record in seconds. Defaults to `3600` and is constrained to `60` through `86400`. |
| `metadata` | No | Object | Caller metadata stored with the retained job record; it does not alter document processing. |
| `filename` | No | String | Source filename stored with the retained job record. |
| `locale` | No | String | Source locale stored with the retained job record. |
| `options` | No | Object | Additional data stored with the retained job record; current document handlers do not apply this object. |

An empty `source` fails with `source is required`. Unknown input and output
format references fail with `unsupported input_format` and
`unsupported output_format`.

## Response fields

`parse`, `sanitize`, and `preview` return `input_format`, `result`,
`result_format`, `warnings`, `issues`, and `metadata` in `data`.

- Parse results use `result_format: "json_structured"`. The `result` object
  contains `type`, `html`, `headings`, and `links`.
- Sanitization returns `result_format: "sanitized_html"` and the sanitized
  document in `result`.
- Preview returns `result_format: "html"` and the rendered document in
  `result`.
- Validation returns `input_format`, `output_format`, `valid`,
  `result_format`, `warnings`, `issues`, and `metadata`. An unsupported target
  among the known output formats is reported as `valid: false` with an issue
  whose code is `unsupported_output_format`. An unknown output reference fails
  the request with `unsupported output_format`.

## Preview a document

```bash
curl -sS https://api.document.service.m7.org/v1/document/preview \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "bucket_id": "BUCKET_UUID",
    "source": "# Preview title",
    "input_format": "markdown"
  }'
```

```json
{
  "status": 1,
  "comment": "PREVIEW",
  "data": {
    "input_format": "markdown",
    "result": "<h1>Preview title</h1>\n",
    "result_format": "html",
    "warnings": [],
    "issues": [],
    "metadata": {
      "input_length": 15,
      "result_format": "html"
    }
  }
}
```
