Markdown to HTML API Documentation¶

Overview¶

The Markdown to HTML API converts Markdown-formatted text into HTML output.
It supports tables, fenced code blocks, smart punctuation, and sane lists.
This API can operate in three modes:

Body Mode (Synchronous) — Markdown text is sent directly in the request body.
URL Mode (Asynchronous) — A remote file URL is provided; the conversion runs asynchronously.
File Mode (Asynchronous) — A previously uploaded file is referenced; the conversion runs asynchronously.

The API returns either an HTML file link (for synchronous mode) or a job ID (for asynchronous mode).

Endpoint (POST)¶

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

Headers¶

Header	Description	Required	Example
`Content-Type`	MIME type of request body	Yes	`application/json`
`x-source-type`	Input source type (`body`, `url`, or `file`)	Optional (defaults to `body`)	`body`
`x-api-key`	API key	Yes	`<api_key>`

Accepted File Extensions¶

Mode	Allowed Extensions
URL Mode	`.txt`, `.md`
File Mode	`.txt`, `.md`

Input Example (Body Mode)¶

# Hello World\nThis is **Markdown** converted to HTML.

Input Example (URL Mode)¶

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

Input Example (File Mode)¶

{
  "file": "user123/uploads/sample.md"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/markdown-to-html-api" \
  -H "Content-Type: application/json" \
  -H "x-source-type: body" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '# Sample Markdown\n\nThis is a test.'

Asynchronous (Remote File URL)¶

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

Asynchronous (Input File)¶

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

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "b7a9f2c1-4e2d-4b9a-9c6e-8f1b2e3d4f5a",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.html",
  "preview": "<h1>Hello World</h1><p>This is <strong>Markdown</strong> converted to HTML.</p>"
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-1234567890abcdef",
  "status_url": "https://api.apidatatools.com/jobs/job-1234567890abcdef",
  "request_id": "b7a9f2c1-4e2d-4b9a-9c6e-8f1b2e3d4f5a"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_MARKDOWN`	400	Markdown input must be a non-empty string	`{"status":"error","error":"INVALID_MARKDOWN","details":{"message":"Markdown input must be a non-empty string"}}`
`MARKDOWN_TO_HTML_ERROR`	400	Unexpected error during conversion	`{"status":"error","error":"MARKDOWN_TO_HTML_ERROR","details":{"message":"Conversion failed"}}`
`INVALID_BODY`	400	Body must be valid JSON	`{"status":"error","error":"INVALID_BODY","details":{"message":"Body must be valid JSON"}}`
`INVALID_URL`	400	Missing or invalid URL	`{"status":"error","error":"INVALID_URL","details":{"message":"URL must be valid http/https."}}`
`URL_UNREACHABLE`	400	Could not reach URL	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	Remote file returned non-200 HTTP status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404"}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Extension '.exe' is not allowed"}}`
`INVALID_FILE`	400	Missing or invalid file path	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`FILE_UNAVAILABLE`	400	File not accessible in S3	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit"}}`
`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, use the Status API:

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

Example Status Response for Async¶

Queued¶

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

Success¶

{
  "job_id": "job-1234567890abcdef",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "result": {
    "status": "success",
    "request_id": "b7a9f2c1-4e2d-4b9a-9c6e-8f1b2e3d4f5a",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.html",
    "preview": "<h1>Converted HTML Preview</h1>"
  }
}

Failed¶

{
  "job_id": "job-1234567890abcdef",
  "status": "failed",
  "error": {
    "code": "MARKDOWN_TO_HTML_ERROR",
    "message": "Conversion failed",
    "details": {}
  }
}

Notes for Developers¶

The output is always HTML (text/html) with .html extension.
For asynchronous operations (url or file mode), a job ID is returned; use the Status API to track progress.
Each response includes a unique request_id for traceability.
The preview field contains the first 100 KB of the generated HTML.
The returned file link is temporary and stored securely.