API Documentation | To-Markdown Converter Integration

Authentication

Use an API key in the Authorization header for programmatic access:

Authorization: Bearer YOUR_API_KEY

The web UI uses a signed server session cookie and does not expose API keys in frontend code.

Rate Limits

/api/v1/convert/file: 100 requests/hour
/api/v1/convert/file/async: 100 requests/hour
/api/v1/convert/url: 30 requests/hour
/api/v1/convert/youtube: 30 requests/hour
/api/v1/convert/text: 120 requests/hour
/api/v1/convert/jobs/{job_id}: 120 requests/hour
/tools/ocr/process: 30 requests/hour

Endpoints

Convert Document

Convert a document to Markdown format.

POST /api/v1/convert/file

Parameters

Name	Type	Description
file	File	The document to convert

For long-running conversions, use async endpoint POST /api/v1/convert/file/async and poll GET /api/v1/convert/jobs/{job_id}.

Queue Conversion Job

Submit file conversion asynchronously and get a job id.

POST /api/v1/convert/file/async

Get Job Status

Query conversion job progress and retrieve result when completed.

GET /api/v1/convert/jobs/{job_id}

Convert Web URL

Convert a public HTTP/HTTPS webpage URL to Markdown.

POST /api/v1/convert/url?url=https://example.com

Convert YouTube URL

Convert a YouTube video URL to transcript-ready Markdown.

POST /api/v1/convert/youtube?url=https://www.youtube.com/watch?v=VIDEO_ID

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request:

200: Success
400: Bad Request
401: Unauthorized
403: Forbidden
429: Too Many Requests
500: Internal Server Error

Examples

cURL

curl -X POST https://api.to-markdown.com/api/v1/convert/file \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "[email protected]"

Async cURL

# 1) Queue a job
curl -X POST https://api.to-markdown.com/api/v1/convert/file/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "[email protected]"

# 2) Poll status
curl -X GET https://api.to-markdown.com/api/v1/convert/jobs/JOB_ID \
    -H "Authorization: Bearer YOUR_API_KEY"

YouTube cURL

curl -X POST "https://api.to-markdown.com/api/v1/convert/youtube?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVIDEO_ID" \
    -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

url = 'https://api.to-markdown.com/api/v1/convert/file'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
files = {'file': open('document.pdf', 'rb')}

response = requests.post(url, headers=headers, files=files)
markdown = response.json()['markdown']

JavaScript

const formData = new FormData();
formData.append('file', file);

const response = await fetch('https://api.to-markdown.com/api/v1/convert/file', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
});

const data = await response.json();
const markdown = data.markdown;