formfeed

Official

Overview Schema Source Related Servers Discussions Admin

Render a document

render

Create a PDF, image, DOCX or PPTX from a stored template or HTML filled with your data, and get a download link back. Use it to turn data into a finished document.

Instructions

Creates a document by filling a stored template, or ad-hoc html, with data: a PDF or image, or DOCX, PPTX or PDF from Word and PowerPoint templates. Returns the render with status and download_url; for an image (png, jpg or webp) up to 2 MB the result also carries the picture itself, so look at what you made before handing it on (a PDF comes as its link). Use it to make a document from data; to turn an existing office file into a PDF, use convert_to_pdf. Stored templates render their published version, so one whose published_version is null fails with template_not_found. Every call is a new render: a live key or a signed-in agent consumes units, a test key is free (watermarked on the Free plan). A render that fails returns status failed and an error with code and message; validate_template finds most causes beforehand. With einvoice the PDF becomes a ZUGFeRD / Factur-X e-invoice built from data._invoice (check the block with check_invoice first): the render then carries einvoice, the validator's report, and a refused invoice names the fields and rules to fix. The link expires at expires_at; get_render issues a fresh one.

Input Schema

Name	Required	Description
`data`	No	Values for the template, shaped as get_template_schema describes; leave out when it needs none
`html`	No	A complete HTML document to render instead of a stored template, up to 5 MB
`wait`	No	Most renders are finished when the call returns; true also waits for one that continues in the background, false returns it as it is (queued or rendering) to check later with get_render
`engine`	No	Template language of html, when it contains expressions to fill from data
`locale`	No	BCP 47 tag for helpers and translations, e.g. de-DE
`output`	No	Left out, the template decides: PDF for PDF templates and html, its image format for image templates, its default output for Word and PowerPoint templates. Word templates render docx or pdf, PowerPoint templates pptx or pdf
`einvoice`	No	Makes the PDF a ZUGFeRD / Factur-X e-invoice whose XML is built from data._invoice: true for the defaults, an object to choose, false to switch off what the template declares. PDF only; live renders from the Starter plan, test keys on Free make 20 marked ones a day
`filename`	No	Name of the file behind download_url, e.g. invoice-2026-0042.pdf
`template`	No	Slug or tpl_ id of a stored template; pass this or html

Output Schema

Name	Required	Description
`id`	Yes	rnd_ id of the render
`pdfa`	No	The PDF/A verdict (PDF/A-2b or PDF/A-3b), when the template declares it
`error`	Yes	Why a failed render failed
`units`	Yes	Units the render counted
`status`	Yes
`einvoice`	No	The e-invoice report, when the render made one
`template`	Yes	The template and version rendered; null for html and conversions
`expires_at`	Yes	When download_url stops working; get_render issues a fresh one
`page_count`	Yes
`environment`	Yes
`download_url`	Yes	Signed link to the file; null until the render succeeded
`accessibility`	No	The PDF/UA-1 verdict, when the template declares it

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.22Nov 1, 2026

addedOutput schema / properties / pdfa

