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

# Import Markdown via REST API

Learn how to import Markdown files into Tiptap JSON 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 import API converts `.md` files into Tiptap JSON format.

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

## Import Markdown

`POST /v2/convert/import/markdown`

The `/v2/convert/import/markdown` endpoint converts Markdown files (`.md` or `.markdown`) into Tiptap's JSON format. Upload a file using `multipart/form-data`.

### Example (cURL)

```bash
curl -X POST "https://api.tiptap.dev/v2/convert/import/markdown" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -F "file=@/path/to/file.md"
```

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

### Body

| Name      | Type     | Required | Description                                               |
| --------- | -------- | -------- | --------------------------------------------------------- |
| `file`    | `File`   | Yes      | The Markdown file to convert (`.md` or `.markdown`)       |
| `verbose` | `string` | No       | Logging verbosity level (bitmask: 1=log, 2=warn, 4=error) |

### Response (200 OK)

```json
{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Hello from Markdown!"
            }
          ]
        }
      ]
    }
  },
  "logs": {
    "info": [],
    "warn": [],
    "error": []
  }
}
```

### Error responses

| Status | Code                                        | Description                        |
| ------ | ------------------------------------------- | ---------------------------------- |
| 400    | `NO_FILE_PROVIDED`                          | No file was provided               |
| 400    | `INVALID_FILE_TYPE`                         | File is not `.md` or `.markdown`   |
| 422    | `FAILED_TO_GET_FILE_ARRAY_BUFFER`           | Failed to read file buffer         |
| 500    | `FAILED_TO_CONVERT_MARKDOWN_TO_TIPTAP_JSON` | Failed to convert Markdown to JSON |

## Support & Limitations

Markdown import parses Markdown text into Tiptap JSON via the v2 cloud API. The endpoint supports standard CommonMark and GFM tables. Custom syntaxes used by optional Tiptap extensions (underline, highlight, math) are not parsed by the import service and won't appear in the returned JSON.

| **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                                    |
| **Underline**             | ✗ Custom `++text++` syntax not registered on the server             |
| **Highlight**             | ✗ Custom `==text==` syntax not registered on the server             |
| **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**                  | ✗ `$...$` syntax not registered on the server                       |
| **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.