Developer integrations: complete guide to OCR API, widgets, and Markdown pipelines

Developers land on Toolsy when a one-off upload stops scaling. A folder of PDFs needs Markdown for RAG. A site needs handwriting capture without building OCR. A CI job needs a keyed HTTP call. This hub maps browser conversion, the OCR API, and the embed widget so you pick the right surface first. It is not an OpenAPI dump. Start at API docs for keys and POST /api/v1/ocr, or Widget for embed snippets. For interactive files, keep PDF to Markdown and Convert to Markdown. Free API sandbox after sign-up is about 40 recognitions per month. Browser MarkItDown quotas are a separate daily counter. Production OCR volume needs an API plan on pricing.

Who this developer integrations hub is for

This index fits backend engineers, indie hackers, and agency techs wiring document intake. Product managers who only convert three PDFs a week should stay on the browser tools and skip API billing.

If your pipeline is Markdown-first for models, keep Markdown for AI: complete guide open beside this hub. Chunking after conversion still follows Prepare documents for RAG with Markdown. Privacy reviews belong in Privacy and document safety: complete guide.

Decision tree: browser, API, or widget

Name the caller before you create a key. A human in a tab is not the same as a server cron.

Your goal	Start here	Deep guide
One-off PDF → Markdown in a browser	PDF to Markdown	MarkItDown CLI vs browser converter
Keyed HTTP OCR / Markdown-shaped OCR	API docs	PDF to Markdown API for developers
Embed capture on your site	Widget	Embed OCR widget on your site
Compare to vertical OCR vendors	API docs	Nanonets vs self-serve OCR API
RAG / LLM document prep	Convert to Markdown	Markdown for AI: complete guide
ID strategy for fixtures	UUID generator	UUID v4 vs v7 for databases
Spreadsheet → JSON mocks	CSV to JSON	CSV to JSON for API mocks
Handwriting intake product	Handwriting to text	Handwriting OCR: complete guide
Upload trust for client files	API docs	Is it safe to upload documents online?
Retention after processing	Privacy Policy	What happens to files after processing?
CLI vs hosted MarkItDown	PDF to Markdown	MarkItDown CLI vs browser converter
Vendor bake-off notes	API docs	Nanonets vs self-serve OCR API

When two rows match, choose the caller: human → browser; your backend → API; end-user on your domain → widget.

OCR API keys, quotas, and call shape

The developer path is documented at API docs. You create a key in your account and send Authorization: Bearer YOUR_KEY to POST https://toolsy.tools/api/v1/ocr with a live tool value and an image or PDF. There is no invent-your-own pdf-to-markdown API slug; Markdown-shaped OCR uses documented tool names such as notes-to-markdown. Details and honesty live in PDF to Markdown API for developers.

Free sandbox after sign-up is about forty recognitions per month with no card. Pro and Plus include a trial monthly OCR quota. Steady production traffic needs a dedicated API plan. Browser MarkItDown daily caps are not the same counter.

When the browser converter is enough

Three PDFs this week do not need a key. Use PDF to Markdown. Free MarkItDown quotas are small (on the order of three files per day with a modest size cap); Pro raises size and removes the daily file cap. Read MarkItDown CLI vs browser converter when you debate local scripts vs hosted clicks. For ChatGPT upload vs Markdown-first tradeoffs on the same files, see ChatGPT PDF upload vs Markdown-first.

Self-serve vs vertical OCR platforms

Nanonets vs self-serve OCR API compares enterprise workflow UIs with a keyed self-serve endpoint. Pick Nanonets-style platforms when you need human-in-the-loop labeling products. Pick self-serve when you already own the UI and only need recognition.

Embed widgets for third-party sites

Widget covers embed snippets so your users upload on your domain while Toolsy runs recognition. Walk Embed OCR widget on your site for keys, domains, and UX notes. Widgets still consume recognition quota. They do not bypass privacy review for medical or legal uploads.

