Last updated: Jul 24, 2025, 10:53 AM UTC

Convert To Markdown API v2 Documentation

What's New in v2

  • Unified API - Single endpoint for all conversions
  • API Key Authentication - Secure access with usage tracking
  • RESTful Design - Intuitive /v1/convert/ paths
  • Usage Analytics API - Track your conversions and performance
  • Structured Error Handling - Clear, actionable error messages

Quick Links: Overview | Pricing | Security | Migration Guide

Quick Start

Step 1: Get Your API Key

  1. Sign up for a free account at convert-to-markdown.knowcode.tech
  2. Get your API key from the dashboard
  3. Start converting documents!

Step 2: 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 get back 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)

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

Option 2: Bearer Token

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

API Endpoints

Base URL

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

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
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.

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

Request:

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"

Response:

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

Excel to Markdown

Convert Excel files to 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 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.

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"

Usage API

Track your API usage and monitor performance.

Get Usage Summary

Get your current billing period usage.

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"
  },
  "subscription": {
    "plan": "free",
    "status": "active"
  },
  "usage": {
    "conversions": {
      "used": 23,
      "limit": 50,
      "percentage": 46.0,
      "remaining": 27
    }
  }
}

Get Usage History

Get historical usage data with daily granularity.

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

Get real-time usage metrics.

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 errors follow a consistent structure:

{
  "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.knowcode.tech/docs/errors#AUTH_001"
}

Common Error Codes

Code Description HTTP Status
AUTH_001 Missing API key 401
AUTH_002 Invalid API key 401
USAGE_001 Monthly quota exceeded 429
VAL_001 Invalid file type 400
VAL_002 File too large (>10MB) 413
PROC_001 Conversion failed 500

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

Migration from v1

If you're using the old endpoints, here's how to migrate:

Old → New Endpoint Mapping

Old Endpoint New Endpoint
/xlsx-converter /v1/convert/excel-to-json
/xlsx-to-md /v1/convert/excel-to-markdown
/pdf-to-md /v1/convert/pdf-to-markdown
/docx-to-html /v1/convert/word-to-html
/docx-to-md /v1/convert/word-to-markdown

Key Changes

  1. Authentication Required - Add X-API-Key header
  2. New URL Structure - Use /v1/convert/ prefix
  3. Response Format - Slightly different structure (see examples)

Example Migration

Before (v1):

curl -X POST https://convert-to-markdown.knowcode.tech/xlsx-converter \
  -F "file=@data.xlsx"

After (v2):

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

Client Libraries

JavaScript/Node.js

const ConvertToMarkdown = require('@knowcode/convert-to-markdown');

const client = new ConvertToMarkdown({
  apiKey: 'your-api-key'
});

// Convert Excel to JSON
const result = await client.convert.excelToJson('data.xlsx');
console.log(result.content);

// Check usage
const usage = await client.usage.getSummary();
console.log(`Used ${usage.conversions.used} of ${usage.conversions.limit}`);

Python

import requests

class ConvertToMarkdown:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://convert-to-markdown.knowcode.tech/v1'
    
    def 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={'X-API-Key': self.api_key},
                files={'file': f}
            )
        return response.json()

# Usage
client = ConvertToMarkdown('your-api-key')
result = client.excel_to_json('data.xlsx')

For Bubble.io Users - API Connector Setup

Easy setup for no-code platforms:

  1. API Name: Convert to Markdown v2
  2. Authentication: Private key in header
  3. Key name: X-API-Key
  4. Key value: Your API key
  5. 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

Security

  • Zero-storage architecture - Files are never saved
  • HTTPS only - All connections encrypted
  • API keys - Secure authentication
  • Rate limiting - Protection against abuse

Read more in our Security Documentation.

Support

API v2 launched January 2025 with authentication, usage tracking, and improved performance.