canonical: https://jentic.com/apis/mdtidy.com/mdtidy

# Mdtidy Markdown Tidy API

The Markdown Tidy API cleans, repairs, and converts markdown into HTML, plain text, PDF, DOCX, or PNG in a single call, styled with a built-in design system such as minimal-clean, executive-report, or developer-docs. Page settings control paper size, orientation, margins, and font scale at no extra credit cost, and each successful render debits 1 credit with failed renders refunded automatically. Alongside conversion, workspace routes store markdown in projects, folders, and versioned files, and share a project through a public link or invited viewers.

## For AI agents

Convert messy markdown into clean HTML, text, PDF, DOCX, or PNG with a chosen design system, check credit balance, and store and share markdown files in Markdown Tidy projects.

## Scope

Does not handle general office file conversion, PDF editing, or website hosting. Use for cleaning and rendering markdown and storing markdown projects only.

## Capabilities

- Convert markdown up to 1 MB into html, text, pdf, docx, or png with one convert call, repairing and cleaning it on the way
- Style output with a designSystem such as minimal-clean, executive-report, or developer-docs and set page geometry and font scale
- Read the caller's credit balance and recent usage before running a batch of renders
- Organise markdown into projects and folders, and save files with an Idempotency-Key so a retried save does not charge twice
- Update a file with If-Match and its version to avoid overwriting a newer edit, or copy it as a new file
- Share a project through a public link or invite viewers by email, and make it private again

## Use cases

### Agent-generated documents through Jentic

Agents write markdown naturally, but people want PDFs and Word files. Through Jentic an agent can send its markdown to the convert operation with format set to pdf or docx and a designSystem such as executive-report, and get a cleaned, repaired, styled document back. Failed renders are refunded, so a retry after a bad input costs nothing extra.

Example prompt: Send the weekly status report markdown to the convert operation with format pdf and designSystem executive-report, then return the rendered PDF to the user

### Repairing markdown from mixed sources

Markdown pasted from chat tools, LLM output, or exported wikis often has broken lists, stray characters, and inconsistent headings. The convert pipeline cleans and repairs it before rendering, so the same call can return tidy HTML for a web page or plain text for an email body.

Example prompt: Convert a pasted markdown snippet with format html using the minimal-clean design system and return the HTML for publishing

### Stored and shared markdown projects

Teams keeping documentation as markdown can store it in Markdown Tidy projects with folders and versioned files. Saves accept an Idempotency-Key to stay safe on retry, updates use If-Match with the file version to avoid clobbering edits, and a project can be published through a public link or shared with invited viewers.

Example prompt: Create a project named Onboarding Docs, create a file named welcome.md in it with the draft content, then enable the project's public link and return it

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/convert` | Clean, repair, and convert markdown |
| GET | `/api/v1/usage` | Read credit balance and recent usage |
| POST | `/api/v1/projects` | Create a project |
| POST | `/api/v1/files` | Create a file |
| PATCH | `/api/v1/files/{id}` | Update, move, or archive a file |
| POST | `/api/v1/projects/{id}/share/public` | Turn on the public link |

## Key resources

- **Convert** — Clean, repair, and render markdown to HTML, text, PDF, DOCX, or PNG.
- **Usage and credits** — Read credit balance, recent usage, and workspace entitlement.
- **Projects and folders** — Create, list, rename, archive, and delete projects and their folders.
- **Files** — Create, read, update, copy, and delete versioned markdown files.
- **Sharing** — Manage public links, invited viewers, and private mode for a project.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 72 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 46 / 100
  - Agent Usability: 94 / 100
  - Security: 55 / 100
  - AI Discoverability: 72 / 100
- **View full report:** https://jentic.com/apis/mdtidy.com/mdtidy/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Markdown Tidy by hand means sending its key as X-API-KEY on conversion routes but as a bearer token on workspace routes, plus handling Idempotency-Key and If-Match headers on saves. Through Jentic you install once, import Markdown Tidy from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Markdown Tidy puts project, folder, and file ids in the URL path (`/api/v1/projects/{id}`, `/api/v1/files/{id}`), so a rule can pin your agent to one project and the operations you pick. You choose the operations it may call, so destructive ones like deleting a project or regenerating a public link are not included unless you add them.
- **Credential handling:** Your Markdown Tidy key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert markdown to PDF' or 'share a project link', and Jentic returns the matching Markdown Tidy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **CloudConvert** — General file conversion across hundreds of formats, without markdown cleanup or design systems.
- **ConvertAPI** — Document conversion API covering office, PDF, and image formats.
- **PDFMonkey** — Generates PDFs from HTML templates filled with JSON data.
- **Google Drive API** — Stores and shares files, such as rendered PDFs and DOCX outputs.

## FAQ

### What authentication does the Markdown Tidy API use?

Per its OpenAPI spec, the convert and usage routes take a dashboard-issued key in the X-API-KEY header, and the workspace routes for credits, projects, folders, files, and sharing accept the same key as an Authorization: Bearer token. Keys starting mt_test_ are for the sandbox and mt_live_ for production. Through Jentic the key is stored encrypted on your own instance and injected at call time.

### Is there a Markdown Tidy MCP server?

You don't need an MCP server to give your agent Markdown Tidy. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are discovered on demand, so no extra server's tool definitions take up your agent's context.

### Can I limit what my agent is allowed to do with the Markdown Tidy API?

Yes. For a report-writing agent, write a rule that allows only POST `/api/v1/convert` and GET `/api/v1/usage`, so it can render documents and check its credit balance but cannot touch stored projects, delete files, or publish public links. Every call it makes is logged.

### What does a Markdown Tidy conversion cost?

Each successful render through the convert operation debits 1 credit from your wallet, and failed renders are refunded automatically. Page geometry and font scale settings carry no extra cost. Creating or copying a file and each viewer-invite call also charge 1 credit, enabling a public link costs 1 credit unless it falls within the 30-day slug grace, and removing invitees and disabling links are free.

### What are the rate limits for the Markdown Tidy API?

The OpenAPI spec does not specify rate limits; check https://mdtidy.com for current limits. Spend is bounded by your credit balance, which GET `/api/v1/usage` reports.

### How do I convert markdown to PDF with Markdown Tidy through Jentic?

Search Jentic for an intent like 'convert markdown to PDF', import the Markdown Tidy API, and store your key once. Your agent then calls POST `/api/v1/convert` with the markdown and format set to pdf. To run it on your own infrastructure, install Jentic One from its GitHub repo.