Markdown Toc API

POST https://api.findutils.com/api/tools/markdown-toc/execute

Build a nested Markdown table of contents from a document's headings, with GitHub-style anchor links by default (or GitLab anchors, or plain labels), and return both the TOC and the document with the TOC inserted. Reads ATX (#) and Setext (=== / ---) headings; skips headings inside fenced and indented code blocks, HTML comments and front matter. Repeated headings get the anchors the host gives them (#setup, #setup-1). The TOC replaces a [TOC] line or fills  ... ; with no marker it goes after a leading H1, else at the top. A one-shot insert: nothing watches the file.

Needs an API key. Running a tool needs an API key. Keys are not for sale yet: ask for early access. About API keys

Open the tool Try it

Request body

application/json

markdown

string required

The Markdown document.
slug_style

string optional

Anchor rules: github (default), gitlab, or plain (labels without links). One of github · gitlab · plain. Default "github".
min_level

integer optional

Shallowest heading level listed, 1 to 6. Default 2, which leaves out a lone title H1. Default 2.
max_level

integer optional

Deepest heading level listed, 1 to 6. Default 4. Default 4.
bullet

string optional

List marker: - (default), *, or 1. for a numbered list. One of - · * · 1.. Default "-".
indent

integer optional

Spaces per nesting level: 2 (default) or 4. A numbered list uses at least 3, which Markdown needs to nest under "1. ". One of 2 · 4. Default 2.
ignore_code_blocks

boolean optional

Skip # lines inside fenced and indented code blocks. Default true. Default true.
add_heading

boolean optional

Put a "## Table of Contents" heading above the list. Default false. Default false.

Example arguments

Verified

{
  "markdown": "# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"
}

curl -X POST https://api.findutils.com/api/tools/markdown-toc/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"
  }'

const response = await fetch('https://api.findutils.com/api/tools/markdown-toc/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: 'Bearer YOUR_API_KEY' },
  body: JSON.stringify({"markdown":"# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"}),
});
const data = await response.json();

import requests

response = requests.post(
    "https://api.findutils.com/api/tools/markdown-toc/execute",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"markdown":"# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"},
)
data = response.json()

$ch = curl_init('https://api.findutils.com/api/tools/markdown-toc/execute');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer YOUR_API_KEY'],
    CURLOPT_POSTFIELDS => '{"markdown":"# Project\n\n## Install\n\n## Usage\n\n### Options\n\n## Setup\n\n## Setup\n"}',
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Also an MCP tool

Call markdown_toc from Claude, Cursor or any MCP client. Same arguments, same output.

https://mcp.findutils.com

MCP reference

Rate limit: 60 a minute, per IP
Auth: API key
REST id: markdown-toc
MCP name: markdown_toc
Category: Text
Machine-readable: openapi.json · markdown.md

Request body

Example arguments

More Text tools

More to explore