# mdapi.io - Markdown Converter API
# https://mdapi.io/llms-full.txt

Convert documents, images and webpages to Markdown.
Optimized for AI agents, RAG pipelines and LLM processing.
Pay-per-use via x402 v1/v2 or manual payment.

## For autonomous AI agents: use the ready SKILL.md → https://mdapi.io/.well-known/SKILL.md or https://mdapi.io/SKILL.md

## Features
- In-memory processing (no data stored)
- No data storage - full privacy  
- Stateless - no sessions or tracking
- Elastic scalability

## Supported Formats
| Type      | Formats                        |
|-----------|--------------------------------|
| Documents | PDF, DOCX, XLSX, XLS, ODT, ODS |
| Images    | JPEG, JPG, PNG, WebP, SVG      |
| Text      | HTML, XML, JSON, CSV, TXT      |
| Webpages  | Any publicly accessible URL    |

## Limits
- Max file: 100MB
- Max URL content: 50MB
- Free tier: 10 requests/day
- Paid: $0.01/request (USDC on Solana)
- Rate limit: 10,000/hour
- Token validity: 1 year

## Authentication
- Bearer: Authorization: Bearer TOKEN
- Header: X-Token-Required: TOKEN
- Query: ?token=TOKEN

## Token Activation
Before using a paid token, it must be activated:
1. Receive 402 with X-Token-Required, X-Memo-Required
2. Send USDC on Solana to wallet with memo
3. Activate: ?token=TOKEN&memo=MEMO
4. After: use token only

## Method Semantics
| Method | Response Format | Notes                                     |
|--------|-----------------|-------------------------------------------|
| GET    | Markdown        | Always returns Markdown                   |
| POST   | JSON            | Always returns JSON                       |
| Error  | Same as method  | GET errors = Markdown, POST errors = JSON |

## GET / (URL/text conversion)
Parameters: url, text, prompt, result, stream, token, memo
- url: URL to convert (required if no text)
- text: Direct text to process
- prompt: Custom LLM instructions
- result: markdown|prompt|both (default: markdown)
- stream: Enable streaming "true" for SSE response
- token: Access token
- memo: Token activation memo

## POST / (File upload)
Returns JSON. Same parameters + file (multipart/form-data).
Required: url OR text OR file

## stream parameter
- "true": Returns SSE stream with real-time chunks
- Token info sent as first message: {"type":"token_info",...}
- Content sent as chunks: {"content":"...",...}
- End marker: data: [DONE]

## result parameter
- markdown: raw converted Markdown (default)
- prompt: LLM result only (requires prompt)
- both: markdown + prompt_result

## prompt examples
| Use Case  | Example                                            |
|-----------|----------------------------------------------------|
| Summarize | ?url=...&prompt=Summarize this&result=prompt       |
| Extract   | ?text=...&prompt=Extract key points&result=prompt  |
| JSON      | ?url=...&prompt=Convert to JSON&result=prompt      |
| Analyze   | ?text=...&prompt=Analyze and explain&result=prompt |

## Response (POST)
{
  "success": true,
  "markdown": "# Converted content",
  "prompt_result": "... (when result=prompt or both)",
  "resource": "https://example.com/file.pdf",  // URL, "text", or filename
  "mimetype": "application/pdf",
  "token_status": "free|valid|invalid",
  "token_balance": 99,
  "token_expires": "2027-01-01T00:00:00Z"
}

## Error Codes
| Code | Description                |
|------|----------------------------|
| 200  | Success                    |
| 400  | Bad request                |
| 401  | Invalid token              |
| 402  | Payment required           |
| 404  | Not found                  |
| 413  | File too large (max 100MB) |
| 429  | Rate limit exceeded        |
| 500  | Internal error             |

## Endpoints

