PDF to Markdown API for developers: integrate conversion without the OpenAPI dump

Searchers for a PDF to Markdown API want a keyed HTTP call that returns Markdown for RAG loaders, note apps, or internal tools. On Toolsy that job splits. The browser path PDF to Markdown runs MarkItDown-family conversion for one-off files. The developer path is the OCR API at API docs: POST /api/v1/ocr with a Bearer key, a live tool value, and an image or PDF. There is no invent-your-own pdf-to-markdown API slug today; the Markdown-shaped OCR tool is notes-to-markdown. This guide covers path choice, keys, the real call shape, quotas, and privacy. It is not a full OpenAPI dump.

Why developers search for a PDF to Markdown API

Teams land on “pdf to markdown api” after a local script hits a wall. A folder of vendor PDFs needs to become .md for chunking. A backend must accept uploads and return text without opening a browser. A CI job should fail loud when recognition is unavailable. The head term “pdf to markdown” is huge (thousands of monthly searches in US Ads data) and belongs to the convert page. The API phrase is thinner: Google Ads often omits volume for pdf to markdown api, while Labs shows roughly fifty searches a month and a low difficulty score. Nearby, pdf to markdown python sits around ninety. Treat demand as real but small, and write for people who already know they need HTTP.

Intent is commercial and practical. People want auth, request shape, rate limits, and what the JSON looks like on success. They do not need another essay on why Markdown helps models; that story lives in prepare documents for RAG with Markdown. They also do not need a Marker vs MarkItDown bake-off here; that comparison is already live at Marker vs MarkItDown vs online converters.

If you only convert three PDFs this week, stop reading and use the browser tool. An API key pays off when software, not a human, owns the upload loop.

Browser converter vs keyed API

Two Toolsy surfaces look related and behave differently. Confusing them burns a day of debugging.

The browser converter at PDF to Markdown (and the multi-format hub Convert to Markdown) is for interactive uploads. Free accounts get a small daily MarkItDown quota (three files) and a five megabyte size cap; Pro raises size toward fifty megabytes and removes the daily file cap. You click, wait, download .md. That path matches “pdf to markdown online” intent and one-off cleanup.

The keyed API is documented at API docs. You sign up, create a key under the account API section, and send Authorization: Bearer YOUR_KEY to POST https://toolsy.tools/api/v1/ocr. Usage is a monthly recognition quota, not the same daily MarkItDown counter. Free sandbox after sign-up is forty recognitions per month with no card. Pro and Plus include a hundred per month as trial quota. Steady production traffic needs a dedicated API plan on pricing.

When the browser tool is enough

Use the browser when a human is in the loop, the file count is tiny, and you want MarkItDown-style document conversion for a digital PDF. Spot-check tables and headings by eye. For local library vs browser tradeoffs, see MarkItDown explained.

When you need the API

Use the API when your server, n8n job, or backend route must call Toolsy without a person watching the upload form. Keep the key on the server. Never ship it in public front-end JavaScript. The widget path shares OCR quota for site embeds; that recipe belongs to a later widget article, not this one.

How Toolsy splits PDF work today

Honesty first. The OCR OpenAPI enum lists tools such as handwriting-to-text, receipt-to-excel, and notes-to-markdown. It does not list pdf-to-markdown. Word-to-Markdown and the generic MarkItDown document tools stay on the free web pages. The API docs marketing line mentions PDF and Markdown together because OCR accepts PDF uploads and can return Markdown-shaped text from the notes tool. That is not the same pipeline as the MarkItDown browser converter.

Practical rule:

• Digital PDF you would convert once in a browser → PDF to Markdown.
• Photo or PDF of notes you want structured Markdown from software → OCR API with tool=notes-to-markdown.
• Receipts, forms, handwriting, screenshots → matching OCR tool slugs from the docs tool list.

Do not invent endpoints. If a tool slug is missing from the allowed list, the API returns 400 with unknown_tool and an allowed array. Trust that list over blog memory.

PDF uploads on the OCR path process the first twelve pages. Longer files get a truncation note in the text. Max file size is eight megabytes. Timeout is up to sixty seconds per request.

Get a key and understand quotas

Create an account, open the account API section, and copy a key that looks like tsy_…. Store it in an environment variable such as TOOLSY_API_KEY. Rotate it if it leaks.

