DocMint API reference

Quickstart#

Four calls: get a key, upload a template, ask what it needs, render it. The whole thing takes about a minute and costs one credit.

1. Get a key

curl -X POST https://docmint-832s.onrender.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-long-enough-password"}'

{
  "email": "you@example.com",
  "api_key": "dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "plan": { "id": "free", "name": "Free", "credits": 30 },
  "note": "This is the only time the key is shown. Store it now."
}

2. Author a template

Open Word and type a document with placeholders in it. This one has two:

Quote for {{customer}}
Total due: {{total|currency:EUR}}

Save it as quote.docx. Nothing else about the file changes — it still opens in Word, and whoever owns the letterhead can keep editing it.

3. Upload it

curl -X POST https://docmint-832s.onrender.com/v1/templates \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"quote\",\"file_base64\":\"$(base64 -w0 quote.docx)\"}"

{
  "request_id": "dm_4wtUEH44inC4",
  "id": "tpl_6P2RxBHdMziH",
  "name": "quote",
  "format": "docx",
  "version": 1,
  "unchanged": false,
  "size": 1001,
  "fields": [
    { "name": "customer", "scope": "", "type": "string", "repeating": false,
      "required": true, "formatters": [], "used": 1,
      "locations": ["word/document.xml, paragraph 1"] },
    { "name": "total", "scope": "", "type": "number", "repeating": false,
      "required": true, "formatters": ["currency"], "used": 1,
      "locations": ["word/document.xml, paragraph 2"] }
  ],
  "macro_enabled": false
}

4. Ask what it needs, then render it

curl -H "Authorization: Bearer dm_live_xxx" \
  https://docmint-832s.onrender.com/v1/templates/quote/fields

{
  "id": "tpl_6P2RxBHdMziH",
  "name": "quote",
  "format": "docx",
  "version": 1,
  "fields": [
    { "name": "customer", "scope": "", "type": "string", "repeating": false,
      "required": true, "formatters": [], "used": 1,
      "locations": ["word/document.xml, paragraph 1"] },
    { "name": "total", "scope": "", "type": "number", "repeating": false,
      "required": true, "formatters": ["currency"], "used": 1,
      "locations": ["word/document.xml, paragraph 2"] }
  ],
  "names": ["customer", "total"],
  "tags": [
    { "expr": "customer", "kind": "value",
      "location": "word/document.xml, paragraph 1" },
    { "expr": "total|currency:EUR", "kind": "value",
      "location": "word/document.xml, paragraph 2" }
  ],
  "sample_data": { "customer": "customer", "total": 0 }
}

curl -X POST https://docmint-832s.onrender.com/v1/render \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"template":"quote","data":{"customer":"Acme GmbH","total":1240.5},"output":"pdf"}' \
  --output quote.pdf

HTTP/2 200
content-type: application/pdf
content-length: 13660
content-disposition: attachment; filename="document.pdf"
x-docmint-request-id: dm_o9shbTxzJCqW
x-docmint-credits-remaining: 28
x-docmint-warnings: 0
x-ratelimit-limit: 120
x-ratelimit-burst: 30
x-ratelimit-remaining: 29

Leave output off and you get the filled .docx instead, for one credit rather than two.

POST/v1/signup#

Self-serve signup over the API, deliberately rather than only through a web form. The buyer here is someone wiring up a workflow; making them leave the terminal before they can see whether the thing works is friction with no purpose.

The response contains the account's first API key. It is shown once and cannot be read back — not by support, not by the operator, because only a SHA-256 hash of it is stored.

Errors

Authentication#

Every endpoint except POST /v1/signup, GET /v1/capabilities and GET /healthz needs a key.

Authorization: Bearer dm_live_xxx

X-API-Key: dm_live_xxx is accepted too, for clients that cannot set an Authorization header. Keys always start with dm_live_; a key that does not is rejected without a database lookup.

More keys#

One key per environment is a good habit: a leaked key from a staging workflow can then be revoked without stopping production.

curl -X POST https://docmint-832s.onrender.com/v1/keys \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci"}'

