# Convert a document

Convert a document between an enabled input and output pair. Use
[`/v1/format/matrix`](https://m7.org/docs/api/api.document.m7.org/format.md) to select a supported pair first.

All conversion 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 | Success result |
| --- | --- | --- |
| `/v1/convert/sync` | `bucket_id`, `source`, `input_format`, `output_format` | Converted output in `data.result`. |
| `/v1/convert/async` | `bucket_id`, `source`, `input_format`, `output_format` | A `job_id` for the conversion job. |

## 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 | Enabled input format `name` or dashed UUID. |
| `output_format` | Yes | String | Enabled output format `name` or dashed UUID. The pair must be listed in the conversion matrix. |
| `profile` | No | String | Active format-profile `name` or dashed UUID recorded with the conversion job. |
| `job_ttl` | No | Integer | Retention in seconds. Defaults to `3600` and is constrained to `60` through `86400`. |
| `metadata` | No | Object | Caller metadata returned by the asynchronous creation response and stored with the job. |
| `filename` | No | String | Source filename; an empty value is treated as absent. |
| `locale` | No | String | Source locale; an empty value is treated as absent. |
| `options` | No | Object | Conversion-specific option payload. |
| `bbcode` | No | Object | BBCode parsing options when `input_format` is `bbcode`. Takes precedence over `bbcode_options`. |
| `bbcode_options` | No | Object | BBCode parsing options when `bbcode` is not supplied. |

Invalid format or profile references fail with `unsupported input_format`,
`unsupported output_format`, or `unsupported profile`. An empty `source` fails
with `source is required`.

## Convert synchronously

Use this route when the converted document is needed in the same request.

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

```json
{
  "status": 1,
  "comment": "CONVERT_SYNC",
  "data": {
    "input_format": "markdown",
    "output_format": "html",
    "result": "<h1>Example document</h1>\n",
    "result_format": "html",
    "warnings": [],
    "issues": [],
    "duration_ms": 5,
    "metadata": {
      "engine": "commonmark",
      "result_format": "html"
    }
  }
}
```

## Create a conversion job

Use this route when the caller will retrieve the output from the job API. Save
the returned `job_id`, then use [`/v1/job/result`](https://m7.org/docs/api/api.document.m7.org/jobs.md) until the job is
completed.

```bash
curl -sS https://api.document.service.m7.org/v1/convert/async \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "bucket_id": "BUCKET_UUID",
    "source": "# Example document",
    "input_format": "markdown",
    "output_format": "html",
    "metadata": {
      "request_reference": "example-conversion"
    }
  }'
```

```json
{
  "status": 1,
  "comment": "CONVERT_ASYNC",
  "data": {
    "job_id": "JOB_UUID",
    "mode": "async",
    "status": "pending",
    "input_format": "markdown",
    "output_format": "html",
    "expires_at": "2030-01-01 12:00:00",
    "metadata": {
      "request_reference": "example-conversion"
    }
  }
}
```

Treat the creation response as an acknowledgement. The job endpoint is the
source of truth for its current status and result.
