---
title: "Convert Markdown via REST API (Legacy)"
description: "Learn how to handle Markdown files via the legacy REST API for Tiptap conversion."
canonical_url: "https://tiptap.dev/docs/conversion/legacy/markdown/rest-api"
---

# Convert Markdown via REST API (Legacy)

Learn how to handle Markdown files via the legacy REST API for Tiptap conversion.

> **Legacy Markdown REST API (Deprecated):**
>
> This REST API is deprecated and will be sunset at some point in 2026 with prior communication from the team. For new integrations, use the updated [Markdown export REST API](https://tiptap.dev/docs/conversion/export/markdown/rest-api.md) and [Markdown import REST API](https://tiptap.dev/docs/conversion/import/markdown/rest-api.md).

- **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**

  In case you want to integrate the REST API retrieve your App ID and Convert secret from [your dashboard](https://cloud.tiptap.dev/v2/cloud/convert).
- **3. Install from private registry**

  To install the frontend extensions, authenticate to Tiptap's private npm registry by following the [setup guide](https://tiptap.dev/docs/guides/pro-extensions.md).

> **Use Postman:**
>
>  Experiment with the Conversion API in our 
>
> Postman collection
>
> . 

## Import API endpoint

`POST /import`

Converts .md files (or gfm) to Tiptap JSON.

```bash
curl -X POST "https://api.tiptap.dev/v1/convert/import?format=md" \
  -H "Authorization: Bearer <your-jwt>" \
  -H "X-App-Id: <your-app-id>" \
  -F "file=@/path/to/file.md"
```

### Import API Headers

| Header          | Description                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `Authorization` | `Bearer <your-jwt>`                                                                                        |
| `X-App-Id`      | Convert App ID from [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

### Import API Fields

| Field                    | Description                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `file`                   | The Markdown file to convert                                                       |
| `imageUploadCallbackUrl` | Optional endpoint for handling images if the Markdown file references local images |

## Export API endpoint

`POST /export`

Converts Tiptap JSON to .md or .gfm.

```bash
curl -X POST "https://api.tiptap.dev/v1/convert/export" \
  -H "Authorization: Bearer <your-jwt>" \
  -H "X-App-Id: <your-app-id>" \
  -F 'prosemirrorJson={"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Hello from Tiptap!"}]}]}' \
  -F 'to=md' \
  --output document.md
```

#### Export API Headers

| Header          | Description                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `Authorization` | `Bearer <your-jwt>`                                                                                        |
| `X-App-Id`      | Convert App ID from [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### Export API Fields

| Field             | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `prosemirrorJson` | Tiptap/ProseMirror JSON                                   |
| `to`              | Target format, `md` or `gfm` for GitHub Flavored Markdown |