Added value: +{
+  "additionalProperties": {},
+  "description": "The PDF/A verdict (PDF/A-2b or PDF/A-3b), when the template declares it",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

Changed1 schema field changedv0.3.19Oct 22, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "accessibility": {
+      "additionalProperties": {},
+      "description": "The PDF/UA-1 verdict, when the template declares it",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "download_url": {
+      "description": "Signed link to the file; null until the render succeeded",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "einvoice": {
+      "additionalProperties": {},
+      "description": "The e-invoice report, when the render made one",
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "environment": {
+      "enum": [
+        "live",
+        "test"
+      ],
+      "type": "string"
+    },
+    "error": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Why a failed render failed"
+    },
+    "expires_at": {
+      "description": "When download_url stops working; get_render issues a fresh one",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "id": {
+      "description": "rnd_ id of the render",
+      "type": "string"
+    },
+    "page_count": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "status": {
+      "enum": [
+        "queued",
+        "rendering",
+        "succeeded",
+        "failed"
+      ],
+      "type": "string"
+    },
+    "template": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "canary": {
+              "type": "boolean"
+            },
+            "channel": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "slug": {
+              "type": "string"
+            },
+            "version": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "id",
+            "slug",
+            "version"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The template and version rendered; null for html and conversions"
+    },
+    "units": {
+      "description": "Units the render counted",
+      "type": "number"
+    }
+  },
+  "required": [
+    "id",
+    "status",
+    "download_url",
+    "expires_at",
+    "page_count",
+    "units",
+    "environment",
+    "template",
+    "error"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.3.17Oct 12, 2026

addedInput schema / properties / einvoice

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "properties": {
+        "display_check": {
+          "description": "What a value of the XML that the PDF does not show does: a warning in the report (default) or a failed render",
+          "enum": [
+            "warn",
+            "strict"
+          ],
+          "type": "string"
+        },
+        "flavour": {
+          "description": "One specification under two names; the default factur-x and zugferd make the same file",
+          "enum": [
+            "factur-x",
+            "zugferd"
+          ],
+          "type": "string"
+        },
+        "profile": {
+          "description": "en16931 (default) carries the whole European standard; basic is the smallest full invoice and is refused between two French businesses",
+          "enum": [
+            "en16931",
+            "basic"
+          ],
+          "type": "string"
+        },
+        "xml": {
+          "description": "both also stores the XML as a file of its own, linked as einvoice.xml_url",
+          "enum": [
+            "embedded",
+            "both"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  ],
+  "description": "Makes the PDF a ZUGFeRD / Factur-X e-invoice whose XML is built from data._invoice: true for the defaults, an object to choose, false to switch off what the template declares. PDF only; live renders from the Starter plan, test keys on Free make 20 marked ones a day"
+}

Changed6 schema fields changedv0.3.10Sep 25, 2026

addedInput schema / properties / data / description

Added value: +"Values for the template, shaped as get_template_schema describes; leave out when it needs none"

changedInput schema / properties / engine / description

Previous value: -"Engine for html that contains template syntax"New value: +"Template language of html, when it contains expressions to fill from data"

addedInput schema / properties / filename / description

Added value: +"Name of the file behind download_url, e.g. invoice-2026-0042.pdf"

changedInput schema / properties / html / description

Previous value: -"Raw HTML instead of a template"New value: +"A complete HTML document to render instead of a stored template, up to 5 MB"

changedInput schema / properties / template / description

Previous value: -"Template slug or tpl_ id"New value: +"Slug or tpl_ id of a stored template; pass this or html"

changedInput schema / properties / wait / description

Previous value: -"Wait for the render to finish (sync renders finish immediately)"New value: +"Most renders are finished when the call returns; true also waits for one that continues in the background, false returns it as it is (queued or rendering) to check later with get_render"

First observedv0.3.7Sep 22, 2026

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly=false, destructive=false), and the description adds real behavioral context: every call is a new render consuming units, test keys are free but watermarked, templates render their published version and fail with template_not_found when null. Failures return status failed with a code/message, and links expire at expires_at. Good additions, but the einvoice and return-shape details are partly duplicated by the output schema, so it sits at a solid 3.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then progressively less common concerns (units, einvoice, expiry). It is long, and the einvoice sentence packs several ideas together, but nearly every sentence carries operational information and could not be cut without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object, mutation tool with an output schema, the description covers source choice, output defaults, failure mode, cost, expiry and the einvoice branch. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents each parameter with enums and nested einvoice fields. The description adds a few non-obvious constraints — data shaped per get_template_schema, data._invoice for einvoice, published-version template selection — but most of its parameter talk restates the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource+output matrix: filling a stored template or ad-hoc html with data, yielding PDF/image/DOCX/PPTX. It explicitly names the sibling it is not (convert_to_pdf) in the same breath, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the positive case ("Use it to make a document from data") and the exclusion with an alternative ("to turn an existing office file into a PDF, use convert_to_pdf"). It also points to validate_template and check_invoice as preflight steps, giving concrete ordering guidance rather than vague hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server