Test the happy path and the limit-exceeded path before you ship. Show a clear error when the monthly quota ends mid-demo.

Markdown pipelines, fixtures, and IDs

API intake is only half of a developer week. You still need clean Markdown for chunking, JSON fixtures for mocks, and stable IDs for rows.

RAG and AI document prep

Markdown for AI: complete guide indexes conversion and chunking posts. Pair API OCR output with the same heading hygiene you use for browser exports. Do not dump raw OCR into a vector index without a QA pass.

Mocks and identifiers

CSV to JSON for API mocks covers spreadsheet → fixture arrays. UUID v4 vs v7 for databases helps when mock rows need sortable IDs. These tools are browser-side utilities; they do not replace the OCR API.

Privacy, processors, and client data

OCR and some AI paths may send content to external model providers for that request. Toolsy designs uploads to be discarded after processing (typically within about an hour) and does not use uploads to train its own models. Legal detail sits in the Privacy Policy.

Read Is it safe to upload documents online? and What happens to files after processing? before you point a production bucket at the API. Handwriting workflows with sensitive scans also belong under Handwriting OCR: complete guide and the privacy hub.

Limits and when not to integrate yet

Skip the API when volume is manual and rare. Skip the widget when you only need an internal admin tool. Skip inventing SDK wrappers on day one; Toolsy documents one HTTP endpoint with samples, not a separate multi-language SDK.

Rate limits and monthly caps will 429 you in production if you ignore them. Put retries and user-visible quota errors in your client before launch day.

Frequently asked questions

What developer integration should I build first?

If a human uploads occasionally, use the browser converter. If software uploads on a schedule, use the OCR API at API docs. If end users upload on your domain, use Widget. The decision tree above spells out the deep guides for each path.

Is there a dedicated PDF to Markdown API slug on Toolsy?

Not as a separate invent-your-own route name. You call POST /api/v1/ocr with a Bearer key and a documented tool value. Markdown-shaped recognition uses tools such as notes-to-markdown. See PDF to Markdown API for developers for the real call shape.

How many free API recognitions do I get?

After sign-up, the sandbox is about 40 recognitions per month with no card. Pro and Plus include trial monthly OCR quota. Heavy production needs an API plan on pricing. Browser MarkItDown daily limits are separate and do not top up API quota.

Do I need an SDK to call the OCR API?

No separate SDK is required. Use HTTPS with a Bearer token and the documented JSON fields. Snippets live on API docs. Platform embed notes live on Widget.

When should I embed the OCR widget instead of calling the API myself?

Embed when your end users must upload in your UI without you proxying every byte through your backend on day one. Call the API yourself when you already own storage, auth, and retry logic. Walk Embed OCR widget on your site before you paste the snippet in production.

How does Toolsy compare to Nanonets for OCR APIs?

Nanonets-style platforms win on vertical workflows and labeling products. Self-serve Toolsy wins when you want a keyed endpoint and you already own the product UI. Read Nanonets vs self-serve OCR API for an honest split.

Is MarkItDown CLI better than the browser converter?

CLI wins for repeatable local folders and scripts. Browser wins for ad hoc files and non-developer teammates. Compare in MarkItDown CLI vs browser converter. Neither replaces a keyed API for server-side intake.

What happens to files I send to the API?

Uploads are processed for the request and designed to be discarded afterward (typically within about an hour). OCR may involve external model providers for that job. Read What happens to files after processing? and the Privacy Policy before shipping client data.

Can I use CSV to JSON and UUID tools with the same account?

Yes. Those utilities are separate browser tools for fixtures and IDs. They do not consume OCR recognitions. See CSV to JSON for API mocks and UUID v4 vs v7 for databases.

Where do Markdown-for-AI guides fit with the API?

API output is still text you must chunk and QA. Use Markdown for AI: complete guide for pipeline design after recognition succeeds. Bad OCR into a vector index becomes confident nonsense in chat.

For implementation detail, keep PDF to Markdown API for developers and Embed OCR widget on your site next to this hub.