API Reference

curl -X POST https://api.formatex.io/api/v1/compile \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"latex": "\\documentclass{article}\\begin{document}Hello!\\end{document}"}' \
  --output document.pdf

{
  "error": "human-readable error message",
  "plan": "free",
  "limit": 100,
  "used": 100
}

{
  "total": 3,
  "success": 2,
  "failed": 1,
  "results": [
    { "index": 0, "filename": "report-Martin-1.pdf", "success": true },
    { "index": 1, "filename": "report-Chen-2.pdf",   "success": true },
    { "index": 2, "filename": "report-López-3.pdf",  "success": false, "error": "Undefined control sequence \\badmacro" }
  ]
}

&  →  \&                   %  →  \%
$  →  \$                   #  →  \#
_  →  \_                   {  →  \{
}  →  \}                   ~  →  \textasciitilde{}
^  →  \textasciicircum{}   \  →  \textbackslash{}

curl -X POST https://api.formatex.io/api/v1/templates/cover-letter/compile \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"variables": {"name": "Alice Martin", "company": "Acme Corp"}}' \
  --output cover-letter.pdf

{
  "event": "compilation.success",
  "data": {
    "compilationId": "uuid",
    "engine": "pdflatex",
    "durationMs": 1240,
    "inputSizeBytes": 2048,
    "apiKeyPrefix": "a2e67d28...",
    "timestamp": "2026-02-20T14:30:00Z"
  }
}

formatex compile thesis.tex

formatex login

- name: Compile LaTeX
  run: formatex compile thesis.tex --output dist/thesis.pdf
  env:
    FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}

pip install formatex

from formatex import FormaTexClient

client = FormaTexClient(api_key="fex_your_key_here")

result = client.compile(r"""
\documentclass{article}
\begin{document}
Hello, FormaTeX!
\end{document}
""")

with open("output.pdf", "wb") as f:
    f.write(result.pdf)

FormaTexClient(
    api_key: str,         # required — get yours at formatex.io/dashboard/api-keys
    *,
    timeout: float = 120.0,
)

with FormaTexClient(api_key="fex_...") as client:
    result = client.compile(latex)

result = client.compile(
    latex: str,
    *,
    engine: str = "pdflatex",   # pdflatex | xelatex | lualatex | latexmk
    runs: int = 0,               # 0 = auto (1–5, capped to plan)
    timeout: int = 0,            # 0 = plan default
    files: list[dict] | None = None,  # companion files (images, .bib, etc.)
)
# → CompileResult(pdf: bytes, engine: str, duration_ms: int, size_bytes: int, job_id: str, log: str)

from formatex import FormaTexClient, file_entry
from pathlib import Path

result = client.compile(latex, files=[
    file_entry("logo.png", Path("assets/logo.png").read_bytes()),
    file_entry("refs.bib", Path("refs.bib").read_bytes()),
])

result = client.compile_smart(latex, engine="auto")

zip_bytes = Path("project.zip").read_bytes()
result = client.compile_zip(
    zip_bytes,
    main="chapters/main.tex",  # optional — auto-detected if omitted
    engine="xelatex",
)

nb_bytes = Path("notebook.ipynb").read_bytes()
result = client.compile_ipynb(nb_bytes, engine="pdflatex")

# Compile from Markdown
result = client.compile_markdown(markdown_str)

# Compile from HTML
result = client.compile_html(html_str)

# Compile from reStructuredText
result = client.compile_rst(rst_str)

# Submit
job = client.async_compile(latex, engine="lualatex")
print(job.job_id, job.status)  # pending

# Poll manually
result_info = client.get_job(job.job_id)

# Or wait with exponential back-off (recommended)
result = client.wait_for_job(job.job_id, poll_interval=2, max_wait=300)
pdf_bytes = result.pdf

# Render a LaTeX equation to PNG/SVG
img = client.render_equation(
    r"E = mc^2",
    format="png",   # png | svg
    dpi=150,
    display=True,   # display mode (vs inline)
)
with open("eq.png", "wb") as f:
    f.write(img.image)