| Method | Path                                                 | Description                                                                                   |
|--------|------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| GET    | /                                                    | API docs or URL/text conversion (via query parameters: `url`, `text`, `prompt`, `result`)     |
| POST   | /                                                    | Convert URL, text, or upload file (supports `url`, `file`, `text`, `prompt`, `result` params) |
| POST   | /v1/chat/completions                                 | OpenAI-compatible endpoint                                                                    |
| GET    | /mcp                                                 | MCP server manifest                                                                           |
| POST   | /mcp                                                 | MCP tool calls                                                                                |
| POST   | /acp/rpc                                             | ACP RPC endpoint                                                                              |
| GET    | /health                                              | Health check                                                                                  |
| GET    | /llms.txt                                            | API documentation                                                                             |
| GET    | /llms-full.txt                                       | Full API documentation                                                                        |
| GET    | /.well-known/ai-discovery.json or /ai-discovery.json | AI discovery                                                                                  |
| GET    | /.well-known/agent.json        or /agent.json        | AI agent discovery                                                                            |                                                                           |
| GET    | /.well-known/agent-card.json   or /agent-card.json   | A2A agent card                                                                                |
| GET    | /.well-known/acp.json          or /acp.json          | ACP manifest                                                                                  |
| GET    | /.well-known/x402.json         or /x402.json         | x402 payment manifest                                                                         |
| GET    | /.well-known/openapi.json      or /openapi.json      | OpenAPI specification (JSON)                                                                  |
| GET    | /.well-known/openapi.yaml      or /openapi.yaml      | OpenAPI specification (YAML)                                                                  |
| GET    | /.well-known/mapi.md           or /mapi.md           | MAPI specification (case-insensitive path MAPI.md support)                                    |
| GET    | /.well-known/skill.md          or /skill.md          | Skill specification (case-insensitive path SKILL.md support)                                  |

## Code Examples

### curl
# GET conversion (free)
curl "https://mdapi.io/?url=https://example.com/file.pdf"

# With prompt
curl "https://mdapi.io/?url=...&prompt=Summarize&result=both"

# Token activation
curl "https://mdapi.io/?url=...&token=TOKEN&memo=MEMO"

# POST file
curl -X POST -F "file=@doc.pdf" "https://mdapi.io/"

# With token
curl -X POST -H "Authorization: Bearer TOKEN" -F "file=@doc.pdf" "https://mdapi.io/"

### Python
import requests
response = requests.get("https://mdapi.io/?url=https://example.com/doc.pdf")
print(response.text)

### JavaScript
const res = await fetch("https://mdapi.io/?url=https://example.com/doc.pdf");
const markdown = await res.text();

### OpenAI SDK (Python)
from openai import OpenAI
client = OpenAI(base_url="https://mdapi.io/v1", api_key="TOKEN")
response = client.chat.completions.create(
    model="markdown-v1",
    messages=[{"role": "user", "content": "Convert https://example.com/doc.pdf"}]
)
print(response.choices[0].message.content)

## MCP Configuration
{
  "mcpServers": {
    "mdapi": {
      "url": "https://mdapi.io/mcp"
    }
  }
}

Token activation via MCP:
{"method":"tools/call","params":{"name":"convert","arguments":{"url":"...","token":"TOKEN","memo":"MEMO"}}}

## Use Cases
| Use Case            | Description                  |
|---------------------|------------------------------|
| table_extraction    | Extract tables from PDF/DOCX |
| code_extraction     | Extract code blocks          |
| summarization       | Document summary             |
| qa_over_document    | Question answering           |
| json_extraction     | Convert to JSON              |
| entity_extraction   | Named entities               |
| metadata_extraction | Document metadata            |

## Links

- **API docs:** https://mdapi.io
- **MCP server manifest:** https://mdapi.io/mcp
- **Health check:** https://mdapi.io/health
- **API documentation:** https://mdapi.io/llms.txt
- **Full API documentation:** https://mdapi.io/llms-full.txt
- **AI discovery:** https://mdapi.io/.well-known/ai-discovery.json                                        or https://mdapi.io/ai-discovery.json
- **AI agent discovery:** https://mdapi.io/.well-known/agent.json                                         or https://mdapi.io/agent.json
- **A2A agent card:** https://mdapi.io/.well-known/agent-card.json                                        or https://mdapi.io/agent-card.json
- **ACP manifest:** https://mdapi.io/.well-known/acp.json                                                 or https://mdapi.io/acp.json
- **x402 payment manifest:** https://mdapi.io/.well-known/x402.json                                       or https://mdapi.io/x402.json
- **OpenAPI specification (JSON):** https://mdapi.io/.well-known/openapi.json                             or https://mdapi.io/openapi.json
- **OpenAPI specification (YAML):** https://mdapi.io/.well-known/openapi.yaml                             or https://mdapi.io/openapi.yaml
- **MAPI specification (case-insensitive path MAPI.md support):** https://mdapi.io/.well-known/mapi.md    or https://mdapi.io/mapi.md
- **Skill specification (case-insensitive path SKILL.md support):** https://mdapi.io/.well-known/skill.md or https://mdapi.io/skill.md

## Disclaimer

**The service is provided "AS IS".**