---
title: "Export Markdown via REST API"
description: "Learn how to export Tiptap JSON documents to Markdown format using the Tiptap Conversion REST API v2."
canonical_url: "https://tiptap.dev/docs/conversion/export/markdown/rest-api"
---

# Export Markdown via REST API

Learn how to export Tiptap JSON documents to Markdown format using the Tiptap Conversion REST API v2.

- **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start plan](https://cloud.tiptap.dev/v2/billing) in your account.
- **2. Configure Convert app**

  To use the Convert REST API retrieve your App ID and Convert secret from [your dashboard](https://cloud.tiptap.dev/v2/cloud/convert).

The Markdown export API converts Tiptap JSON documents into Markdown files.

> **Review the postman collection:**
>
> You can also experiment with the Document Conversion API by heading over to our [Postman
> Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60).

## Export Markdown

`POST /v2/convert/export/markdown`

The `/v2/convert/export/markdown` endpoint converts Tiptap JSON documents into Markdown format. Send a `POST` request with your document as a JSON body to receive a downloadable Markdown file.

### Example (cURL)

```bash
curl --output document.md -X POST "https://api.tiptap.dev/v2/convert/export/markdown" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello from Tiptap!\"}]}]}"
    }'
```

> **Subscription required:**
>
> This endpoint requires a valid Tiptap subscription. For more details review our [pricing page](https://tiptap.dev/pricing).

### Required headers

| Name            | Description                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | The JWT token to authenticate the request. Example: `Bearer your-jwt-token`                                                               |
| `X-App-Id`      | The Convert App-ID from the Convert settings page: [https://cloud.tiptap.dev/v2/cloud/convert](https://cloud.tiptap.dev/v2/cloud/convert) |
| `Content-Type`  | Must be `application/json`                                                                                                                |

### Body

| Name  | Type     | Description                      | Required |
| ----- | -------- | -------------------------------- | -------- |
| `doc` | `String` | Tiptap JSON document as a string | Yes      |

### Response

On success the API returns the Markdown file as a text download:

- **Status**: `200 OK`
- **Content-Type**: `text/markdown; charset=utf-8`
- **Content-Disposition**: `attachment; filename=export-{timestamp}.md`

### Error responses

| Status | Code                            | Description                          |
| ------ | ------------------------------- | ------------------------------------ |
| 400    | `NO_DOCUMENT_PROVIDED`          | No document was provided in the body |
| 422    | `FAILED_TO_PARSE_JSON_INPUT`    | Failed to parse JSON inputs          |
| 422    | `FAILED_TO_PARSE_MARKDOWN_FILE` | Failed to export Markdown            |

## Support & Limitations

The REST API uses the same Markdown conversion as the editor extension, so the supported feature set is identical. Markdown export converts Tiptap content to CommonMark-compatible Markdown. Unlike DOCX, Markdown has no concept of rich styling, page layout, or complex table formatting.

| **Feature**               | **Support**                                                             |
| ------------------------- | ----------------------------------------------------------------------- |
| **Text content**          | ✓ Paragraphs, headings (1–6), hard breaks                               |
| **Inline formatting**     | ✓ Bold, italic, strikethrough, inline code                              |
| **Block elements**        | ✓ Blockquotes, code blocks (fenced with language), horizontal rules     |
| **Lists**                 | ✓ Bullet lists, ordered lists, task lists, nested lists                 |
| **Tables**                | ✓ Basic pipe-syntax tables (single header row, no merged cells)         |
| **Links**                 | ✓ Hyperlinks with text and URL                                          |
| **Images**                | ✓ Image references with alt text (no dimensions)                        |
| **Underline**             | ✓ Custom syntax (`++text++`, non-standard)                              |
| **Highlight**             | ✓ Custom syntax (`==text==`, non-standard)                              |
| **Text color / Font**     | ✗ No Markdown syntax for colors, font family, or font size              |
| **Text alignment**        | ✗ No Markdown syntax                                                    |
| **Spacing / Indentation** | ✗ No Markdown syntax                                                    |
| **Merged cells**          | ✗ Markdown tables don't support colspan or rowspan                      |
| **Headers & Footers**     | ✗ No concept in Markdown                                                |
| **Page layout**           | ✗ No page breaks, sections, or page size                                |
| **Math**                  | \~ Extension-dependent (`$...$` syntax if math extension is configured) |
| **Footnotes & Endnotes**  | ✗ Not supported in CommonMark                                           |

For the full DOCX feature comparison, see the [Supported features](https://tiptap.dev/docs/conversion/getting-started/feature-support-matrix.md) matrix.