HTML to Markdown API Documentation¶

Overview¶

The HTML to Markdown API converts HTML content into Markdown format.
It supports three input modes:

Body Mode (direct HTML string)
URL Mode (remote HTML file)
File Mode (uploaded HTML file from storage)

The API returns a downloadable Markdown file and a preview snippet of the converted content.

Endpoint (POST)¶

POST https://api.apidatatools.com/html-to-markdown-api

Headers¶

Header	Description	Required	Example
`Content-Type`	Defines the input type. Usually `application/json` or `text/plain`.	Yes	`application/json`
`x-source-type`	Specifies input source type: `body`, `url`, or `file`.	Optional (default: `body`)	`x-source-type: url`
`x-api-key`	API key for authentication.	Yes	`<api_key>`

Accepted File Extensions¶

This tool accepts the following input file types:

.txt, .html

Input Example (Body Mode)¶

<h1>Hello World</h1><p>This is a paragraph.</p>

Input Example (URL Mode)¶

{
  "url": "https://example.com/sample.html"
}

Input Example (File Mode)¶

{
  "file": "user_uploads/sample.html"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/html-to-markdown-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: body" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '<h1>Title</h1><p>Sample text.</p>'

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/html-to-markdown-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: url" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://example.com/sample.html"}'

Asynchronous (Input File)¶

curl -X POST "https://api.apidatatools.com/html-to-markdown-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-source-type: file" \
  -d '{"file": "uploads/user123/sample.html"}'

Example Response¶

Successful (Body Mode)¶

{
  "request_id": "b7f3c2e1-9a8d-4f2a-bb3b-1c2d9f8e6a7d",
  "status": "success",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.md",
  "preview": "# Title\n\nSample text."
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job_123456789",
  "status_url": "https://api.apidatatools.com/jobs/job_123456789",
  "request_id": "b7f3c2e1-9a8d-4f2a-bb3b-1c2d9f8e6a7d"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_HTML`	400	HTML input must be a non-empty string.	`{"status":"error","error":"INVALID_HTML","details":{"message":"HTML input must be a non-empty string"}}`
`DEPENDENCY_MISSING`	500	Required dependency `html2text` not installed.	`{"status":"error","error":"DEPENDENCY_MISSING","details":{"message":"html2text is not installed in the Lambda runtime"}}`
`HTML_TO_MARKDOWN_ERROR`	400	Conversion failed due to malformed HTML or internal error.	`{"status":"error","error":"HTML_TO_MARKDOWN_ERROR","details":{"message":"Unexpected parsing error"}}`
`INVALID_URL`	400	Provided URL is invalid or missing.	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	Remote URL could not be reached.	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	Remote URL returned non-200 response.	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit.	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"File exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension.	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`FILE_UNAVAILABLE`	400	File not accessible in storage.	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`INVALID_SOURCE_TYPE`	400	Invalid source type header.	`{"status":"error","error":"INVALID_SOURCE_TYPE","details":{"message":"Must be 'url' or 'file'."}}`
`INTERNAL_ERROR`	500	Unexpected internal error.	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

To check the status of an asynchronous job (URL or File mode):

Endpoint¶

GET https://api.apidatatools.com/jobs/{job_id}

Example Status Response for Async¶

{
  "job_id": "job_123456789",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "request_id": "b7f3c2e1-9a8d-4f2a-bb3b-1c2d9f8e6a7d",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.md",
    "preview": "# Title\n\nSample text."
  }
}

If the job is still processing:

{
  "job_id": "job_123456789",
  "status": "queued",
  "message": "Your job is being processed.",
  "retry_after": 2
}

If the job failed:

{
  "job_id": "job_123456789",
  "status": "failed",
  "error": {
    "code": "HTML_TO_MARKDOWN_ERROR",
    "message": "Conversion failed",
    "details": {}
  }
}

Notes for Developers¶

The API supports synchronous and asynchronous processing depending on x-source-type.
For Body Mode, conversion happens instantly and returns a downloadable Markdown file.
For URL or File Mode, a job is queued and processed asynchronously.
Use the status_url to poll job status.
Each response includes a unique request_id for tracking.
The preview is limited to the first 100 KB of the converted Markdown.