Convert To Markdown API Documentation

Overview

Welcome to the Convert To Markdown API! This guide will help you convert documents (Excel, Word, PDF) into clean, AI-ready formats like Markdown, JSON, and HTML.

Quick Links: Overview | Pricing | Security | NPM Package | Project Settings

Getting Started

1. Get Your API Key

2. Make Your First API Call

curl -X POST https://convert-to-markdown.knowcode.tech/v1/convert/excel-to-json \
  -H "X-API-Key: your-api-key-here" \
  -F "file=@yourfile.xlsx"

That's it! You'll receive clean JSON data from your Excel file.

Authentication

All API requests require authentication using an API key. Include your key in one of these ways:

Option 1: X-API-Key Header (Recommended)

-H "X-API-Key: your-api-key-here"

Option 2: Bearer Token

-H "Authorization: Bearer your-api-key-here"

API Reference

Base URL

https://convert-to-markdown.knowcode.tech

ℹ️ Note: For all project settings, domains, and constants, see Project Settings

Available Endpoints

Method	Endpoint	Description
`GET`	`/v1/health`	Health check (no auth required)
`GET`	`/v1`	API information and endpoints
`POST`	`/v1/convert/excel-to-json`	Convert Excel to JSON
`POST`	`/v1/convert/excel-to-markdown`	Convert Excel to Markdown
`POST`	`/v1/convert/pdf-to-markdown`	Convert PDF to Markdown
`POST`	`/v1/convert/word-to-html`	Convert Word to HTML
`POST`	`/v1/convert/word-to-markdown`	Convert Word to Markdown
`POST`	`/v1/convert/ppt-to-markdown`	Convert PowerPoint to Markdown
`GET`	`/v1/usage/summary`	Get usage summary
`GET`	`/v1/usage/history`	Get usage history
`GET`	`/v1/usage/current`	Get real-time usage

Conversion Endpoints

Excel to JSON

Convert Excel files (.xlsx, .xls, .xlsm) to structured JSON with resolved formulas.

Endpoint: POST /v1/convert/excel-to-json

Request Example

Using cURL:

curl -X POST \
  https://convert-to-markdown.knowcode.tech/v1/convert/excel-to-json \
  -H "X-API-Key: your-api-key" \
  -F "file=@sales-report.xlsx"

Using JavaScript:

const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('https://convert-to-markdown.knowcode.tech/v1/convert/excel-to-json', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key'
  },
  body: formData
})
.then(res => res.json())
.then(data => console.log(data));

Using Python:

import requests

with open('sales-report.xlsx', 'rb') as f:
    files = {'file': f}
    headers = {'X-API-Key': 'your-api-key'}
    response = requests.post(
        'https://convert-to-markdown.knowcode.tech/v1/convert/excel-to-json',
        headers=headers,
        files=files
    )
    print(response.json())

Response Example

{
  "content": "{\"Sheet1\":[{\"Product\":\"Widget A\",\"Price\":29.99,\"Quantity\":100,\"Total\":2999}]}",
  "statistics": {
    "fileSize": {
      "bytes": 12288,
      "KB": 12,
      "MB": 0.01
    },
    "sheets": 1,
    "estimatedTokens": 450,
    "processingTime": "782ms"
  }
}

Excel to Markdown

Convert Excel spreadsheets into clean Markdown tables.

Endpoint: POST /v1/convert/excel-to-markdown

Request

curl -X POST https://convert-to-markdown.knowcode.tech/v1/convert/excel-to-markdown \
  -H "X-API-Key: your-api-key" \
  -F "file=@data.xlsx"

Response

{
  "markdown": "# Sheet1\n\n| Product | Price | Quantity |\n|---------|-------|----------|\n| Widget A | 29.99 | 100 |\n",
  "statistics": {
    "fileSize": { "bytes": 12288, "KB": 12, "MB": 0.01 },
    "estimatedTokens": 125,
    "processingTime": "523ms"
  }
}

PDF to Markdown

Extract text and tables from PDFs as Markdown.

Endpoint: POST /v1/convert/pdf-to-markdown

Request

curl -X POST https://convert-to-markdown.knowcode.tech/v1/convert/pdf-to-markdown \
  -H "X-API-Key: your-api-key" \
  -F "file=@document.pdf"

Word to HTML

Convert Word documents (.docx, .dotx, .dotm) to clean, semantic HTML.

Endpoint: POST /v1/convert/word-to-html

Request

curl -X POST https://convert-to-markdown.knowcode.tech/v1/convert/word-to-html \
  -H "X-API-Key: your-api-key" \
  -F "file=@report.docx"

Word to Markdown

Convert Word documents to Markdown format.

Endpoint: POST /v1/convert/word-to-markdown

Request

curl -X POST https://convert-to-markdown.knowcode.tech/v1/convert/word-to-markdown \
  -H "X-API-Key: your-api-key" \
  -F "file=@document.docx"

PowerPoint to Markdown

Convert PowerPoint presentations (.pptx) to Markdown format, preserving slide structure and speaker notes.

Endpoint: POST /v1/convert/ppt-to-markdown

Request

curl -X POST https://convert-to-markdown.knowcode.tech/v1/convert/ppt-to-markdown \
  -H "X-API-Key: your-api-key" \
  -F "file=@presentation.pptx"

Response

{
  "markdown": "# Presentation Title\n\n## Slide 1\n\nContent of first slide...\n\n> **Speaker Notes:** These are the notes for slide 1\n\n---\n\n## Slide 2\n\nContent of second slide...",
  "filename": "presentation.pptx",
  "statistics": {
    "slideCount": 15,
    "totalImages": 8,
    "hasSpeakerNotes": true,
    "estimatedTokens": 2500,
    "processingTime": "1.2s"
  }
}

Features

