XGenerate — Document Assembly

Guide · REST API

Convert Markdown to DOCX with one API call

Your system writes Markdown: release notes, reports, text from a model. Send it to the API and get a Word document back whose headings, lists, tables and emphasis are real Word formatting. Add your letterhead template and the text lands at its body placeholder, with the other merge fields filled from JSON.

Request a demo Open the API contract

Why not convert Markdown yourself

  • A converter in your process produces a bare document; the letterhead, fonts and styles your company expects are not in the text.
  • Command-line converters are one more binary to install and keep patched on every server that writes documents.
  • Generated text, from a model or a workflow, has to become a document people can still edit and sign off.

The request

Multipart transport: the Markdown is the markdown part, the format a plain form value; format=DOCX returns the Word file, PDF the rendered pages. An optional file part carries a Word template whose MERGEFIELD body placeholder receives the text, and a fields part fills the template's other merge fields. Without a template, only letterheads from the fields envelope apply.

TOKEN=$(curl -sS https://auth.xgenerate.io/realms/xgenerate/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$XGENERATE_CLIENT_ID" \
  -d client_secret="$XGENERATE_CLIENT_SECRET" | jq -r .access_token)

# 1. Plain Markdown: the text is the document.
curl -sS https://api.xgenerate.io/v2/documents/generate-from-markdown \
  -H "Authorization: Bearer $TOKEN" \
  -F "markdown=@release-notes.md;type=text/markdown" \
  -F "format=DOCX" \
  -o release-notes.docx

# 2. Onto a letterhead: the template's MERGEFIELD body receives the text,
#    its other merge fields are filled from the fields part.
cat > fields.json <<'JSON'
{ "fields": [ { "name": "document.date", "value": "25.10.2026" } ] }
JSON

curl -sS https://api.xgenerate.io/v2/documents/generate-from-markdown \
  -H "Authorization: Bearer $TOKEN" \
  -F "markdown=@release-notes.md;type=text/markdown" \
  -F "file=@letterhead.docx" \
  -F "fields=@fields.json;type=application/json" \
  -F "format=DOCX" \
  -o release-notes.docx

From .NET 

using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", token);

// JSON transport: the Markdown travels as text, the optional letterhead template base64-encoded.
var request = new
{
    filename = "release-notes.md",
    markdown = await File.ReadAllTextAsync("release-notes.md"),
    template = Convert.ToBase64String(await File.ReadAllBytesAsync("letterhead.docx")),
    fields = new
    {
        fields = new[] { new { name = "document.date", value = "25.10.2026" } }
    },
    format = "DOCX"
};
var response = await http.PostAsJsonAsync(
    "https://api.xgenerate.io/v2/documents/generate-from-markdown", request);
response.EnsureSuccessStatusCode();

// result.Filename is "release-notes.docx": the extension follows the requested format.
var result = await response.Content.ReadFromJsonAsync<GenerateResult>();
await File.WriteAllBytesAsync(result!.Filename, Convert.FromBase64String(result.Content));

record GenerateResult(string Filename, string Content, string Format);

The response

The multipart call streams the DOCX back with Content-Type application/vnd.openxmlformats-officedocument.wordprocessingml.document. The JSON transport returns filename, content, format and warnings, with the file base64-encoded in content. With a template, warnings name image, QR and letterhead slots without a value; merge fields and regions without data are removed without a warning. The request succeeds either way.

What XGenerate does not do

Markdown covers the GFM basics: headings, lists, emphasis, links, code, blockquotes and pipe tables. Image syntax is reduced to its alt text and nothing is fetched from the network. The text renders through the Word engine, so complex CSS layouts and JavaScript are not interpreted; for a layout that must match an existing document, the Word template is the path.

Try it on your own template

Send us a Word file you use today. We render it with your data and return the PDF together with the adapted template, so your evaluation does not have to wait on us.

Request a demo

Related guides