---
title: "Convert Markdown to HTML"
description: "POST https://api.markitdown.ai/v1/convert/markdown/html — Convert Markdown to HTML. Costs 0 credits."
url: https://markitdown.ai/docs/api/convert-markdown-html
updated: 2026-09-26
source: markitdown.ai
---

# Convert Markdown to HTML

> POST https://api.markitdown.ai/v1/convert/markdown/html — Convert Markdown to HTML. Costs 0 credits.

## Endpoint

**POST** `/v1/convert/markdown/html` — Convert Markdown to HTML

Accepted inputs: multipart file, text/texts, file/files (reference). Options: store, metadata.

> **Note:** Send an Idempotency-Key header so a retried request replays the original conversion instead of creating a second one.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header · string | no |  |
| `Prefer` | header · string | no |  |
| `wait` | query · integer | no |  |

## Request body

`application/json` — object (required).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string | no | A `file_…` id from an earlier conversion. |
| `files` | string[] | no | Several `file_…` ids. |
| `metadata` | object | no | Your own data, returned unchanged. |
| `store` | boolean | no | Keep the result in the account library. |
| `text` | string | no | The content to convert. |
| `texts` | string[] | no | Several contents, one source each. |
| `upload` | string | no | An `upl_…` id of a completed chunked upload. |
| `uploads` | string[] | no | Several `upl_…` ids. |

`multipart/form-data` — object (required).

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string (binary) | yes | One of .md. |
| `metadata` | object | no | Your own data, returned unchanged. |
| `store` | boolean | no | Keep the result in the account library. |

## Example request

**curl**

```bash
curl -X POST https://api.markitdown.ai/v1/convert/markdown/html \
  -H "x-api-key: $MARKITDOWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file": "string" }'
```

## Responses

- `200` Conversion finished within the wait window. (`application/json`) — `Conversion`
- `202` Conversion still in progress. (`application/json`) — `Conversion`
- `400` Invalid request (`application/problem+json`) — `Problem`
- `402` Insufficient credits (`application/problem+json`) — `Problem`
- `403` Upload limit exceeded (`application/problem+json`) — `Problem`
- `404` Not found (`application/problem+json`) — `Problem`
- `409` Upload not completed (`application/problem+json`) — `Problem`
- `410` File expired (`application/problem+json`) — `Problem`
- `413` Upload too large (`application/problem+json`) — `Problem`
- `415` Input format mismatch (`application/problem+json`) — `Problem`
- `422` Page cap exceeded (`application/problem+json`) — `Problem`
- `429` Concurrency limited (`application/problem+json`) — `Problem`
- `503` Parser unavailable (`application/problem+json`) — `Problem`

**200 body — Conversion**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `async_reason` | "respond_async" \| "too_many_sources" \| "pages_exceed_sync_limit" \| "capacity" \| "wait_timeout" \| null | no |  |
| `completed_at` | string (date-time) \| null | no |  |
| `created_at` | string (date-time) | yes |  |
| `files` | object[] | no |  |
| `files[].bytes` | integer \| null | no |  |
| `files[].content` | string \| null | no |  |
| `files[].credits` | integer \| null | no |  |
| `files[].error` | object \| any \| null | no |  |
| `files[].format` | "markdown" \| "text" \| "html" \| "pages" | no |  |
| `files[].id` | string | yes |  |
| `files[].links` | object | no |  |
| `files[].mime` | string | yes |  |
| `files[].name` | string | yes |  |
| `files[].object` | "file" | yes |  |
| `files[].outputs` | object[] | no |  |
| `files[].pages` | integer \| null | no |  |
| `files[].role` | "source" \| "output" | yes |  |
| `files[].status` | "queued" \| "running" \| "completed" \| "failed" | no |  |
| `files[].variant` | "standard" \| "ai_enhanced" | no |  |
| `files_next_cursor` | string \| null | no |  |
| `id` | string | yes |  |
| `links` | object | no |  |
| `metadata` | any | no |  |
| `name` | string | yes |  |
| `object` | "conversion" | yes |  |
| `operation` | "parse" \| "render" | yes |  |
| `status` | "queued" \| "running" \| "completed" \| "completed_with_errors" \| "failed" | yes |  |
| `summary` | object | yes |  |
| `summary.completed` | integer | no |  |
| `summary.failed` | integer | no |  |
| `summary.queued` | integer | no |  |
| `summary.running` | integer | no |  |
| `summary.sources` | integer | no |  |
| `usage` | object | yes |  |
| `usage.credits_charged` | integer | no |  |
| `usage.credits_remaining` | integer \| null | no |  |
| `usage.credits_reserved` | integer | no |  |

## Errors

- [Error codes](/docs/errors) — every `error` code with its status, meaning and whether to retry

## Related

- [API reference](https://markitdown.ai/docs/api)
- [Error codes](https://markitdown.ai/docs/errors)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)