API Reference

TokenMarkdown API Documentation

TokenMarkdown is a high-throughput, deterministic web-to-markdown API designed to compress web pages into token-efficient GitHub-Flavored Markdown for LLMs, RAG pipelines, and autonomous AI agents.

Base URL: https://tokenmarkdown.com

Authentication

Pass your API key in the Authorization header as a Bearer token or using the x-api-key header:

Authorization: Bearer tm_live_YOUR_API_KEY
x-api-key: tm_live_YOUR_API_KEY

Prefix Proxy (Zero-SDK Instant Extraction)

Fetch clean markdown from any URL by prepending https://tokenmarkdown.com/ before the target address:

curl -s "https://tokenmarkdown.com/https://linear.app/blog/rethinking-issue-tracking"

POST /v1/extract

Extracts clean markdown and structured metadata from a single webpage.

Request Body (JSON)

{
  "url": "https://linear.app/blog/rethinking-issue-tracking",
  "query": "performance",      // Semantic section filter (drops unrelated content)
  "include_toc": true,        // Prepends automated Table of Contents
  "include_images": true,
  "include_links": true,
  "selector": "article",
  "format": "json"            // "json" | "raw" | "xml" | "markdown"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "url": "https://linear.app/blog/rethinking-issue-tracking",
    "title": "Rethinking Issue Tracking",
    "author": "Karri Saarinen",
    "word_count": 842,
    "estimated_tokens": 620,
    "reading_time_minutes": 4,
    "markdown": "# Rethinking Issue Tracking\n\nSoftware teams spend 40%...",
    "outline": [
      { "level": 2, "title": "The Principles of High-Velocity Teams", "anchor": "the-principles-of-high-velocity-teams" }
    ],
    "schema_org": {
      "entities": [
        { "@type": "Article", "headline": "Rethinking Issue Tracking", "author": { "name": "Karri Saarinen" } }
      ]
    }
  },
  "performance": {
    "fetch_latency_ms": 94,
    "parse_latency_ms": 30,
    "total_latency_ms": 124,
    "tokens_per_second": 5000
  }
}

Model Context Protocol (MCP) Setup

To enable TokenMarkdown in Claude Desktop or Cursor, add the following configuration:

claude_desktop_config.json

{
  "mcpServers": {
    "tokenmarkdown": {
      "command": "npx",
      "args": ["-y", "tokenmarkdown-mcp"],
      "env": {
        "TOKENMARKDOWN_API_KEY": "tm_live_YOUR_API_KEY"
      }
    }
  }
}

Standard Error Codes

All API errors follow the RFC 7807 structured JSON format:

Error Code	HTTP Status	Description
`SSRF_IP_BLOCKED`	400	Target URL points to a private/loopback IP address.
`UPSTREAM_BOT_BLOCK`	403	Target site is protected by Cloudflare Turnstile / Bot challenge.
`PAYLOAD_TOO_LARGE`	413	Target webpage exceeds the 10MB streaming size limit.
`RATE_LIMIT_EXCEEDED`	429	Monthly quota or public IP rate limit reached.