# Batch render multiple equations
results = client.render_equations([
    {"latex": r"E = mc^2", "format": "png"},
    {"latex": r"\int_0^\infty e^{-x}\,dx", "format": "svg"},
])

result = client.convert(
    latex,
    format="docx",  # docx | html | odt | epub | markdown | txt
)
with open("thesis.docx", "wb") as f:
    f.write(result.file)

lint = client.lint(latex)
print(lint.error_count, lint.warning_count)
for d in lint.diagnostics:
    print(f"{d.line}:{d.column} [{d.severity}] {d.message}")

# Extract text from page 0
extracted = client.pdf_extract(pdf_bytes, page=0)
print(extracted.text)

# Render pages as images
pages = client.pdf_pages(pdf_bytes, dpi=150)

# Compress
compressed = client.pdf_compress(pdf_bytes)

# Merge
merged = client.pdf_merge([pdf_a, pdf_b, pdf_c])

# Split into individual pages
split = client.pdf_split(pdf_bytes)

# Convert to PDF/A
pdfa = client.pdf_pdfa(pdf_bytes)

# Word count
wc = client.word_count(latex)

# Extract \usepackage dependencies
deps = client.extract_dependencies(latex)

# Check which packages are available on the server
status = client.check_packages(["tikz", "pgfplots", "fontawesome5"])

# Extract title, author, date, etc.
meta = client.extract_metadata(latex)

# Analyse a .bib file
bib = client.analyse_bibliography(bib_str)

from formatex.exceptions import FormaTexError, CompilationError, RateLimitError

try:
    result = client.compile(latex)
except CompilationError as e:
    print("LaTeX errors:", e.log)
except RateLimitError:
    print("Rate limit hit — back off and retry")
except FormaTexError as e:
    print("API error:", e)

npm install formatex-sdk
# or
pnpm add formatex-sdk

import { FormaTexClient } from "formatex-sdk";

const client = new FormaTexClient("fex_your_key_here");

const result = await client.compile(`
  \\documentclass{article}
  \\begin{document}
  Hello, FormaTeX!
  \\end{document}
`);

await fs.writeFile("output.pdf", result.pdf);

const client = new FormaTexClient(
  apiKey: string,                  // required
  options?: FormaTexClientOptions, // { baseUrl?, timeout? }
);

const result = await client.compile(latex: string, options?: CompileOptions);
// CompileOptions: { engine?, runs?, timeout?, files? }
// Returns: CompileResult { pdf: Buffer, engine, durationMs, sizeBytes, jobId, log }

import { FormaTexClient, fileEntry } from "formatex-sdk";
import { readFileSync } from "fs";

const result = await client.compile(latex, {
  engine: "xelatex",
  files: [
    fileEntry("logo.png", readFileSync("assets/logo.png")),
    fileEntry("refs.bib", readFileSync("refs.bib")),
  ],
});

const result = await client.compileSmart(latex, { engine: "auto" });

const zip = readFileSync("project.zip");
const result = await client.compileZip(zip, {
  main: "chapters/main.tex", // optional
  engine: "xelatex",
});

const nb = readFileSync("notebook.ipynb");
const result = await client.compileIpynb(nb);

// Compile from Markdown
const result = await client.compileMarkdown(markdownStr);

// Compile from HTML
const result = await client.compileHtml(htmlStr);

// Compile from reStructuredText
const result = await client.compileRst(rstStr);

// Submit
const job = await client.asyncCompile(latex, { engine: "lualatex" });
console.log(job.jobId, job.status); // pending

// Wait with exponential back-off (recommended)
const result = await client.waitForJob(job.jobId, { maxWait: 300_000 });
await fs.writeFile("output.pdf", result.pdf);

// Or poll manually
const status = await client.getJob(job.jobId);
const pdf = await client.getJobPdf(job.jobId);

