npm package: @knowcode/convert-to-markdown
Description: Convert Excel, PDF, and Word documents to clean, AI-ready formats like Markdown and JSON
Author: lindsay-knowcode
Latest version: 1.3.3

# Convert to Markdown

[![npm version](https://img.shields.io/npm/v/@knowcode/convert-to-markdown.svg?style=flat-square)](https://www.npmjs.com/package/@knowcode/convert-to-markdown)
[![npm downloads](https://img.shields.io/npm/dm/@knowcode/convert-to-markdown.svg?style=flat-square)](https://www.npmjs.com/package/@knowcode/convert-to-markdown)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![API v2](https://img.shields.io/badge/API-v2-brightgreen?style=flat-square)](./docs/api.md)
[![Knowcode Organization](https://img.shields.io/badge/org-knowcode-blue?style=flat-square)](https://github.com/knowcode)

Convert Excel, PDF, and Word documents to clean, AI-ready formats with our secure API.

<div align="center">
  
### 🚀 **Production API Endpoint**

**✨ https://convert-api-qpg64cvnga-uk.a.run.app**

**Secure API with Authentication • Usage Tracking • 50 Free Conversions/month**

</div>

## 🎯 Key Features

- **🔑 API Key Authentication** - Secure access with usage tracking
- **📊 Usage Analytics** - Monitor your conversions and performance
- **🎨 RESTful Design** - Clean, intuitive `/v1/convert/` endpoints
- **🆓 Free Tier** - 50 conversions/month to get started
- **⚡ Fast Processing** - Convert documents in seconds
- **🔒 Zero Storage** - Your files are never saved

## 🚀 Quick Start

### 1. Get Your API Key

**Test API Keys Available:**
- **Free Tier**: `test_a8baaf01a4124761b7467b918bc9c263` (50 conversions/month)
- **Pro Tier**: `pro_eb78f30408b647c6bcb90ccb9027c5f6` (10,000 conversions/month)

### 2. Make Your First Request

```bash
curl -X POST https://convert-api-qpg64cvnga-uk.a.run.app/v1/convert/pdf-to-markdown \
  -H "X-API-Key: test_a8baaf01a4124761b7467b918bc9c263" \
  -F "file=@yourfile.pdf"
```

### 3. Check Your Usage

```bash
curl https://convert-api-qpg64cvnga-uk.a.run.app/v1/usage/summary \
  -H "X-API-Key: test_a8baaf01a4124761b7467b918bc9c263"
```

## 📚 Documentation

- **[API Documentation](./docs/api.md)** - Complete API reference
- **[Pricing](./docs/pricing.md)** - Simple, transparent pricing
- **[Security](./docs/security.md)** - Zero-storage architecture
- **[NPM Package](./docs/setup/npm-usage.md)** - Programmatic usage
- **[CLI Usage](./docs/setup/cli-usage-guide.md)** - Command-line interface

## 🔄 Supported Conversions

| From | To | Endpoint |
|------|----|----------|
| Excel (.xlsx, .xls, .xlsm) | JSON | `/v1/convert/excel-to-json` |
| Excel (.xlsx, .xls, .xlsm) | Markdown | `/v1/convert/excel-to-markdown` |
| PDF | Markdown | `/v1/convert/pdf-to-markdown` |
| Word (.docx, .dotx, .dotm) | HTML | `/v1/convert/word-to-html` |
| Word (.docx, .dotx, .dotm) | Markdown | `/v1/convert/word-to-markdown` |

## 💰 Pricing

| Plan | Price | Conversions | File Size | Support |
|------|-------|-------------|-----------|---------|
| **Free** | $0/month | 50/month | 5MB | Community |
| **Pro** | $10/month | 10,000/month | 10MB | Priority |
| **Enterprise** | Custom | Unlimited | Custom | Dedicated |

## 💻 CLI Installation

Install the command-line tool for local document conversion:

```bash
npm install -g @knowcode/convert-to-markdown
```

Quick usage:
```bash
# Convert Excel to Markdown
convert-to-markdown excel-to-markdown report.xlsx -o report.md

# Convert PDF to Markdown
convert-to-markdown pdf-to-markdown document.pdf -o document.md

# Show all examples
convert-to-markdown examples
```

See [CLI Usage Guide](./docs/setup/cli-usage-guide.md) for complete documentation.

## 🛠️ Integration Examples

### JavaScript/Node.js

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

const response = await fetch('https://convert-to-markdown.knowcode.tech/v1/convert/excel-to-json', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key'
  },
  body: formData
});

const result = await response.json();
console.log(result.content);
```

### Python

```python
import requests

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

### Bubble.io

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

## 🔒 Security First

- **Zero-storage architecture** - Your files are never saved
- **Memory-only processing** - Data processed in RAM only
- **Instant deletion** - Files purged after conversion
- **HTTPS encryption** - Secure data transmission

[Read more about our security →](./docs/security.md)

## 📊 Usage Tracking

Monitor your API usage in real-time:

```bash
# Get current month summary
curl https://convert-to-markdown.knowcode.tech/v1/usage/summary \
  -H "X-API-Key: your-api-key"

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

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

## 🚨 Error Handling

All errors follow a consistent format:

```json
{
  "error": {
    "code": "USAGE_001",
    "message": "Monthly quota exceeded (50 conversions)",
    "details": {
      "used": 50,
      "limit": 50
    }
  },
  "help": "Upgrade to Pro plan for 10,000 monthly conversions",
  "documentation": "https://convert-to-markdown.knowcode.tech/docs/errors#USAGE_001"
}
```

## 📦 NPM Package

For self-hosted deployments:

```bash
npm install @knowcode/convert-to-markdown
```

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

// Use as a library (self-hosted)
const result = await ConvertToMarkdown.excelToJson('data.xlsx');
console.log(result.content);
```

[NPM Package Documentation →](./docs/npm-usage.md)

## 🚀 Deploy Your Own

Deploy as Google Cloud Functions:

```bash
# Clone the repository
git clone https://github.com/wapdat/convert-to-markdown.git
cd convert-to-markdown

# Deploy to Google Cloud
./deploy.sh
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

## 🆘 Support

- **Documentation**: [convert-to-markdown.knowcode.tech/docs](https://convert-to-markdown.knowcode.tech/docs)
- **Email**: lindsay@knowcode.tech
- **GitHub Issues**: [Report a bug](https://github.com/wapdat/convert-to-markdown/issues)

---

Built with ❤️ by [Knowcode](https://github.com/knowcode) • Powered by Google Cloud Functions