Quota is monthly and plan-based. Free: forty recognitions. Dedicated plans on pricing: API Starter five hundred, Growth three thousand, Scale fifteen thousand. Response JSON includes a usage object with used, quota, remaining, plan, and month. Headers expose X-RateLimit-Limit, X-RateLimit-Used, and X-RateLimit-Remaining. Rate limit is sixty requests per minute per key. Over that, you get 429 with rate_limited and Retry-After: 60. Exhausted monthly quota returns 429 with quota_exceeded.

OCR API usage is not the same meter as SEO research credits on Plus. Do not mix those billing stories. API plans and the free sandbox are the numbers that matter for this guide. Details and contact for higher volume sit on pricing and API docs.

Call the OCR API for Markdown-shaped output

One endpoint. Send the key. Pick a real tool. Attach a file. Read text on HTTP 200.

Base call shape from the live docs:

POST https://toolsy.tools/api/v1/ocr
Authorization: Bearer YOUR_KEY

Multipart fields: file (image or PDF) and tool. JSON body alternative: tool, image_base64, optional mime and filename.

Multipart form upload

This is the default for servers that already hold a temp file. Set tool to a value from the docs list. For Markdown structure from notes pages, use notes-to-markdown.

curl -X POST https://toolsy.tools/api/v1/ocr \
  -H "Authorization: Bearer $TOOLSY_API_KEY" \
  -F "tool=notes-to-markdown" \
  -F "file=@notes.pdf"

On success, parse JSON and take text. On failure, read the error string and map it with the table on the docs page.

JSON with base64

Use JSON when your platform prefers base64 (some serverless or Apps Script setups). Strip any data: prefix from the base64 string. Set mime to match the bytes (application/pdf or image/jpeg).

Keep payloads under the eight megabyte file limit after decoding. Giant base64 strings still count against size and timeout.

Python requests example

Search volume for “pdf to markdown python” is higher than the bare API phrase, so many readers will start here. The sample matches the docs Python snippet pattern, swapped to the Markdown notes tool and a PDF path:

import os
import requests

r = requests.post(
    "https://toolsy.tools/api/v1/ocr",
    headers={"Authorization": f"Bearer {os.environ['TOOLSY_API_KEY']}"},
    files={"file": open("notes.pdf", "rb")},
    data={"tool": "notes-to-markdown"},
    timeout=60,
)
r.raise_for_status()
payload = r.json()
print(payload["text"])
print("remaining:", r.headers.get("X-RateLimit-Remaining"))

Pin your own retry policy for 502 / 503. Do not hammer 429; honor Retry-After. For MarkItDown as a local library instead of HTTP, read MarkItDown explained and keep files on your machine.

Limits, errors, and what to check in the response

Limits protect shared capacity. Design around them instead of discovering them in production.

Size, pages, rate, and timeout

• Formats: JPG, PNG, WebP, GIF, PDF.
• Max size: 8 MB per OCR request.
• PDF: first 12 pages processed.
• Timeout: up to 60 seconds.
• Rate: 60 requests per minute per key.

If you need MarkItDown conversion of a clean digital PDF larger than the OCR story, use the browser tool with Pro size limits, or convert locally. Do not assume the OCR endpoint silently behaves like the MarkItDown web converter.

Error codes you will actually see

Body is JSON with an error field. Common codes from the live docs:

HTTP	error	What you do
401	invalid_api_key	Fix Bearer key or create a new one
400	unknown_tool	Wrong slug; read allowed
400	file_required	Missing file or image_base64
400	file_too_large	Shrink under 8 MB
429	rate_limited	Wait Retry-After seconds
429	quota_exceeded	Upgrade plan or wait for month reset
502	ocr_failed	Retry later
503	ocr_unavailable	Service down; check status

Success returns text, the tool you sent, and usage. Table tools return CSV inside text. Forms may return JSON as a string. For notes-to-markdown, expect Markdown headings and lists when the page layout is visible. Spot-check names, numbers, and [?] placeholders before you index the string.

Privacy, credits honesty, and when to stay local

Uploads for OCR and document conversion are processed for the request and designed to be discarded shortly afterward, typically within about one hour. Toolsy does not use your uploads to train its own models. OCR and certain AI features send content through the AI gateway so the model can produce text. API request logs may store key id, status, and timing, not the full document body. The binding text is the Privacy Policy. Plain-language retention sits in what happens to files after processing.

Credits honesty: free OCR API sandbox is forty recognitions per month. Pro and Plus trial quota is one hundred. Dedicated API plans are priced on the pricing page. Browser MarkItDown tools use a separate free daily file quota. SEO research credits on Plus are a different product. Quote the meter that matches the call you make.

