# PlainMarkdown API

> Convert any URL into clean, LLM-ready Markdown.

## API Usage
- Base URL: https://api.plainmarkdown.com
- Auth: Bearer token in header `Authorization: Bearer <token>`
- Content-Type: application/json

## Endpoints

### POST /v1/convert
Converts a web page to Markdown.

**Request JSON:**
- `url` (string, required): The URL to convert.
- `include_metadata` (boolean, optional): Default false. If true, returns title, byline, excerpt, siteName, length, dir, url.
- `response_format` (enum, optional): "markdown" (default) or "text" (strips all markdown formatting).

**Response JSON:**
- `status`: "success" or "error"
- `data.content`: The converted Markdown (or plain text).
- `data.metadata`: Page metadata (only if include_metadata is true).

**Example:**
```bash
curl -X POST https://api.plainmarkdown.com/v1/convert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KEY" \
  -d '{"url": "https://example.com"}'
```

### GET /health
Returns `{"status": "ok"}`. No auth required.

## Rate Limits
- Free: 10 requests per minute, 100 per hour
- Discovery ($9/mo): 60 requests per minute, 600 per hour
- Growth ($49/mo): 200 requests per minute, 2,000 per hour
- Exceeding either limit returns HTTP 429

## MCP Server

PlainMarkdown is available as an MCP server for AI editors and agents.

- Endpoint: https://api.plainmarkdown.com/mcp
- Transport: Streamable HTTP (POST)
- Auth: Bearer token in header `Authorization: Bearer <token>`
- Tool: `webpage_to_markdown` — converts a web page URL to clean Markdown or plain text

## Docs
- OpenAPI spec: https://api.plainmarkdown.com/openapi.json
- Interactive docs: https://api.plainmarkdown.com/docs