Endpoint reference
POST /api/text-to-pdf
Turn Markdown, plain text or CSV into a PDF: headings, lists, tables, code blocks and links on the built-in fonts, on A4 or Letter pages. Returns application/pdf.
This is not HTML-to-PDF. It does not render HTML or CSS, has no custom fonts and does not embed images. It lays out a fixed Markdown subset, plain text or CSV itself, in Helvetica (Courier for code), and the same request always produces the same bytes. Use it for reports, notes, logs, exports and generated documents; for a web page as it looks in a browser, it is the wrong tool.
Request
Method: POST. URL: https://pdfops.dev/api/text-to-pdf. Body: application/json, up to 1 MB. Numbers and booleans must be JSON numbers and booleans, not strings.
| Field | Type | Required | Description |
|---|---|---|---|
content | String | Yes | The document, up to 512 KiB of UTF-8 (tabs count as 4 spaces). Must not be blank. A leading BOM is dropped and CRLF line endings are accepted. |
format | String | No | markdown (default), text or csv. |
page_size | String | No | letter (default, 612 x 792 pt) or a4 (595.28 x 841.89 pt). |
margin | Number | No | Page margin in points on all four sides, 18 to 144. Default 54 (0.75 inch). |
font_size | Number | No | Body text size in points, 6 to 36. Default 11. Headings scale from it. |
title | String | No | Sets the PDF's Title metadata, up to 200 characters. Not printed on the page. |
page_numbers | Boolean | No | true prints Page n of N, centred in the bottom margin. Default false. |
monospace | Boolean | No | Set body text in Courier instead of Helvetica. Only used with format: "text"; ignored for the other formats. Default false. |
The optional X-API-Key header works as on /api/merge: no header is anonymous, 100 requests per IP per month; a valid key uses your tier's quota; an invalid or revoked key returns 401 invalid_api_key. A successful (2xx) call counts 1 request, however many pages it makes. Check consumption with GET /api/usage.
Response
On success: 200 OK, Content-Type: application/pdf, the PDF as the body. Dates in the PDF are fixed and the Producer is pdfops.dev, so the same request returns byte-identical output. The page carries no PDFops footer, on any plan: it is your document.
On any failure: 4xx or 500, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.
Markdown subset
The Markdown reader is a small, fixed subset, not a full CommonMark or GitHub renderer. What is drawn:
- Headings
#to######, with optional closing#s, kept together with the line that follows. - Paragraphs with bold (
**x**,__x__), italic (*x*,_x_) and`code`. Emphasis follows the CommonMark delimiter rules, sosnake_casestays literal and an unmatched marker is printed as typed. Backslash escapes work on ASCII punctuation. A hard line break is two trailing spaces or a trailing backslash. - Links
[text](url),[text](<url>)and[text](url "title"). They print as blue text followed by the URL in parentheses, so the address survives printing; the title is ignored. Onlyhttp://,https://andmailto:links are also clickable, up to 2,000 links per document and 2,048 characters per URL. Past those caps the link still prints as text. An empty destination is plain text. - Fenced code blocks with
```or~~~, in Courier on a shaded background. Whitespace is kept exactly; a line wider than the page wraps at the margin like a terminal. The language after the fence is not used for highlighting. - Lists, bulleted (
-,*,+) or numbered (1.or1); both are drawn as1.). An item can hold more paragraphs, a code block, a quote or a table when indented under it. Nesting goes one level deep; deeper items are drawn at that level. - Blockquotes with
>, one level. What is inside is read as Markdown, so lists, code and tables work in a quote. - Horizontal rules
---,***and___. - Tables in the GitHub pipe form: a header row, a
|---|---|separator, then rows. The header is bold and shaded and repeats on each page; columns are sized from the content and cells wrap. A pipe inside a code span or written\|does not split a cell. Up to 20 columns and 100,000 cells. - Page breaks with
\pagebreakor<!-- pagebreak -->on a line of its own. Repeated or trailing breaks never make an empty page.
What stays literal text: images (), raw HTML, setext headings (text underlined with ===; text over a --- line is a paragraph followed by a horizontal rule), task-list boxes, and anything else not listed above. Table column alignment (:---:) is ignored; every column is left-aligned. A pipe table with more than 20 columns is printed as ordinary paragraph text.
format: "text" draws the content as typed: spaces and line breaks are kept, long lines wrap at the margin, and nothing is interpreted. format: "csv" follows RFC 4180 (quoted fields, doubled quotes, commas and line breaks inside quotes); blank lines are skipped, short rows are padded to the widest row, and the first row is the header.
Limits
| Limit | Value | Over the limit |
|---|---|---|
| Request body | 1 MB | 413 request_too_large |
content | 512 KiB of UTF-8, counted again after tabs become 4 spaces | content_too_large |
| Output pages | 200 | too_many_pages |
| CSV | 20 columns, 10,000 rows, 100,000 cells | too_many_columns, csv_too_large |
| Markdown table | 100,000 cells | table_too_large |
| Draw operations | 115,000 | content_too_complex |
| List items / blocks | 30,000 / 60,000 | content_too_complex |
| Characters | WinAnsi only | unsupported_characters |
Draw operations. Every piece of text drawn, shaded rectangle, rule and link is one operation, and a document may use 115,000 of them. Ordinary prose never gets near it. Tables do, because every wrapped line inside a cell is its own operation, so the cell cap alone does not tell you what fits. Examples: 20 columns of a single character c at font_size 6 and margin 18 fit all 100,000 cells (5,000 rows); 20 columns of 1234.56 at font_size 11 and the default margin on Letter fit at most 1,738 rows including the header (34,760 cells, 1,758 rows on A4), because those cells wrap, and one more row returns content_too_complex. A smaller font_size or a smaller margin stops cells wrapping. Heavy inline formatting (thousands of bold, italic, code and link runs) draws against the same budget, and the error message says whether tables or inline formatting used it up. The fix is a shorter document, fewer rows or columns, a smaller font_size, or several requests.
Characters. The built-in fonts draw WinAnsi (Windows-1252, roughly Latin-1) only: English and Western European letters, digits, common punctuation, curly quotes, dashes, the euro sign. Emoji, Cyrillic, Greek, CJK and Arabic are rejected with unsupported_characters rather than replaced with a blank. details gives the code point and the line and column of the first one in your text, for example U+041F ("П") at line 3, column 8. Replace or remove it and retry.
Error codes
| Error code | Status | Trigger |
|---|---|---|
invalid_json | 400 | Request body isn't parseable JSON. |
invalid_body | 400 | The JSON is valid but is not an object. |
missing_content | 400 | content is absent, blank, or (for CSV) has no rows. |
invalid_content | 400 | content is not a string. |
content_too_large | 400 | content is over 512 KiB of UTF-8, as sent or after tabs expand to 4 spaces. |
invalid_format | 400 | format is not markdown, text or csv. |
invalid_page_size | 400 | page_size is not a4 or letter. |
invalid_parameter | 400 | margin or font_size is not a JSON number in range, title is not a string of at most 200 characters, or page_numbers or monospace is not a boolean. |
unsupported_characters | 400 | content has a character outside WinAnsi. details names the code point, line and column. |
invalid_csv | 400 | A quoted CSV field is never closed. |
too_many_columns | 400 | A CSV row has more than 20 cells. |
csv_too_large | 400 | The CSV has more than 10,000 rows or 100,000 cells. |
table_too_large | 400 | A Markdown table has more than 100,000 cells. |
table_too_wide | 400 | A table has more columns than fit across the page at this font_size and margin. details gives how many fit. |
content_too_complex | 400 | More than 115,000 draw operations, 30,000 list items or 60,000 blocks. details says which. |
too_many_pages | 400 | The output would be more than 200 pages. |
render_failed | 500 | The document could not be laid out. |
save_failed | 500 | The finished PDF could not be serialized. |
request_too_large | 413 | The whole request body is over 1 MB. Rejected before anything is parsed. |
invalid_api_key | 401 | An X-API-Key header was sent but the key is unknown or revoked. No fallback to the anonymous IP cap. Get a fresh key at /pricing. |
rate_limited (anonymous) | 429 | No X-API-Key header and the per-IP limit (100/month) is exhausted. Retry-After gives seconds until next calendar month. |
rate_limited (keyed) | 429 | Your key's tier quota (Free 250 / Indie 4,000 / Pro 25,000 per month) is exhausted. Retry-After gives seconds until next calendar month. |
Example
Markdown with a heading, emphasis, a link, a list and a table, with page numbers:
curl -X POST https://pdfops.dev/api/text-to-pdf \
-H "Content-Type: application/json" \
-H "X-API-Key: pdfops_live_..." \
-d '{"content": "# Release notes\n\nVersion **2.4** is out. See the [changelog](https://example.com/changelog).\n\n- Faster merges\n- New `title` option\n\n| Plan | Requests |\n|---|---|\n| Free | 250 |\n| Indie | 4,000 |", "title": "Release notes", "page_numbers": true}' \
-o notes.pdf # optional key raises your quota to your tier
Plain text, kept exactly as typed, in Courier on A4:
curl -X POST https://pdfops.dev/api/text-to-pdf \
-H "Content-Type: application/json" \
-d '{"content": "ORDER 1042\n qty item\n 2 widget\n 1 gadget", "format": "text", "monospace": true, "page_size": "a4"}' \
-o order.pdf
CSV as a table (the first row is the header; quote a field that contains a comma):
curl -X POST https://pdfops.dev/api/text-to-pdf \
-H "Content-Type: application/json" \
-d '{"content": "name,qty,price\nWidget,2,9.50\n\"Gadget, large\",1,24.00", "format": "csv"}' \
-o items.pdf
Keyless calls work: 100 requests per IP per month with no key.
Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.
Code examples
Have an API key? Add an X-API-Key header to any request. It is optional, and it raises your quota from 100/IP/month to your tier's.
JavaScript (Node.js 22+) — built-in fetch
import { writeFile } from 'node:fs/promises';
const headers = { 'Content-Type': 'application/json' };
if (process.env.PDFOPS_API_KEY) headers['X-API-Key'] = process.env.PDFOPS_API_KEY; // optional
const res = await fetch('https://pdfops.dev/api/text-to-pdf', {
method: 'POST',
headers,
body: JSON.stringify({
content: '# Release notes\n\n- Faster merges',
title: 'Release notes',
page_numbers: true,
}),
});
if (!res.ok) {
const err = await res.json();
throw new Error(`PDFops text-to-pdf failed: ${err.error}: ${err.details}`);
}
await writeFile('notes.pdf', Buffer.from(await res.arrayBuffer()));
Python — requests
import os, requests
res = requests.post(
"https://pdfops.dev/api/text-to-pdf",
headers={"X-API-Key": os.environ.get("PDFOPS_API_KEY", "")}, # optional
json={
"content": "name,qty\nWidget,2\nGadget,1",
"format": "csv",
"title": "Items",
},
)
res.raise_for_status()
with open("items.pdf", "wb") as f:
f.write(res.content)
From an AI agent (MCP)
The hosted MCP server at https://pdfops.dev/api/mcp exposes this as the pdf_text_to_pdf tool. It takes the same fields and returns the PDF inline as an application/pdf resource. See PDFops for AI agents.
Behavioral notes
- Not HTML-to-PDF. No HTML, CSS, custom fonts or images. The fonts are the standard Helvetica family and Courier.
- Deterministic. The same request returns byte-identical PDF bytes.
- Unbranded. No "Generated with" footer, on any plan.
- Nothing is stored. The document is built for the response and not kept.
- Limits: 1 MB request, 512 KiB of content, 200 output pages, 115,000 draw operations.
FAQ
How do I convert Markdown to PDF with an API?
POST a JSON body with a content field holding the Markdown to https://pdfops.dev/api/text-to-pdf. The response is the PDF. Headings, lists, tables, code blocks, quotes and links are laid out on the built-in fonts; set page_size, margin and font_size to change the page.
Is this HTML to PDF?
No. This endpoint lays out a fixed Markdown subset, plain text or CSV itself, on the standard Helvetica and Courier fonts. It does not render HTML or CSS, load custom fonts or embed images, and it has no headless browser.
How do I turn a CSV into a PDF table?
Send the CSV as content with format set to csv. The first row becomes a shaded header row that repeats on each page; columns are sized from the content and cells wrap. Up to 20 columns, 10,000 rows and 100,000 cells.
Why was my text rejected with unsupported_characters?
The built-in fonts only draw WinAnsi (Windows-1252, roughly Latin-1) characters. Anything outside that range, such as emoji, Cyrillic, Greek or CJK, is rejected instead of being replaced with a placeholder. The error names the code point and its line and column in your text.
Is the output the same every time?
Yes. The same JSON request produces byte-identical PDF bytes: the PDF dates are fixed and nothing random is written. The output carries no PDFops footer or branding.
Related: Generate an invoice PDF · Stamp text on a PDF · Add text and images at a position.
Get a free API key. Keyless calls get 100 requests per IP per month; a free key raises that to 250, with no card. Enter your email and the key arrives in your inbox.