{
  "openapi": "3.0.1",
  "info": {
    "title": "ConvertAPI",
    "description": "# High-Performance File Conversion API\nConvert Word, Excel, PowerPoint, HTML, PDF and Image formats with our powerful file conversion service.\nWe support more than [200 file types.]( https://www.convertapi.com/doc/file-formats)",
    "termsOfService": "https://www.convertapi.com/terms",
    "contact": {
      "url": "https://www.convertapi.com/support",
      "email": "support@convertapi.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "v2"
  },
  "servers": [
    {
      "url": "https://v2.convertapi.com"
    },
    {
      "url": "https://eu-v2.convertapi.com"
    },
    {
      "url": "https://uk-v2.convertapi.com"
    },
    {
      "url": "https://us-v2.convertapi.com"
    },
    {
      "url": "https://ca-v2.convertapi.com"
    },
    {
      "url": "https://as-v2.convertapi.com"
    },
    {
      "url": "https://au-v2.convertapi.com"
    }
  ],
  "paths": {
    "/convert/html/to/md": {
      "summary": "HTML to MD API",
      "description": "Convert HTML content into clean Markdown (MD). Preserves formatting, supports GitHub-flavored options and custom tag handling.",
      "post": {
        "tags": [
          "Conversion"
        ],
        "externalDocs": {
          "description": "Read more about the converter",
          "url": "https://www.convertapi.com/html-to-md"
        },
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "required": [
                  "File"
                ],
                "type": "object",
                "properties": {
                  "File": {
                    "type": "string",
                    "description": "File to be converted. Value can be URL or file content.",
                    "format": "binary",
                    "x-ca-featured": true,
                    "x-ca-label": "File",
                    "x-ca-group": "Input",
                    "x-ca-type": "File",
                    "x-ca-representation": "Default",
                    "x-ca-allowed-extensions": [
                      "html",
                      "htm"
                    ]
                  },
                  "FileName": {
                    "type": "string",
                    "description": "The `FileName` property defines the name of the output file(s) generated by the file conversion API, ensuring safe and\r\nunique file naming. It sanitizes input filenames to remove potentially harmful characters, automatically appends the\r\ncorrect file extension based on the target format, and includes an indexing feature to distinguish multiple output files\r\nfrom a single input. For example, converting `report.docx` to PDF format might result in `report.pdf` for a single file,\r\nor `report_0.pdf`, `report_1.pdf` for multiple files, ensuring each output file is uniquely identifiable.",
                    "x-ca-featured": false,
                    "x-ca-label": "Output file name",
                    "x-ca-group": "Output",
                    "x-ca-type": "String",
                    "x-ca-representation": "Default",
                    "x-ca-range": {
                      "from": "1",
                      "to": "200"
                    }
                  },
                  "GithubFlavored": {
                    "type": "boolean",
                    "description": "Create GitHub-flavored markdown GFM.",
                    "default": false,
                    "x-ca-featured": false,
                    "x-ca-label": "Github flavored markdown",
                    "x-ca-group": "Options",
                    "x-ca-type": "Bool",
                    "x-ca-representation": "Default"
                  },
                  "RemoveComments": {
                    "type": "boolean",
                    "description": "Remove comment tags.",
                    "default": false,
                    "x-ca-featured": false,
                    "x-ca-label": "Remove comments",
                    "x-ca-group": "Options",
                    "x-ca-type": "Bool",
                    "x-ca-representation": "Default"
                  },
                  "UnsupportedTags": {
                    "enum": [
                      "PassThrough",
                      "Drop",
                      "Bypass",
                      "Fail"
                    ],
                    "type": "string",
                    "description": "Sets the rules on how to handle unsupported HTML tags. Markup that carries no document text is always removed first (scripts, stylesheets, document metadata), and HTML5 structural elements such as `main`, `section` and `article` are always unwrapped, keeping their content. This setting therefore applies to the tags that remain unrecognised after that.",
                    "default": "PassThrough",
                    "x-ca-featured": false,
                    "x-ca-label": "Process unsupported tags",
                    "x-ca-group": "Options",
                    "x-ca-type": "Collection",
                    "x-ca-representation": "Dropdown",
                    "x-ca-values": {
                      "PassThrough": "PassThrough unsupported tags",
                      "Drop": "Drop unsupported tags and content",
                      "Bypass": "Bypass unsupported tags but convert content",
                      "Fail": "Fail and throw exception"
                    }
                  },
                  "PassThroughTags": {
                    "type": "string",
                    "description": "Enter pass-through tags, separating them with commas. The tags will be copied to the MD document without processing. The UnsupportedTags property should be set to PassThrough.",
                    "x-ca-featured": false,
                    "x-ca-label": "Pass through tags",
                    "x-ca-group": "Options",
                    "x-ca-type": "String",
                    "x-ca-representation": "Default"
                  },
                  "ListBulletChar": {
                    "type": "string",
                    "description": "Set bullet list character.",
                    "default": "-",
                    "x-ca-featured": false,
                    "x-ca-label": "List bullet char",
                    "x-ca-group": "Options",
                    "x-ca-type": "String",
                    "x-ca-representation": "Default"
                  },
                  "Images": {
                    "enum": [
                      "embed",
                      "extract",
                      "remove",
                      "describe",
                      "unchanged"
                    ],
                    "type": "string",
                    "description": "Controls how images are handled in the resulting Markdown. `Embed` produces a self-contained document with images embedded as base64 data URIs. `Extract` saves images as separate files referenced by relative links, the result is a zip archive with the Markdown and image files, or a plain Markdown file when the document has no images. `Remove` replaces images with their alt text when available, producing compact output suited for machine processing. `Describe` replaces every image with AI generated text: scanned text and tables are transcribed, pictures become short descriptions, producing text-only Markdown for LLM and RAG scenarios. `Unchanged` does not transform images at all: linked images stay links and embedded images stay embedded. Images referenced by URL are downloaded when `Embed`, `Extract` or `Describe` is selected, and an image that cannot be downloaded keeps its original link.",
                    "default": "unchanged",
                    "x-ca-featured": false,
                    "x-ca-label": "Images",
                    "x-ca-group": "Options",
                    "x-ca-type": "Collection",
                    "x-ca-representation": "Dropdown",
                    "x-ca-values": {
                      "embed": "Embed images as base64",
                      "extract": "Extract images to separate files (zip)",
                      "remove": "Remove images",
                      "describe": "Describe images with AI",
                      "unchanged": "Keep images unchanged"
                    }
                  },
                  "StoreFile": {
                    "type": "boolean",
                    "description": "When the `StoreFile` parameter is set to `True`, your converted file is written to ConvertAPI’s encrypted, temporary storage and made available via a time-limited secure download URL, valid for up to 3 hours. After this period, the file is permanently deleted.\r\n\r\nWhen `StoreFile` is set to `False`, conversion happens entirely in-memory. The raw file bytes are streamed back in the API response without touching disk or external storage, ensuring maximum security and zero persistence so that only you can access the content.\r\n",
                    "default": false,
                    "x-ca-featured": false,
                    "x-ca-label": "Store file",
                    "x-ca-group": "Output",
                    "x-ca-type": "Bool",
                    "x-ca-representation": "Default"
                  },
                  "Timeout": {
                    "maximum": 1200,
                    "minimum": 10,
                    "type": "integer",
                    "description": "Conversion timeout in seconds.",
                    "default": 120,
                    "x-ca-featured": false,
                    "x-ca-label": "Timeout",
                    "x-ca-group": "Execution",
                    "x-ca-type": "Integer",
                    "x-ca-representation": "Default",
                    "x-ca-range": {
                      "from": "10",
                      "to": "1200"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ConversionCost": {
                      "type": "integer",
                      "description": "This amount will be deducted from your balance after the conversion.",
                      "format": "int32",
                      "example": 1
                    },
                    "Files": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "FileName": {
                            "type": "string",
                            "description": "Name of the converted file.",
                            "example": "myfile.pdf"
                          },
                          "FileExt": {
                            "type": "string",
                            "description": "File type (file name extension)",
                            "example": "pdf"
                          },
                          "FileSize": {
                            "type": "integer",
                            "description": "File size",
                            "format": "int32",
                            "example": 111955
                          },
                          "FileId": {
                            "type": "string",
                            "description": "File ID",
                            "example": "25811safe8e61dd3f51ef00ee5f58b92"
                          },
                          "Url": {
                            "type": "string",
                            "description": "File URL",
                            "example": "https://v2.convertapi.com/d/v01plsb72o0cmdooq90w4d1lnqsf6oy4/myfile.pdf"
                          },
                          "FileData": {
                            "type": "string",
                            "description": "Base64 encoded file data",
                            "format": "base64",
                            "example": "JVBERi0xLjcKJb662+4KMSAwIG9iago8PC9UeXBlIC9DYXRhbG9n..."
                          }
                        }
                      }
                    }
                  },
                  "externalDocs": {
                    "url": "https://www.convertapi.com/doc/content-types#applicationjson-1"
                  }
                }
              },
              "multipart/mixed": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "externalDocs": {
                    "url": "https://www.convertapi.com/doc/content-types#multipartmixed"
                  }
                },
                "example": "--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f\nConversionCost: 1\nContent-Type: application/octet-stream\nContent-Disposition: attachment; filename=\"my_file.pdf\"; size=8475\n\n--FILE CONTENT--\n--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f--\n"
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "externalDocs": {
                    "url": "https://www.convertapi.com/doc/content-types#applicationoctet-stream-1"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "415": {
            "$ref": "#/components/responses/415"
          },
          "500": {
            "$ref": "#/components/responses/500"
          },
          "503": {
            "$ref": "#/components/responses/503"
          }
        },
        "security": [
          {
            "secret": [ ]
          },
          {
            "token": [ ]
          },
          {
            "jwt": [ ]
          }
        ]
      },
      "x-ca-overview": "Convert HTML and HTM pages into clean, readable Markdown (.md) through a fast, reliable API. Document structure is preserved: headings, lists, links, code blocks, and tables where possible. Great for documentation pipelines, wikis, CMS imports, version controlled content, and preparing web content for LLM and RAG pipelines.\nThe conversion is tunable: produce GitHub flavored Markdown, remove comments, choose the list bullet character, and decide how unsupported tags are handled: passed through, dropped, or bypassed keeping their content. Scripts, stylesheets and other markup that carries no readable text is always removed first, so the result stays free of noise.\nThe Images parameter decides what happens to the pictures on a page. By default images stay unchanged: linked images remain links and embedded images stay embedded. Use embed for one self contained file, extract to get the images as separate files, remove for the most compact text, or describe to let an AI model turn images into text: scanned paragraphs and tables are transcribed, charts and photos get short descriptions, and decorative images are dropped. Images referenced by URL are downloaded when needed, and the last option produces text only Markdown for LLM and RAG pipelines.\nSimply upload your HTML and receive a UTF-8 Markdown file ready to edit, publish, or feed to a model.\n",
      "x-ca-overview-markdown": "Convert HTML and HTM pages into clean, readable Markdown (.md) through a fast, reliable API. Document structure is preserved: headings, lists, links, code blocks, and tables where possible. Great for documentation pipelines, wikis, CMS imports, version controlled content, and preparing web content for LLM and RAG pipelines.\r\n\r\nThe conversion is tunable: produce GitHub flavored Markdown, remove comments, choose the list bullet character, and decide how unsupported tags are handled: passed through, dropped, or bypassed keeping their content. Scripts, stylesheets and other markup that carries no readable text is always removed first, so the result stays free of noise.\r\n\r\nThe `Images` parameter decides what happens to the pictures on a page. By default images stay unchanged: linked images remain links and embedded images stay embedded. Use `embed` for one self contained file, `extract` to get the images as separate files, `remove` for the most compact text, or `describe` to let an AI model turn images into text: scanned paragraphs and tables are transcribed, charts and photos get short descriptions, and decorative images are dropped. Images referenced by URL are downloaded when needed, and the last option produces text only Markdown for LLM and RAG pipelines.\r\n\r\nSimply upload your HTML and receive a UTF-8 Markdown file ready to edit, publish, or feed to a model.\r\n",
      "x-ca-meta-title": "HTML to Markdown Conversion API - Clean MD Formatting",
      "x-ca-meta-description": "Convert HTML to Markdown via API. Preserves headings, lists, links, images, tables. Supports GFM, pass-through tags, custom bullets, and AI image description for RAG.",
      "x-ca-keywords": "html, markdown, md, llm, rag, ai, embeddings, context, web",
      "x-ca-source-formats": "html,htm",
      "x-ca-destination-formats": "md",
      "x-ca-tags": [
        "html",
        "markdown"
      ]
    }
  },
  "components": {
    "schemas": {
      "fileId": {
        "maxLength": 32,
        "minLength": 32,
        "type": "string",
        "description": "Uploaded File ID",
        "example": "25811safe8e61dd3f51ef00ee5f58b92"
      },
      "error": {
        "type": "object",
        "properties": {
          "Code": {
            "type": "integer",
            "description": "Error message code",
            "format": "int32",
            "example": 4000
          },
          "Message": {
            "type": "string",
            "description": "Error message text",
            "example": "Parameter validation error."
          }
        },
        "externalDocs": {
          "url": "https://www.convertapi.com/doc/response-codes"
        }
      }
    },
    "responses": {
      "400": {
        "description": "Malformed request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "401": {
        "description": "Authentication error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "415": {
        "description": "File type error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "500": {
        "description": "Conversion failure",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      },
      "503": {
        "description": "Conversion rate limit error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/error"
            }
          }
        }
      }
    },
    "parameters": {
      "fileId": {
        "name": "fileId",
        "in": "path",
        "description": "File ID",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/fileId"
        }
      },
      "src": {
        "name": "src",
        "in": "path",
        "description": "Source file format (docx, pdf, jpg etc.)",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "dst": {
        "name": "dst",
        "in": "path",
        "description": "Destination file format (docx, pdf, jpg etc.)",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "headers": {
      "content-disposition": {
        "description": "File information ([docummentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition))",
        "schema": {
          "type": "string"
        }
      },
      "file-name": {
        "description": "File name",
        "schema": {
          "type": "string"
        }
      },
      "file-ext": {
        "description": "File name extension",
        "schema": {
          "type": "string"
        }
      },
      "file-size": {
        "description": "File size",
        "schema": {
          "type": "integer"
        }
      }
    },
    "securitySchemes": {
      "secret": {
        "type": "http",
        "description": "[Get `Secret`](https://www.convertapi.com/a/secret)",
        "scheme": "bearer"
      },
      "token": {
        "type": "http",
        "description": "[Get `Token`](https://www.convertapi.com/a/api-tokens)",
        "scheme": "bearer"
      },
      "jwt": {
        "type": "http",
        "description": "[Get `JWT`](https://www.convertapi.com/a/jwt-tokens)",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "tags": [
    {
      "name": "Conversion",
      "description": "File Conversion API call",
      "externalDocs": {
        "description": "File Conversion related operations",
        "url": "https://www.convertapi.com/doc/content-types"
      }
    },
    {
      "name": "File Server",
      "description": "ConvertAPI temporary file storage",
      "externalDocs": {
        "description": "File Server related operations",
        "url": "https://www.convertapi.com/doc/upload"
      }
    },
    {
      "name": "User",
      "description": "API User",
      "externalDocs": {
        "description": "API User related operations",
        "url": "https://www.convertapi.com/doc/user"
      }
    }
  ],
  "externalDocs": {
    "description": "Find out more about ConvertAPI",
    "url": "https://www.convertapi.com/doc"
  }
}