Convert Markdown

Convert Mathpix Markdown documents to DOCX, XLSX, LaTeX, HTML, PDF, PPTX, and other formats.

Endpoint	Description
POST v3/converter	Submit an MMD document for conversion
GET v3/converter/{conversion_id}	Check conversion status
GET v3/converter/{conversion_id}.{ext}	Download converted output
DELETE v3/converter/{conversion_id}	Permanently delete conversion data

See the document conversion guide for step-by-step examples.

POST v3/converter

POST api.mathpix.com/v3/converter

Submit an MMD (Mathpix Markdown) document for conversion. Returns a conversion_id for polling status and downloading results. Maximum JSON body size: 10 MB.

Example

Request body

{
  "mmd": "_full mmd text_",
  "formats": { "docx": true, "tex.zip": true }
}

cURL

curl -X POST https://api.mathpix.com/v3/converter \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY' \
-H 'Content-Type: application/json' \
--data '{"mmd": "_full mmd text_", "formats": {"docx": true, "tex.zip": true}}'

Python

import requests
r = requests.post("https://api.mathpix.com/v3/converter",
    json={
        "mmd": "_full mmd text_",
        "formats": {"docx": True, "tex.zip": True}
    },
    headers={
        "app_id": "APP_ID",
        "app_key": "APP_KEY",
        "Content-type": "application/json"
    }
)
print(r.json())  # {"conversion_id": "..."}

JavaScript / TypeScript

const response = await fetch("https://api.mathpix.com/v3/converter", {
  method: "POST",
  headers: {
    app_id: "APP_ID",
    app_key: "APP_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mmd: "_full mmd text_",
    formats: { docx: true, "tex.zip": true },
  }),
});
const { conversion_id } = await response.json();
console.log(`Conversion ID: ${conversion_id}`);

Go

body := bytes.NewBufferString(`{
    "mmd": "_full mmd text_",
    "formats": {"docx": true, "tex.zip": true}
}`)
req, _ := http.NewRequest("POST", "https://api.mathpix.com/v3/converter", body)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result)) // {"conversion_id": "..."}

Java

HttpClient client = HttpClient.newHttpClient();
String body = """
    {
      "mmd": "_full mmd text_",
      "formats": { "docx": true, "tex.zip": true }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/converter"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Example response

{
  "conversion_id": "2024_01_15_abc123def456"
}

Request parameters

mmd string

MMD document that needs to be converted into other formats

formats ConversionFormats

Specifies output formats.

conversion_options ConversionOptions (optional)

Specifies options for specific output formats. Each key corresponds to a format enabled in formats, and the associated object contains format-specific settings.

metadata object (optional)

Key-value object. Supports improve_mathpix for extra privacy controls.

Response body

conversion_id string

Tracking ID for status and downloads

GET v3/converter/{conversion_id}

GET api.mathpix.com/v3/converter/{conversion_id}

Check conversion status. The top-level status is always completed since MMD is accepted synchronously. Individual format progress is tracked in conversion_status.

Example

cURL

curl https://api.mathpix.com/v3/converter/CONVERSION_ID \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY'

Python

import requests
r = requests.get("https://api.mathpix.com/v3/converter/CONVERSION_ID",
    headers={"app_id": "APP_ID", "app_key": "APP_KEY"}
)
print(r.json())  # {"status": "completed", "conversion_status": {...}}

JavaScript / TypeScript

const response = await fetch("https://api.mathpix.com/v3/converter/CONVERSION_ID", {
  headers: { app_id: "APP_ID", app_key: "APP_KEY" },
});
const status = await response.json();
console.log(status);

Go

req, _ := http.NewRequest("GET", "https://api.mathpix.com/v3/converter/CONVERSION_ID", nil)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result))

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/converter/CONVERSION_ID"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

status string

Always completed - the source MMD is accepted synchronously, so the top-level status is never a transient value. Individual format progress is tracked in conversion_status.

conversion_status ConversionStatus (object) (optional)

Status of each requested conversion format.

GET v3/converter/{conversion_id}.{ext}

GET api.mathpix.com/v3/converter/{conversion_id}.{ext}

Example

cURL

curl https://api.mathpix.com/v3/converter/CONVERSION_ID.docx \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY' \
-o output.docx

Python

import requests
r = requests.get("https://api.mathpix.com/v3/converter/CONVERSION_ID.docx",
    headers={"app_id": "APP_ID", "app_key": "APP_KEY"}
)
with open("output.docx", "wb") as f:
    f.write(r.content)

JavaScript / TypeScript

import { writeFile } from "fs/promises";
const response = await fetch("https://api.mathpix.com/v3/converter/CONVERSION_ID.docx", {
  headers: { app_id: "APP_ID", app_key: "APP_KEY" },
});
const buffer = await response.arrayBuffer();
await writeFile("output.docx", Buffer.from(buffer));

Go

req, _ := http.NewRequest("GET", "https://api.mathpix.com/v3/converter/CONVERSION_ID.docx", nil)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
out, _ := os.Create("output.docx")
defer out.Close()
io.Copy(out, resp.Body)

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/converter/CONVERSION_ID.docx"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .GET()
    .build();
HttpResponse<Path> response = client.send(request,
    HttpResponse.BodyHandlers.ofFile(Path.of("output.docx")));
System.out.println("Saved to " + response.body());

Download results once the format's conversion status is completed.

Accepted extensions: .mmd, .md, .docx, .tex.zip, .html, .pdf, .latex.pdf, .mmd.overlay.pdf, .pptx, .xlsx, .mmd.zip, .md.zip, .html.zip

See Conversion Formats for availability and descriptions.

DELETE v3/converter/{conversion_id}

Permanently delete a conversion's output data.

DELETE api.mathpix.com/v3/converter/{conversion_id}

Example

cURL

curl -X DELETE https://api.mathpix.com/v3/converter/CONVERSION_ID \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY'

Python

import requests
r = requests.delete("https://api.mathpix.com/v3/converter/CONVERSION_ID",
    headers={"app_id": "APP_ID", "app_key": "APP_KEY"}
)
print(r.json())

JavaScript / TypeScript

const response = await fetch("https://api.mathpix.com/v3/converter/CONVERSION_ID", {
  method: "DELETE",
  headers: { app_id: "APP_ID", app_key: "APP_KEY" },
});
console.log(response.status);

Go

req, _ := http.NewRequest("DELETE", "https://api.mathpix.com/v3/converter/CONVERSION_ID", nil)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result))

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/converter/CONVERSION_ID"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .DELETE()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

When a conversion is deleted:

• All output files are permanently removed from our servers (MMD, DOCX, LaTeX, HTML, PDF, and all requested formats)
• This deletion is permanent and cannot be undone

warning

Download and store files locally before deleting if you need to keep them.

Response body

Returns the conversion status object at the time of deletion.

status string

Conversion status at time of deletion (e.g. completed)

conversion_status ConversionStatus (object) (optional)

Status of each requested conversion format