# markdown.page API

Publish markdown and get a permanent URL. No account or API key required.

POST https://markdown.page/api/publish
POST https://markdown.page/api

Accepted bodies:
- raw markdown text
- JSON string
- JSON object with markdown/content/text/body
- form field markdown/content/text/body

Examples:
  curl https://markdown.page/api/publish --data-binary '# Hello'
  curl https://markdown.page/api/publish --data-binary @README.md
  curl -H 'Accept: text/plain' https://markdown.page/api/publish --data-binary @README.md
  curl -H 'Content-Type: application/json' https://markdown.page/api/publish -d '{"markdown":"# Hello"}'

Response negotiation:
- Browsers/fetch get JSON by default:
  {"slug":"a3x9k2b7","url":"https://markdown.page/a3x9k2b7","raw_url":"https://markdown.page/a3x9k2b7.md"}
- CLI clients and Accept: text/plain get plaintext:
  https://markdown.page/a3x9k2b7

Public GET format negotiation:
- Accept: text/html returns rendered HTML
- Accept: text/plain or text/markdown returns plaintext/markdown where supported
- curl/wget/httpie with Accept: */* receive plaintext by default
- browser defaults receive HTML

For agents and automation:
- Prefer Accept: text/plain when you only need URLs or markdown
- Use GET /{slug}.md to retrieve source markdown for published pages
- Use GET /{slug} when you want negotiated HTML or plaintext
- LLM guide: GET https://markdown.page/llms.txt
- MCP endpoint: POST https://markdown.page/mcp (HTTP JSON-RPC, no auth, no SSE)
- MCP tools: publish_markdown, get_featured_pricing, validate_featured_purchase, get_featured_purchase_status
- Agentic featured promotion is paid placement reviewed before publication.
- Pricing: GET https://markdown.page/pricing.json (alias https://markdown.page/featured/pricing.json) or GET https://markdown.page/pricing.md
- Agentic featured promotion supports x402 and MPP:
  x402:
    POST https://markdown.page/api/featured/purchase/week
    POST https://markdown.page/api/featured/purchase/month
    POST https://markdown.page/api/featured/purchase/quarter
  MPP:
    POST https://markdown.page/api/featured/mpp/purchase/week
    POST https://markdown.page/api/featured/mpp/purchase/month
    POST https://markdown.page/api/featured/mpp/purchase/quarter
  Quotes: GET the same endpoints before POSTing payment.
  Status: GET https://markdown.page/api/featured/purchases/{id}
  Body: {"articleUrl":"https://markdown.page/a3x9k2b7","featuredSlug":"hello-world","contact":"you@example.com","requestId":"agent-run-001"}
  requestId is recommended; purchase ids are x402:{requestId} or mpp:{requestId}.
  Unpaid requests receive HTTP 402 Payment Required; paid requests enter paid_pending_review for admin approval, typically within 48 hours.
- Published pages are public and permanent; do not publish secrets or private data

MCP example:
  curl https://markdown.page/mcp     -H 'Content-Type: application/json'     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"publish_markdown","arguments":{"markdown":"# Hello from MCP"}}}'

Limits:
- 1 MB markdown
- fair-use rate limiting per IP

Explicit format URLs:
  GET https://markdown.page/api.md
  GET https://markdown.page/featured/{slug}.md
  GET https://markdown.page/{slug}.md

Raw markdown:
  GET https://markdown.page/{slug}.md