Document conversion API
Beta
This feature is currently in beta and available to all users with a Tiptap account.
The document conversion API supports DOCX, ODT, and Markdown conversion from and to Tiptap’s JSON format.
The following demo uses the Document Conversion API by integrating both the import and export extensions into the editor.
Review the postman collection
You can also experiment with the Document Conversion API by heading over to our Postman Collection.
Integrate into the editor
Tiptap offers editor extensions for importing and exporting documents. These extensions provide full access to the Document Conversion API. Instead of using the Document Conversion API directly, you can use Tiptap Editor's import and export extensions:
/import endpoint
The /import endpoint enables the conversion of docx, odt, or markdown files into Tiptap’s JSON format. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.
- Method:
POST
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 Collaboration settings page: https://cloud.tiptap.dev/convert-settings |
Body
| Name | Type | Description |
|---|---|---|
file | File | The file to convert |
Query parameters
Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.
| Name | Default | Description |
|---|---|---|
paragraph | paragraph | Defines which prosemirror type is used for paragraph conversion |
heading | heading | Defines which prosemirror type is used for heading conversion |
blockquote | blockquote | Defines which prosemirror type is used for blockquote conversion |
codeblock | codeblock | Defines which prosemirror type is used for codeblock conversion |
bulletlist | bulletlist | Defines which prosemirror type is used for bulletList conversion |
orderedlist | orderedlist | Defines which prosemirror type is used for orderedList conversion |
listitem | listitem | Defines which prosemirror type is used for listItem conversion |
hardbreak | hardbreak | Defines which prosemirror type is used for hardbreak conversion |
horizontalrule | horizontalrule | Defines which prosemirror type is used for horizontalRule conversion |
table | table | Defines which prosemirror type is used for table conversion |
tablecell | tablecell | Defines which prosemirror type is used for tableCell conversion |
tableheader | tableheader | Defines which prosemirror type is used for tableHeader conversion |
tablerow | tablerow | Defines which prosemirror type is used for tableRow conversion |
bold | bold | Defines which prosemirror mark is used for bold conversion |
italic | italic | Defines which prosemirror mark is used for italic conversion |
underline | underline | Defines which prosemirror mark is used for underline conversion |
strikethrough | strike | Defines which prosemirror mark is used for strikethrough conversion |
link | link | Defines which prosemirror mark is used for link conversion |
code | code | Defines which prosemirror mark is used for code conversion |
/export endpoint
The /export endpoint converts Tiptap documents back into formats like docx, odt, or markdown.
- Method:
POST
Convert a Tiptap document to a different format.
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 Collaboration settings page: https://cloud.tiptap.dev/convert-settings |
Body
| Name | Type | Description |
|---|---|---|
content | Object | The Tiptap document |
format | string | The format to convert to, can be docx, odt or markdown |
Query parameters
| Name | Default | Description |
|---|---|---|
gfm | 0 | Use Github Flavored Markdown for markdown export |
paragraph | paragraph | Defines which prosemirror type is used for paragraph conversion |
heading | heading | Defines which prosemirror type is used for heading conversion |
blockquote | blockquote | Defines which prosemirror type is used for blockquote conversion |
codeblock | codeblock | Defines which prosemirror type is used for codeblock conversion |
bulletlist | bulletlist | Defines which prosemirror type is used for bulletList conversion |
orderedlist | orderedlist | Defines which prosemirror type is used for orderedList conversion |
listitem | listitem | Defines which prosemirror type is used for listItem conversion |
hardbreak | hardbreak | Defines which prosemirror type is used for hardbreak conversion |
horizontalrule | horizontalrule | Defines which prosemirror type is used for horizontalRule conversion |
table | table | Defines which prosemirror type is used for table conversion |
tablecell | tablecell | Defines which prosemirror type is used for tableCell conversion |
tableheader | tableheader | Defines which prosemirror type is used for tableHeader conversion |
tablerow | tablerow | Defines which prosemirror type is used for tableRow conversion |
bold | bold | Defines which prosemirror mark is used for bold conversion |
italic | italic | Defines which prosemirror mark is used for italic conversion |
underline | underline | Defines which prosemirror mark is used for underline conversion |
strikethrough | strike | Defines which prosemirror mark is used for strikethrough conversion |
link | link | Defines which prosemirror mark is used for link conversion |
code | code | Defines which prosemirror mark is used for code conversion |