Slide Structure: Each slide is converted to a section with proper headings
Speaker Notes: Preserved as blockquotes with clear labeling
Image Handling: Large images are replaced with descriptive placeholders
Metadata: Includes slide count, image statistics, and processing metrics

Usage API

Track your API usage and monitor performance with our comprehensive usage endpoints.

Get Usage Summary

View your current billing period usage and limits.

Endpoint: GET /v1/usage/summary

Request

curl https://convert-to-markdown.knowcode.tech/v1/usage/summary \
  -H "X-API-Key: your-api-key"

Response

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z",
    "timezone": "UTC"
  },
  "subscription": {
    "plan": "pro",
    "status": "active",
    "renewed_at": "2025-01-01T00:00:00Z",
    "expires_at": "2025-02-01T00:00:00Z"
  },
  "usage": {
    "conversions": {
      "used": 3847,
      "limit": 10000,
      "percentage": 38.47,
      "remaining": 6153
    },
    "storage": {
      "bytes_processed": 487293847,
      "mb_processed": 464.7,
      "largest_file_mb": 47.3
    }
  },
  "current_rate": {
    "daily_average": 124,
    "projected_monthly": 3720,
    "days_until_limit": 49
  }
}

Get Usage History

Retrieve detailed historical usage data.

Endpoint: GET /v1/usage/history

Query Parameters

start_date - Start date (YYYY-MM-DD)
end_date - End date (YYYY-MM-DD)
granularity - daily (default), hourly, or monthly

Request

curl "https://convert-to-markdown.knowcode.tech/v1/usage/history?start_date=2025-01-01&end_date=2025-01-07" \
  -H "X-API-Key: your-api-key"

Get Current Usage

Real-time usage metrics for today and the last hour.

Endpoint: GET /v1/usage/current

Request

curl https://convert-to-markdown.knowcode.tech/v1/usage/current \
  -H "X-API-Key: your-api-key"

Error Handling

All API errors follow a consistent, structured format designed for easy parsing and actionable responses.

Error Response Format

{
  "error": {
    "code": "AUTH_001",
    "message": "API key is required",
    "details": {
      "headers": ["X-API-Key", "Authorization"]
    }
  },
  "help": "Include your API key in X-API-Key header or Authorization: Bearer {key}",
  "documentation": "https://convert-to-markdown.vercel.app/docs/errors#AUTH_001"
}

Common Error Codes

Code	Description	HTTP Status	Solution
`AUTH_001`	Missing API key	401	Add X-API-Key header
`AUTH_002`	Invalid API key	401	Check your API key
`AUTH_003`	Expired API key	401	Renew your subscription
`USAGE_001`	Monthly quota exceeded	429	Upgrade to Pro plan
`VAL_001`	Invalid file type	400	Check supported formats
`VAL_002`	File too large	413	Reduce file size (<10MB)
`VAL_003`	Missing file	400	Include file in request
`PROC_001`	Conversion failed	500	Check file integrity

Rate Limits & Quotas

Free Plan

50 conversions per month
5MB max file size
10 requests per minute

Pro Plan ($10/month)

10,000 conversions per month
10MB max file size
100 requests per minute
Priority support
Advanced analytics

Integration Examples

For Bubble.io Users

Easy API Connector setup:

API Name: Convert to Markdown
Authentication: Private key in header
Key name: X-API-Key
Key value: Your API key
Base URL: https://convert-to-markdown.knowcode.tech/v1

Example Call Configuration

Name: Convert Excel to JSON
Method: POST
URL: /convert/excel-to-json
Body type: Form-data
Parameters: file (File type)

JavaScript SDK Example

class ConvertToMarkdownAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://convert-to-markdown.knowcode.tech/v1';
  }

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

    const response = await fetch(`${this.baseURL}/convert/excel-to-json`, {
      method: 'POST',
      headers: {
        'X-API-Key': this.apiKey
      },
      body: formData
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return response.json();
  }

  async getUsage() {
    const response = await fetch(`${this.baseURL}/usage/summary`, {
      headers: {
        'X-API-Key': this.apiKey
      }
    });

    return response.json();
  }
}

// Usage
const api = new ConvertToMarkdownAPI('your-api-key');
const result = await api.convertExcelToJson(fileInput.files[0]);

Python Client Example

import requests

class ConvertToMarkdownAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://convert-to-markdown.knowcode.tech/v1'
        self.headers = {'X-API-Key': self.api_key}
    
    def convert_excel_to_json(self, file_path):
        with open(file_path, 'rb') as f:
            response = requests.post(
                f'{self.base_url}/convert/excel-to-json',
                headers=self.headers,
                files={'file': f}
            )
        response.raise_for_status()
        return response.json()
    
    def get_usage_summary(self):
        response = requests.get(
            f'{self.base_url}/usage/summary',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
api = ConvertToMarkdownAPI('your-api-key')
result = api.convert_excel_to_json('data.xlsx')
print(f"Converted {result['statistics']['sheets']} sheets")

Security

Zero-storage architecture - Files are processed in memory only
Instant deletion - No data persists after conversion
HTTPS only - All communications encrypted
API key authentication - Secure access control
Rate limiting - Protection against abuse

Read our full Security Documentation.

Best Practices

Handle errors gracefully - Check for error responses and display helpful messages
Monitor your usage - Use the usage API to track your conversions
Optimize file sizes - Compress large files before conversion
Cache results - Store conversion results to avoid redundant API calls
Use appropriate timeouts - Set reasonable timeouts for large file conversions

Support

Documentation: convert-to-markdown.vercel.app/docs
Email: lindsay@knowcode.tech
GitHub Issues: Report a bug
Response Time:
- Free tier: 48-72 hours
- Pro tier: 24 hours

Convert To Markdown API - Simple, Secure, Scalable