Docs

API and MCP

Send content or a Word, Excel or PowerPoint file and get a PDF in your company's brand, document profiles and locale. The REST API and the MCP server use the same rendering and the same plan limits. This page documents what is built today.

Overview

• There is one shared MCP endpoint. Your company is taken from the credential you present. It is never part of the address or a tool argument, and the address alone grants no access.
• An account only works after a verified manager has accepted the Terms and activated it. Until then every call is refused with account_not_activated. Suspended or closed accounts are refused with account_unavailable.
• The MCP address above is the intended public address. The dashboard Connect page shows the address for your deployment.

Authentication

Create a key in the dashboard under API keys. A key starts with ppdf_, is shown once, is stored only as a hash and can be revoked at any time. Keys can have an expiry (1 to 730 days). Send it as follows.

Keys have a scope: render (render documents, read usage and profiles) or admin (also manage keys, image hosts and invitations; admin implies render). A call without the needed scope is refused with insufficient_scope. Keep keys in a secret store, never in source code, a web page or a prompt.

Sign-in (OAuth) status

POST/v1/render

Render Markdown or HTML into a PDF in the company's design. Scope: render. Each accepted request counts as one render against the monthly plan limit; a render that fails is not counted.

JSON body:

With delivery set to pdf the response is application/pdf with Cache-Control: no-store. With link the response is JSON:

{"download_url": "https://api.prettypdfprinter.com/v1/dl/TOKEN", "expires_at": "2026-11-06T15:00:00Z",
 "filename": "Offer-2026-118.pdf", "pages": 2, "size_bytes": 48211, "locale": "de-AT"}

The download address is the only credential needed to fetch the file (GET /v1/dl/{token}), expires after one hour by default and answers 404 once expired.

POST/v1/render/file

Render an uploaded Word (.docx), Excel (.xlsx) or PowerPoint (.pptx) file. Multipart form with the field file (required) and the optional fields profile_id, locale, title, delivery and cleanup, which behave as above. Scope: render.

• Files are limited to 20 MB. The converted text is limited to 1 MiB.
• Embedded images are kept while they fit (200 KB each, 600 KB in total); the rest are replaced by their description. Excel is converted as tables.
• The file type is checked against its content, not only its name.

POST/v1/render/template

Fill one of your company's fixed-layout templates with structured data. Templates are set up by Pretty PDF. List yours with GET /v1/document-templates. Send template, data and optionally locale, title and delivery. Totals and VAT are calculated for you; any totals you send are ignored.

GET/v1/usage

This month's renders and API calls, the plan limits, and how many keys and document profiles exist. Scope: render. GET /v1/usage/history?months=6 returns monthly totals, oldest first (1 to 24 months).

{"period": "2026-11", "plan": "starter", "renders": 12, "api_calls": 15,
 "limits": {"renders_per_month": 300, "api_calls_per_month": 300, "max_document_profiles": 1,
            "max_api_keys": 2, "max_locales": 1},
 "api_keys": 1, "document_profiles": 1}

A limit of null means unlimited.

/v1/company/api-keys

Scope: admin. The company console in the dashboard uses these routes.

Creating and revoking keys is limited to a signed-in company manager. A request authenticated by an API key is refused with not_manager, so a leaked key cannot create more keys.

MCP server

Transport: Streamable HTTP at https://mcp.prettypdfprinter.com/mcp. Add it to your assistant as a custom connector or remote MCP server and, where the client supports a header, set Authorization to Bearer followed by a space and your key. See the sign-in status above.

• Every tool call counts as one API call against the monthly plan limit. A tool that renders also counts as one render. Over the limit, the tool returns a message that names the limit.
• Rendering tools return a time-limited download link (one hour by default), not the file itself.
• Each call writes a metadata-only audit row (the tool name, never the content).

Tools reference

whoami

Show which company and scopes this connection is using.

• Parameters: No parameters.
• Returns: company_id and scopes.

list_document_profiles

List this company's document profiles.

• Parameters: No parameters.
• Returns: A list with id, name, template, page_size, orientation and is_default.

render_document

Render Markdown or HTML into a PDF in the company's design.

• Parameters: content (string, required); content_type (markdown default, or html); profile_id (optional; omit for the company default); locale (optional tag such as sl-SI; default en-GB); title (optional).
• Returns: download_url, expires_at, filename, pages, size_bytes, locale.

convert_file

Convert a Word, Excel or PowerPoint file, sent as base64, into a branded PDF.

• Parameters: filename (string, required; its extension decides the type); file_base64 (string, required; about 3 MB of file at most); profile_id, locale, title (optional, as above).
• Returns: Same as render_document. For larger files use POST /v1/render/file.

list_document_templates

List the fixed-layout templates set up for your company, with the fields each one needs and an example of the data.

render_from_template

Fill a fixed-layout template with structured data and get a temporary download link. Send only the facts: the layout is locked, and totals and VAT are calculated by Pretty PDF.

• Parameters: template, data, optional locale and title.

validate_content

Check content before rendering. Nothing is rendered, stored or counted as a render.

• Parameters: content (string, required); content_type (markdown default, or html).
• Returns: {"valid": true, "remote_images": [...], "sanitized_bytes": n}, or {"valid": false, "code": ..., "message": ...}.

A tool to fetch an earlier document is not available: documents are not kept after rendering other than the temporary link.

Locales

A locale decides paper size, number, date and currency formats, the fixed labels in the document language and which company disclosure fields a business document should show. Formats come from CLDR data. Thirteen tags are supported:

A language without a region resolves to a default: en to en-GB, de to de-DE, and likewise sl, hr, fr, it, es, nl, pl. Any other tag is refused with unknown_locale; it never falls back silently.

Errors

Errors from the REST API have the shape {"detail": {"code": "...", "message": "..."}, "status_code": 422}. A bad key gives "detail": "Invalid API key" with status 401 and the same message for an unknown, malformed, revoked or expired key. MCP tools report the message as a tool error.

Plan limits

Limits apply per company and per calendar month (UTC). They are read from the plan assigned to the company; the prices of the plans are on the pricing page.

A render counts against renders. Every MCP tool call counts against API calls. Check your own figures with GET /v1/usage.

Examples

curl: Markdown to PDF

curl -X POST https://api.prettypdfprinter.com/v1/render \
  -H "X-API-Key: $PRETTY_PDF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Offer 2026-118\n\nThank you for your enquiry.",
       "content_type": "markdown",
       "locale": "de-AT",
       "title": "Offer 2026-118",
       "delivery": "pdf"}' \
  -o offer.pdf

curl: Excel file to PDF

curl -X POST https://api.prettypdfprinter.com/v1/render/file \
  -H "X-API-Key: $PRETTY_PDF_KEY" \
  -F [email protected] \
  -F locale=en-GB \
  -F delivery=pdf \
  -o datasheet.pdf

Python

import os
import requests

resp = requests.post(
    "https://api.prettypdfprinter.com/v1/render",
    headers={"X-API-Key": os.environ["PRETTY_PDF_KEY"]},
    json={"content": "# Offer 2026-118\n\nThank you for your enquiry.", "locale": "sl-SI"},
    timeout=60,
)
if resp.status_code == 200:
    with open("offer.pdf", "wb") as f:
        f.write(resp.content)
else:
    print(resp.status_code, resp.json()["detail"])

Need help or a profile set up for your brand? Request samples or open the dashboard.