Convert a document

Convert a document between an enabled input and output pair. Use /v1/format/matrix to select a supported pair first.

All conversion routes require a bearer token and use POST with a JSON body.

Routes

Route	Required fields	Success result
/v1/convert/sync	source, input_format, output_format	Converted output in data.result.
/v1/convert/async	source, input_format, output_format	A job_id for the conversion job.

Request fields

Field	Required	Type	Description
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.

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

{
  "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 until the job is completed.

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

{
  "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.