Stay local when policy forbids third-party processing, when you need full-document MarkItDown fidelity under your own lockfile, or when volume would blow a freemium quota. Marker and Microsoft MarkItDown remain valid local stacks; Toolsy is not those GitHub repos.

Soft note on batching

Nightly folders and high-volume OCR loops need queueing, backoff, and quota math. A full comparison of batch API use versus manual browser uploads is planned as its own piece later. Treat this section as a boundary, not the playbook.

For now, keep concurrency polite, stay under sixty requests per minute, and watch usage.remaining after every call. Burst traffic without backoff burns the free sandbox and then your paid plan for little gain.

If your corpus is RAG-bound, convert a sample, fix headings, then scale. The prep order in prepare documents for RAG with Markdown still applies whether the bytes arrived from curl or a browser download.

Frequently asked questions

Is there a Toolsy PDF to Markdown API endpoint?

There is a public OCR API at POST /api/v1/ocr, documented on API docs. There is no separate tool=pdf-to-markdown value in the live tool enum. For Markdown-shaped OCR output, use notes-to-markdown with an image or PDF under the OCR limits. For MarkItDown-style PDF conversion in a browser, use PDF to Markdown.

How do I call a PDF to Markdown API from Python?

Create a key, set TOOLSY_API_KEY, and POST multipart to /api/v1/ocr with tool and file as in the sample above. Parse text from the JSON body and log X-RateLimit-Remaining. If you need the Microsoft MarkItDown library on your laptop instead of HTTP, that is a local install path covered in the MarkItDown guide, not a Toolsy Python package name.

Does the free plan include API access?

Yes. After sign-up you get forty OCR recognitions per month without a card. Pro and Plus include one hundred per month as trial quota. Higher monthly caps need a dedicated API plan listed on pricing. Browser MarkItDown conversion uses a different free daily file allowance.

Can I convert PDF to Markdown online without an API key?

Yes. Open PDF to Markdown, upload a file within the size limit, and download the .md. That path fits one-offs and human review. It does not replace a server-side key when software must automate recognition.

What file size and page limits apply on the OCR API?

OCR requests allow JPG, PNG, WebP, GIF, or PDF up to eight megabytes. PDFs process the first twelve pages; longer files include a truncation note. Timeout is up to sixty seconds. Rate limit is sixty requests per minute per key. Exceeding size returns file_too_large.

Is Toolsy the same as Microsoft MarkItDown or Marker?

No. Toolsy offers online conversion in the MarkItDown workflow family and a separate OCR API. It is not the microsoft/markitdown or datalab-to/marker repositories. For an honest three-way comparison, read Marker vs MarkItDown vs online converters.

Where do API keys live, and can I use them in the browser?

Keys live in your account after sign-up. Keep them on a backend, in a secret store, or in an automation tool’s credential vault. Public front-end code would expose the key and burn your quota. Docs snippets that show browser JavaScript are for teaching request shape behind a proxy, not for shipping secrets to visitors.

What happens to files after an API or browser conversion?

Toolsy processes the upload for the job, returns the result, and designs uploads to be discarded shortly afterward, typically within about one hour. Operational logs may keep non-content metadata. Full retention language is in the Privacy Policy and the files after processing article. Do not upload content you are not allowed to process.

How is API quota different from SEO credits?

OCR API quota counts recognitions for /api/v1/ocr and embed widgets that share that meter. SEO research credits on Plus fund keyword and SERP tools. Mixing the two in a budget spreadsheet creates false alarms. Check the usage object on OCR responses for the recognition meter.

Should I batch hundreds of PDFs through the API today?

You can script sequential or lightly parallel calls if you respect rate limits and monthly quota. Large batch design, failure queues, and browser-versus-API cost tradeoffs deserve a dedicated batch article later. Start with a small sample set, verify Markdown quality, then scale. For MarkItDown one-offs while you test quality, keep using PDF to Markdown.

For MarkItDown definition depth, continue with MarkItDown explained. For RAG ingestion order, use prepare documents for RAG with Markdown. For local versus online converter choice, see Marker vs MarkItDown vs online. When privacy is the gate, read what happens to files after processing. For enterprise OCR API shopping, see Nanonets vs self-serve OCR API. For API, widget, and fixture workflows in one map, see Developer integrations: complete guide. Wire the first key from API docs.