// Render a LaTeX equation
const img = await client.renderEquation(r`E = mc^2`, {
  format: "png",     // "png" | "svg"
  dpi: 150,
  display: true,
});
await fs.writeFile("eq.png", img.image);

// Batch render
const results = await client.renderEquations([
  { latex: r`E = mc^2`, format: "png" },
  { latex: r`\int_0^\infty e^{-x}\,dx`, format: "svg" },
]);

const result = await client.convert(latex, { format: "docx" });
// format: "docx" | "html" | "odt" | "epub" | "markdown" | "txt"
await fs.writeFile("thesis.docx", result.file);

const lint = await client.lint(latex);
console.log(lint.errorCount, lint.warningCount);
for (const d of lint.diagnostics) {
  console.log(`${d.line}:${d.column} [${d.severity}] ${d.message}`);
}

// Extract text from a page
const extracted = await client.pdfExtract(pdfBuffer, 0);
console.log(extracted.text);

// Render pages as images
const pages = await client.pdfPages(pdfBuffer, { dpi: 150 });

// Compress
const compressed = await client.pdfCompress(pdfBuffer);

// Merge
const merged = await client.pdfMerge([pdfA, pdfB, pdfC]);

// Split into individual pages
const split = await client.pdfSplit(pdfBuffer);

// Convert to PDF/A
const pdfa = await client.pdfPDFA(pdfBuffer);

// Word count
const wc = await client.wordCount(latex);

// Extract \usepackage dependencies
const deps = await client.extractDependencies(latex);

// Check which packages are available
const status = await client.checkPackages(["tikz", "pgfplots", "fontawesome5"]);

// Extract title, author, date, etc.
const meta = await client.extractMetadata(latex);

// Analyse a .bib file
const bib = await client.analyzeBibliography(bibStr);

import {
  FormaTexError,
  CompilationError,
  RateLimitError,
  AuthenticationError,
} from "formatex-sdk";

try {
  const result = await client.compile(latex);
} catch (e) {
  if (e instanceof CompilationError) {
    console.error("LaTeX errors:", e.log);
  } else if (e instanceof RateLimitError) {
    console.error("Rate limited — back off and retry");
  } else if (e instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (e instanceof FormaTexError) {
    console.error("API error:", e.message);
  }
}

name: Compile LaTeX

on:
  push:
    branches: [main]
  pull_request:

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: formatexio/action@v1
        with:
          file: thesis.tex
          engine: pdflatex        # optional — default: pdflatex
          output: dist/thesis.pdf # optional — default: <file>.pdf
        env:
          FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}

      - uses: actions/upload-artifact@v4
        with:
          name: thesis-pdf
          path: dist/thesis.pdf

name: Compile LaTeX

on:
  push:
    branches: [main]

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install FormaTeX CLI
        run: curl -fsSL https://raw.githubusercontent.com/formatexio/cli/main/install.sh | sh

      - name: Compile
        run: formatex compile thesis.tex --output dist/thesis.pdf
        env:
          FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}

      - uses: actions/upload-artifact@v4
        with:
          name: thesis-pdf
          path: dist/thesis.pdf

- name: Archive project
  run: zip -r project.zip . -x "*.git*"

- name: Compile
  run: formatex compile project.zip --main chapters/main.tex --output dist/thesis.pdf
  env:
    FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}

- name: Compile
  id: compile
  run: formatex compile thesis.tex --output dist/thesis.pdf
  env:
    FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}

- uses: actions/upload-artifact@v4
  id: upload
  with:
    name: thesis-pdf
    path: dist/thesis.pdf

- name: Comment on PR
  if: github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `PDF compiled successfully. [Download artifact](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`,
      })

strategy:
  matrix:
    engine: [pdflatex, xelatex, lualatex]

steps:
  - uses: actions/checkout@v4
  - name: Compile with ${{ matrix.engine }}
    run: formatex compile thesis.tex --engine ${{ matrix.engine }} --output dist/thesis-${{ matrix.engine }}.pdf
    env:
      FORMATEX_API_KEY: ${{ secrets.FORMATEX_API_KEY }}