{ "key": "dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "note": "This is the only time the key is shown. Store it now." }

Revoke one by its first 16 characters — the prefix, which is the only part of a key that is stored in the clear:

curl -X DELETE https://docmint-832s.onrender.com/v1/keys/dm_live_X67fKwVY \
  -H "Authorization: Bearer dm_live_xxx"

{ "revoked": 1 }

Revoking the account's only key is refused, because a key you cannot replace without one is a lockout:

{
  "error": {
    "code": "last_key",
    "message": "This is the only key on the account, so revoking it would lock you out.",
    "hint": "Create a replacement key first, then revoke this one.",
    "docs": "https://docmint-832s.onrender.com/docs#auth-more-keys",
    "request_id": "dm_ZNH9iIxUU9yx"
  }
}

Template syntax#

The same syntax works in all three formats. Both brace styles are accepted, always: {name} is the docxtemplater and Carbone style, {{name}} is the mustache and n8n style. Supporting both costs one branch in the scanner and removes the most common first-five-minutes failure, which is typing the other one. No third syntax was invented.

Every tag form

Scopes

Inside a section the outer scopes stay visible, so {currency} from the invoice root resolves inside {#items} without writing {../currency}. That is a convenience with a sharp edge, and DocMint tells you about it every time — see Warnings.

Where a loop repeats

What "repeat" means depends on where the two markers sit, and this is what makes an invoice line-item table work:

Formatters#

43 of them, applied left to right with |. There is no expression evaluator: formatters are a fixed, audited list, so no string you send is ever compiled or executed. The canonical list is served by GET /v1/capabilities, read straight out of the module — a formatter cannot be documented into existence.

Text

Numbers that produce text

These format for the request's locale and return a string. In a spreadsheet that means a text cell — see the note below.

Numbers that produce numbers

These return a real number. That distinction is load-bearing in a spreadsheet: a numeric result becomes a numeric cell and SUM() over the column works, whereas text lands as text and SUM() silently returns zero. Arithmetic is done in cents-safe form, so 0.1 + 0.2 never appears on an invoice.

List shaping, for sections

These take a list and give back a list, so they belong on a section tag: {#items|filter:active|sort:due_date}. The alternative is telling you to sort and filter the array in your workflow before it arrives — which is fine until the same array has to be rendered twice in one document in two different orders.

Conditions, for sections

These return true or false, which makes them section tests rather than value formatters: a section over true renders once, and a section over false renders not at all. Pair one with {^…} for the else branch.

Dates, as conditions and as counts

All six read the value as a date, exactly as date does, and compare it against now in the request's time zone.

Formatter errors

Images#

{%logo} places a picture, in Word, Excel and PowerPoint. The value it resolves to may be:

Formats: PNG, JPEG, GIF and BMP in Word and Excel; PNG, JPEG and GIF in PowerPoint, which are the formats PowerPoint embeds without conversion. An image may be at most 24 MB.

{
  "template": "deck",
  "data": { "title": "Q3 review", "logo": { "url": "https://example.com/logo.png" } },
  "images": { "https://example.com/logo.png": { "data": "iVBORw0KGgo…" } }
}

The missing-field contract#

This is the behaviour the product is judged on. A rendered document must never contain the text undefined, an unresolved {{tag}}, or a silently blank cell where a number was meant to be.

onMissing

A per-request escape hatch. It is off by default because the failure it prevents is silent and expensive.

What a 422 looks like

Verbatim from the live API. A Word template with {#items}{description}, {qty}, {price|currency}{/items} across one table row, rendered with items that have no price:

{
  "error": {
    "code": "placeholder_unresolved",
    "message": "The template uses {price|currency} but the data has no \"price\".",
    "hint": "Add \"price\" to the data, or write {price|default:} to allow it to be absent.",
    "docs": "https://docmint-832s.onrender.com/docs#errors",
    "details": {
      "field": "price",
      "location": "word/document.xml, table 1 row 2, paragraph 7",
      "available": ["invoice_no", "customer", "items", "description", "qty"],
      "format": "docx"
    },
    "request_id": "dm_IHD7M11U8enL"
  }
}

When the name is close to one that exists, the hint says so. The same template rendered with custmer instead of customer:

{
  "error": {
    "code": "placeholder_unresolved",
    "message": "The template uses {customer} but the data has no \"customer\".",
    "hint": "Did you mean \"custmer\"? Otherwise add \"customer\" to the data, or write
             {customer|default:} to allow it to be absent.",
    "details": {
      "field": "customer",
      "location": "word/document.xml, paragraph 1",
      "available": ["custmer", "total"],
      "format": "docx"
    }
  }
}

The location string

It is written for a human holding the file open, not for a parser. All three of these are real strings taken from the live API:

The related codes

Warnings#

A warning does not stop the render. It comes back in the JSON response under warnings, and the count is always in the X-DocMint-Warnings response header — including when the response body is the file's bytes rather than JSON.

resolved_from_outer_scope

Scopes nest outwards, so inside {#rows} a tag can reach the document root. That is usually what was wanted — {currency} from the invoice root — and occasionally a serious bug: if the rows have product_name and the template says {name}, and name exists at the root, every row prints the same value and nothing errors. DocMint cannot tell which case it is from the data alone, so it records every occurrence rather than guessing silently in either direction.

"warnings": [
  {
    "code": "resolved_from_outer_scope",
    "field": "currency",
    "location": "word/document.xml, table 1 row 2, paragraph 5",
    "message": "{currency} is not a field of the loop item; it was taken from 1 level
                further out, so it prints the same value on every row.",
    "item_fields": ["title", "amount"]
  }
]

strictScope

Send "strictScope": true and the same situation becomes a 422 instead. Use it once on a new template to prove every loop tag really belongs to its item, then turn it off — or leave it on and write {../currency} where you meant the outer value.

{
  "error": {
    "code": "placeholder_outside_loop",
    "message": "{currency} is not a field of the loop item.",
    "hint": "strictScope is on, so a tag inside a loop must name a field of the item.
             Write {../currency} if you meant the value from outside the loop.",
    "details": {
      "field": "currency",
      "location": "word/document.xml, table 1 row 2, paragraph 5",
      "available": ["title", "amount"],
      "format": "docx"
    },
    "request_id": "dm_UfljbGSKSbI0"
  }
}

macros_not_preserved

A macro-enabled template (.docm, .xlsm, .pptm) is filled correctly, but the macros are not guaranteed to survive the rewrite and the file is returned with the plain, non-macro content type. The warning says so on every such render.

POST/v1/render#

The main endpoint. Send a template and some data; get the filled file back.

{
  "error": {
    "code": "unknown_field",
    "message": "There is no field called \"convertTo\" - did you mean \"output\"?",
    "hint": "Rename \"convertTo\" to \"output\".",
    "details": {
      "sent": "convertTo",
      "meant": "output",
      "accepted": ["template","template_base64","template_version","data","output",
                   "filename","locale","currency","timezone","onMissing",
                   "strictScope","response","images"]
    },
    "docs": "https://docmint-832s.onrender.com/docs#render"
  }
}

Response headers

The filename

The filename may contain placeholders, so a workflow can produce a per-document name without a separate expression node. It is resolved against the same data, with missing fields treated as empty — a filename is cosmetic and failing the whole render over it would be absurd — and characters that would make the name unusable as a download, including path separators, are stripped. The extension is forced to match what is actually being returned.

curl -X POST https://docmint-832s.onrender.com/v1/render \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"template":"quote","filename":"quote_{customer}.docx",
       "data":{"customer":"Acme","total":1240.5}}' \
  -D - -o quote.docx

Sending the template#

Exactly one of template and template_base64. Sending both is refused rather than silently preferring one, because that is how a workflow ends up rendering last month's letterhead.

Base64 with or without a data: prefix is accepted, and whitespace and the URL-safe alphabet are tolerated. From a shell, base64 -w0 invoice.docx.

The data object#

A JSON object. Not an array, and not a scalar — if you want to loop over a list, put it under a key and loop with {#items}:

{
  "error": {
    "code": "bad_data",
    "message": "\"data\" must be a JSON object, not an array.",
    "hint": "If you want to loop over a list, put it under a key: {\"items\": [...]},
             and loop with {#items} in the template.",
    "docs": "https://docmint-832s.onrender.com/docs#data"
  }
}

At most 8 MB, measured as the serialised JSON; over that is 413 data_too_large. Large payloads are almost always base64 images, and an image can be sent through the images object instead.

Output modes#

Chosen per request, not fixed per template in a dashboard. The same stored template can produce a .docx for one workflow and a PDF for another.

Add "response": "json" (or an Accept: application/json header) to get the JSON envelope for any mode. It is the only way to see stats and warnings, so it is worth using while building a template.

{
  "request_id": "dm_xteafxWKjXav",
  "format": "xlsx",
  "document": {
    "filename": "document.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size": 6650,
    "base64": "UEsDBBQ…"
  },
  "pdf": {
    "filename": "document.pdf",
    "content_type": "application/pdf",
    "size": 31686,
    "pages": 2,
    "base64": "JVBERi0…"
  },
  "stats": {
    "tags": 14, "resolved": 14, "sections": 2, "images": 0,
    "parts": ["xl/workbook.xml", "xl/worksheets/sheet1.xml", "xl/worksheets/sheet2.xml"],
    "ms": 2708.5,
    "stages": { "load": 0.3, "quota": 3.2, "fill": 7.2, "pdf": 2694.2 }
  },
  "warnings": [],
  "credits": { "used": 2, "remaining": 18, "limit": 30 }
}

stats.stages is where the time actually went, in milliseconds: load is fetching the template, quota the credit reservation, fill the document surgery, pdf the LibreOffice conversion.

PDF output#

PDFs are produced by headless LibreOffice, run as a separate process on the same instance. Word documents go through the Writer filter, workbooks through Calc, decks through Impress.

Not supported: PDF/A, watermarking, PDF encryption, page-range selection, and any choice of converter. There is one converter and one profile.

Localisation#

Three per-request settings feed every formatter that has a locale-dependent result: number, currency, percent, date, and the collator that sort uses on strings.

ordinal is the one formatter that is not localised: it produces English suffixes whatever the locale says.

POST/v1/inspect#

"What fields does this template need?" — for a file you have not stored. It reads a template the caller already has and produces no document, so it costs no credits; charging for the one call that prevents a bad render would only discourage it. It never throws on a field you have not supplied, because it never looks at data.

Takes template, template_base64 or template_version, exactly as render does.

curl -X POST https://docmint-832s.onrender.com/v1/inspect \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d "{\"template_base64\":\"$(base64 -w0 report.pptx)\"}"

{
  "request_id": "dm_UHkGNxmKNkIY",
  "format": "pptx",
  "fields": [
    { "name": "client.name", "scope": "", "type": "string", "repeating": false,
      "required": true, "formatters": [], "used": 4,
      "locations": ["slide 1, shape \"Subtitle 2\"", "slide 2, shape \"Heading 4\""] },
    { "name": "logo", "scope": "", "type": "image", "repeating": false,
      "required": true, "formatters": [], "used": 2,
      "locations": ["slide 1, shape \"Logo 3\""] },
    { "name": "rows", "scope": "", "type": "array", "repeating": true,
      "required": true, "formatters": ["count", "sum", "currency"], "used": 6,
      "locations": ["slide 2, table \"Items 5\", row 1, cell 3",
                    "slide 2, table \"Items 5\", row 3, cell 2",
                    "slide 2, table \"Items 5\", row 3, cell 3"] },
    { "name": "amount", "scope": "rows", "type": "number", "repeating": false,
      "required": true, "formatters": ["currency"], "used": 1,
      "locations": ["slide 2, table \"Items 5\", row 2, cell 3"] }
  ],
  "names": ["title", "subtitle", "client.name", "logo", "notes", "rows",
            "sku", "qty", "amount", "findings", "label", "detail", "owner"],
  "tags": [
    { "expr": "logo", "kind": "image",
      "location": "slide 1, shape \"Logo 3\"" },
    { "expr": "notes", "kind": "value",
      "location": "slide 1 notes, shape \"Notes 1\"" },
    { "expr": "rows", "kind": "section",
      "location": "slide 2, table \"Items 5\", row 2, cell 1" },
    { "expr": "rows|sum:amount|currency:EUR", "kind": "value",
      "location": "slide 2, table \"Items 5\", row 3, cell 3" },
    { "expr": "findings", "kind": "inverted",
      "location": "slide 3, shape \"Body 6\"" }
  ],
  "sample_data": {
    "title": "title", "subtitle": "subtitle", "client": { "name": "name" },
    "logo": null, "notes": "notes",
    "rows":     [{ "sku": "sku", "qty": "qty", "amount": 0 }],
    "findings": [{ "label": "label", "detail": "detail", "owner": "owner" }]
  },
  "template": null
}

How it knows the nesting

Not by parsing the tags a second time. The template is run through the real renderer, with no data and a probe attached to the template context, which records every lookup and the depth of the scope stack it happened at. A section with no data iterates zero times, so the first pass sees only the root; one empty object is then fed into every section that was found and the pass runs again, until nothing new appears. Five passes covers five levels of nesting.

The point of doing it that way is that the answer is, by construction, exactly what a render would ask for: the same scope rules, the same section semantics, the same handling of each format's awkward cases. A second implementation would drift from the first, and the drift would land on you.

The response

Inside one field

Template management#

Templates are addressed by a name you choose, not by an opaque id. A workflow that says template: "invoice" keeps working when the finance team uploads a new letterhead. The tpl_… id exists too and works anywhere a name does.

Names are lower case letters, digits, dot, dash and underscore, 1 to 64 characters, starting and ending with a letter or digit. A name is lower-cased for you.

POST/v1/templates   PUT/v1/templates/:name

Creates a template, or adds a version to one that exists. POST takes the name in the body; PUT takes it in the path.

The response is 201 for a new version and 200 with "unchanged": true when the bytes are identical to the current version. Re-uploading the same file does not burn a version number, because a workflow that syncs a template on every run should not fill the history with copies of one file.

{
  "request_id": "dm_ttYFcKAbX-Fn",
  "id": "tpl_SGmNyoFTTGVf",
  "name": "lines",
  "format": "docx",
  "version": 1,
  "unchanged": false,
  "size": 1129,
  "fields": [ /* the same typed descriptors as GET …/fields, see below */ ],
  "macro_enabled": false
}

The file is identified and the fields extracted at upload time, so a file that cannot be filled is refused while you are looking at the response rather than at 3 a.m. when a workflow runs.

GET/v1/templates

Every template on the account, with its current version, size, SHA-256 and field list.

GET/v1/templates/:name

One template in full, including versions.

GET/v1/templates/:name/fields#

The endpoint this product is built around. Same response as inspect — fields, names, tags, sample_data — for a stored template. Free. Accepts ?version=N.

The fields are re-derived from the stored bytes on every call rather than served from what was recorded at upload, so a template uploaded before a renderer improvement still reports accurately.

curl -H "Authorization: Bearer dm_live_xxx" \
  "https://docmint-832s.onrender.com/v1/templates/lines/fields"

{
  "id": "tpl_SGmNyoFTTGVf",
  "name": "lines",
  "format": "docx",
  "version": 1,
  "fields": [
    { "name": "invoice_no", "scope": "", "type": "string", "repeating": false,
      "required": true, "formatters": [], "used": 2,
      "locations": ["word/document.xml, paragraph 1"] },
    { "name": "customer", "scope": "", "type": "string", "repeating": false,
      "required": true, "formatters": [], "used": 2,
      "locations": ["word/document.xml, paragraph 1"] },
    { "name": "items", "scope": "", "type": "array", "repeating": true,
      "required": true, "formatters": ["sumProduct", "currency"], "used": 4,
      "locations": ["word/document.xml, table 1 row 2",
                    "word/document.xml, paragraph 8"] },
    { "name": "description", "scope": "items", "type": "string", "repeating": false,
      "required": true, "formatters": [], "used": 1,
      "locations": ["word/document.xml, table 1 row 2, paragraph 5"] },
    { "name": "qty", "scope": "items", "type": "number", "repeating": false,
      "required": true, "formatters": [], "used": 1,
      "locations": ["word/document.xml, table 1 row 2, paragraph 6"] },
    { "name": "price", "scope": "items", "type": "number", "repeating": false,
      "required": true, "formatters": ["currency"], "used": 1,
      "locations": ["word/document.xml, table 1 row 2, paragraph 7"] }
  ],
  "names": ["invoice_no", "customer", "items", "description", "qty", "price"],
  "tags": [ … ],
  "sample_data": {
    "invoice_no": "invoice no",
    "customer": "customer",
    "items": [{ "description": "description", "qty": 0, "price": 0 }]
  }
}

Three fields live at the root and three inside items, and the response says so with scope rather than leaving you to infer it from a flat list of six names. That is what a form builder — or n8n's resourceMapper — needs in order to render a repeating section instead of a JSON textarea.

GET/v1/templates/:name/file

The stored bytes back, with the right content type and a Content-Disposition. Accepts ?version=N. Free — downloading a file you already uploaded is not metered.

DELETE/v1/templates/:name

Deletes the template and every version of it. There is no undo.

{ "deleted": true, "id": "tpl_SGmNyoFTTGVf", "name": "lines" }

Errors

{
  "error": {
    "code": "template_not_found",
    "message": "You have no template called \"nope\".",
    "hint": "Templates on this account: report (docx), lines (docx), quote (docx),
             invoice (docx).",
    "details": { "available": ["report", "lines", "quote", "invoice"] },
    "docs": "https://docmint-832s.onrender.com/docs#templates"
  }
}

Versions and rollback#

Every upload is a new version rather than an overwrite. A template is a thing a business depends on, and discovering an hour after replacing one that the old one was better has to be recoverable. The most recent 20 versions are kept; older ones are pruned oldest-first and never below one.

curl -H "Authorization: Bearer dm_live_xxx" \
  https://docmint-832s.onrender.com/v1/templates/quote/versions

{
  "id": "tpl_6G2UxfHtsmUu",
  "name": "quote",
  "current": 2,
  "versions": [
    { "version": 2, "size": 1035,
      "sha256": "b9902f378a8b4922c20ea48cef9087ef3cab315eba53bbd70aaab46884b9128e",
      "note": "added a validity date", "fields": 3,
      "created_at": "2026-08-25T08:54:04.109Z" },
    { "version": 1, "size": 1001,
      "sha256": "4efcfcbf0ff3a2f945fb3619bb5ad0a61183b7d7e37ba39f55221d2bca9d59d2",
      "note": null, "fields": 2,
      "created_at": "2026-08-25T08:51:07.079Z" }
  ]
}

Pin a render to one version with "template_version": 2. Roll the whole template back with:

curl -X POST https://docmint-832s.onrender.com/v1/templates/quote/rollback \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"version":1}'

{ "request_id": "dm_FdTo_2gvw4ko", "id": "tpl_6G2UxfHtsmUu",
  "name": "quote", "version": 3, "restored_from": 1 }

Rolling back copies the old version forward as a new one rather than deleting the versions after it. Nothing is lost, and a rollback made in a panic can itself be rolled back.

GET/v1/usage#

This calendar month's credits and a breakdown of what produced them, grouped by kind, format, output mode and success.

{
  "plan": { "id": "free", "name": "Free", "price_usd": 0 },
  "credits": { "used": 12, "limit": 30, "remaining": 18 },
  "period_start": "2026-08-01T00:00:00.000Z",
  "breakdown": [
    { "kind": "render", "format": null,   "output": "document", "ok": false,
      "n": 9, "credits": 0, "avg_ms": 14 },
    { "kind": "render", "format": "docx", "output": "document", "ok": true,
      "n": 7, "credits": 7, "avg_ms": 20 },
    { "kind": "render", "format": "docx", "output": "pdf",      "ok": true,
      "n": 1, "credits": 2, "avg_ms": 3381 },
    { "kind": "render", "format": "pptx", "output": "document", "ok": true,
      "n": 1, "credits": 1, "avg_ms": 22 },
    { "kind": "render", "format": "xlsx", "output": "both",     "ok": true,
      "n": 1, "credits": 2, "avg_ms": 2705 }
  ]
}

Note the first row: nine failed renders, zero credits. A usage record holds what kind of call it was, the format, the output mode, the duration, the stage timings, whether it succeeded and the error code if not. It never holds document content or the request body.

GET/v1/capabilities#

No key needed. What this build can actually do, published so that the documentation and any client can be checked against the running code rather than against a README that drifted. The formatter list is read out of the module, so a formatter cannot be documented into existence — and the list on this page is checked against this endpoint, in both directions, before the page ships.

curl https://docmint-832s.onrender.com/v1/capabilities

{
  "formats": [
    { "id": "docx", "name": "Word document",   "mime": "application/vnd.openxml…" },
    { "id": "xlsx", "name": "Excel workbook",  "mime": "application/vnd.openxml…" },
    { "id": "pptx", "name": "PowerPoint deck", "mime": "application/vnd.openxml…" }
  ],
  "outputs": ["document", "pdf", "both"],
  "pdf": { "available": true, "engine": "libreoffice", "concurrency": 1 },
  "formatters": [
    { "name": "add", "does": "add:5" },
    { "name": "count", "does": "how many items" },
    { "name": "currency", "does": "currency:EUR gives EUR 1,234.57" }
  ],
  "limits": {
    "max_template_bytes": 26214400,
    "max_data_bytes": 8388608,
    "max_versions_kept": 20,
    "pdf_timeout_ms": 90000
  },
  "credits": { "document": 1, "pdf": 2, "both": 2 }
}

GET/healthz#

No key needed. Reports whether LibreOffice is actually present — an image built without it looks perfectly healthy right up until the first request that asks for a PDF — and how many conversions are running and queued. Add ?db=1 to time two trivial database round trips and see the connection pool's state.

{
  "ok": true,
  "pdf": { "available": true, "active": 0, "queued": 0, "limit": 1 },
  "db": { "first_ms": 3.4, "second_ms": 2.5,
          "pool": { "total": 1, "idle": 1, "waiting": 0 }, "error": null }
}

Not available yet#

Two things are being built and are not reachable on this deployment. They have sections here because the code that will emit them already links to these anchors, and a documentation link in an error message that 404s is worse than no link at all.

Every one of these answered 404 unknown_endpoint when this page was written, on 25 August 2026: POST /v1/jobs, GET /v1/jobs, GET /v1/jobs/:id, POST /v1/jobs/:id/cancel, POST /v1/render/batch, GET /v1/webhooks. Nothing about their behaviour is described here, because nothing about their behaviour has been observed.

Asynchronous rendering#

Not available yet. Every render today is synchronous: you POST, and the response body is the file. That is the right shape for one document and the wrong shape for five hundred, so a queued mode with a webhook callback is in progress.

Until it ships: render one document per request. A PDF takes about 2.7 s and conversions are serialised per instance, so pace a large run rather than firing it all at once — the rate limit is 120 requests a minute with a burst of 30, and a full conversion queue answers 503 pdf_queue_full rather than dropping the request silently.

When it ships, this section is replaced by its reference. If you have arrived here from an error message naming /docs#async and this is still the text you see, the feature is newer than this page — please report it, because that is exactly the drift this page is built to avoid.

Batch rendering#

Not available yet. One template, many data rows, one call. Same status as above, and the same advice: loop over POST /v1/render in your workflow tool for now, which is what an n8n or Make loop does naturally, and which keeps a failure attributable to a single row.

Formats, and what each one cannot do#

Three formats, one syntax. The file is identified from the main part's content type in [Content_Types].xml, not from its extension or the MIME type a client claimed — both are routinely wrong, and the failure they cause is a stack trace inside a zip parser rather than a sentence you can act on.

Word — what is not implemented

• No HTML or Markdown into a document. A value goes in as text, inheriting the placeholder's own formatting. For anything richer there is {@rawXml}, which is raw WordprocessingML and entirely your responsibility.
• No charts, no styling API, no footnote or subtemplate features. Whatever style the placeholder carries is what the value inherits, and that is the whole styling story.
• Images are PNG, JPEG, GIF or BMP, up to 24 MB each.

Excel — what is not implemented, and where it is subtle

• Cell types matter, and are handled deliberately. A cell whose entire content is one placeholder becomes: a real numeric cell if the value is a JS number or the last formatter is arithmetic (sum, sumProduct, count, round, multiply, add, subtract, divide); a boolean cell for a boolean; an Excel date serial for a date value in a cell that already has a date number format; and an inline string for everything else. The cell keeps its s= style, so its number format, font, border and fill survive.
• A numeric string stays text on purpose. Turning "007" into 7 would quietly ruin part numbers and postcodes. Write {n|add:0} if you want it coerced.
• currency, number, percent and date produce text, on purpose — you asked for that exact string. To get a real number that still displays as money, format the cell in the template and write a bare {total}: the cell's own number format does the work and SUM() over the column still adds up.
• No column loops and no sheet loops. A section whose two tags sit in one row is a row loop, because a loop that repeated part of a row would leave the rest of the line behind.
• Formula rewriting has known edges. Row insertion semantics are followed, so SUM(D5:D6) over a loop body becomes SUM(D5:D10) when the loop produced six rows. But a range whose two ends are the same repeated row — SUM(B3:B3) over a per-group subtotal — widens to first..last occurrence and therefore covers the rows in between as well, so a grand total is better written as a sum of the detail rows than as a sum of the subtotals. Chart series and pivot caches keep their own copies of the ranges they read and are not rewritten.
• The shared string table is never edited: a cell containing a tag is rewritten as an inline string instead. Orphaned shared entries are left behind, which Excel ignores.
• A sheet that would need more than 1,048,576 rows fails with too_many_rows.

PowerPoint — what is not implemented

• Images are PNG, JPEG or GIF only — the formats PowerPoint embeds without conversion. A BMP that is fine in Word is refused here.
• Section markers must open and close inside the same text box; a {#a} in one shape and its {/a} in another is section_unbalanced.
• Notes slides are filled too, and report locations as slide N notes, shape "…".
• The finished package is re-checked against the invariants PowerPoint enforces — slide list, relationships, content-type overrides, slide id ranges — before the bytes are returned, because PowerPoint refuses the whole file if any one of them is inconsistent and says only "PowerPoint found a problem with content". A failure here is package_invariant and is a bug worth reporting.

Not accepted at all

Every error code#

Every error has the same shape. code is stable and safe to switch on; message is one line for a human; hint says what to change; docs links to the section of this page that explains it; details carries the machine-readable specifics, and request_id identifies the exact log line.

{
  "error": {
    "code": "placeholder_unresolved",
    "message": "…", "hint": "…",
    "docs": "https://docmint-832s.onrender.com/docs#errors",
    "details": { "field": "…", "location": "…", "available": ["…"], "format": "docx" },
    "request_id": "dm_…"
  }
}

400 — the request is wrong

401, 402, 404, 409 — who you are, what you have

413, 415 — too big, or the wrong kind of file

422 — the template and the data disagree

Everything here comes back with details.field, details.location and usually details.available. A 422 costs no credits.

429, 5xx

Limits#

The same for every plan. There is no feature ladder. These numbers are served by GET /v1/capabilities, so they can be checked rather than trusted.

Rate-limit state comes back on every authenticated response as X-RateLimit-Limit, X-RateLimit-Burst and X-RateLimit-Remaining; a 429 also carries Retry-After. The bucket lives in the instance's memory, which is the honest implementation while there is one instance.

Quota and credits#

One credit is one document produced.

The PDF costs one extra because it costs about a hundred times the CPU of the fill — roughly 2.7 s against roughly 10 ms — and pretending the two are the same price would mean the cheap path subsidising the expensive one. Nothing else is metered. Downloading a file you already generated is free, and so is asking a template what it needs.

The month

Quotas are per calendar month, in UTC, and reset on the 1st. The window rolls forward lazily on your first request of the new month, so there is no cron job that can fail to run. GET /v1/usage reports period_start.

Subscribing mid-month does not hand you a second quota. The window is the calendar month whatever day you subscribed on, and a renewal only resets the counter if the calendar month has actually turned over.

At the ceiling

{
  "error": {
    "code": "quota_exceeded",
    "message": "You have used all 30 documents included in your free plan this month.",
    "hint": "The quota resets on the 1st of next month. To raise it now, upgrade …",
    "details": { "plan": "free", "credits_used": 30, "credits_limit": 30 },
    "docs": "https://docmint-832s.onrender.com/docs#quota"
  }
}

There is no overage billing and no surprise invoice: the API answers 402 until the next period or until the plan changes.

Plans, pricing and billing#

Every plan has every feature: all three formats, PDF output, images, the typed field list, the missing-field contract, the outer-scope warning, versioning and rollback, localisation, and the same limits. There is no paid module and no per-feature licence, now or ever — the fill engine is written for this project and depends on nothing that could start charging for a feature later.

GET/v1/billing/plans

No key needed. The plan list as the running code has it, so a page cannot show three plans while the API knows about four. A plan with no price configured is listed and marked "purchasable": false rather than hidden.

{
  "billing_available": true,
  "plans": [
    { "id": "free",    "name": "Free",    "price_usd": 0,  "documents_per_month": 30,     "purchasable": false },
    { "id": "starter", "name": "Starter", "price_usd": 9,  "documents_per_month": 2000,   "purchasable": true },
    { "id": "pro",     "name": "Pro",     "price_usd": 29, "documents_per_month": 20000,  "purchasable": true },
    { "id": "scale",   "name": "Scale",   "price_usd": 99, "documents_per_month": 100000, "purchasable": true }
  ],
  "note": "One document costs one credit. Asking for a PDF costs one more, because
           converting it costs about a hundred times the CPU. Downloading a file you
           already made is free."
}

POST/v1/billing/checkout

Starts a subscription. Send {"plan": "starter"}; you get back a Stripe Checkout URL to open in a browser. Card details never touch this service.

curl -X POST https://docmint-832s.onrender.com/v1/billing/checkout \
  -H "Authorization: Bearer dm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"plan":"pro"}'

{ "url": "https://checkout.stripe.com/c/pay/cs_live_…",
  "plan": "pro",
  "expires_at": 1787735655 }

The session collects a billing address and offers an optional VAT ID, which Stripe then puts on the invoice — an EU business needs it there or its accountant will not accept the receipt. Promotion codes are accepted. Because there is no dashboard yet, Stripe returns you to /docs#quota afterwards.

POST/v1/billing/portal

Returns a Stripe customer-portal URL for changing the plan, updating the card, downloading invoices, or cancelling. Takes no body.

{ "url": "https://billing.stripe.com/p/session?secret=…" }

Cancelling stops the next charge; it does not refund the current month. There is no overage billing at any point.