API, MCP and CLI

Authorization: Bearer rdbl_…

curl https://readable.md/api/v1/transform \
  -H "Authorization: Bearer $READABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tool": "deslop", "text": "In today’s fast-paced world…" }'

curl https://readable.md/api/v1/transform \
  -H "Authorization: Bearer $READABLE_API_KEY" \
  -F tool=shorten -F length=0.4 -F file=@report.pdf

{
  "id": "5f0c…",
  "share_url": "https://readable.md/r/5f0c…",
  "summary": "107 → 29 words · 6 padded sentences fixed · every fact kept · 2.4 s",
  "settings": { "tool": "deslop", … },
  "stats": { "wordsBefore": 107, "wordsAfter": 29, "slopBefore": 6, … },
  "blocks": [ { "id": "b1", "original": "…", "output": "…", "status": "rewritten",
                "findings": [ { "text": "…", "kind": "filler" } ], … } ],
  "markdown": "…"
}

curl https://readable.md/api/v1/usage -H "Authorization: Bearer $READABLE_API_KEY"

{ "plan": "pro", "pages_used": 7, "pages_limit": 35,
  "pages_per_run": 25, "words_per_page": 500,
  "period_start": "2026-09-14T09:12:00.000Z",
  "renews_at": "2026-10-14T09:12:00.000Z" }

curl https://readable.md/api/v1/workspaces -H "Authorization: Bearer $READABLE_API_KEY"

{ "workspaces": [ { "id": "3f9a2c71-…", "name": "Readable",
                    "updated_at": "2026-09-25T15:40:00.000Z" } ] }

curl https://readable.md/api/v1/review \
  -H "Authorization: Bearer $READABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "workspace": "3f9a2c71-…" }'

{ "text": "# Unlock the power of AI-driven writing\n\n…",
  "context": { "name": "Readable",
               "audience": "Founders and marketers at small B2B software companies",
               "facts": "Tools: De-slop, Slop check, … Free: 6 pages a month.",
               "goals": "Get visitors to try a tool and sign up" } }

{
  "id": "b07e5d12-…",
  "workspace": { "id": "3f9a2c71-…", "name": "Readable" },
  "summary": {
    "line": "4 findings in 4 blocks · 4 high · 4 with checked fixes",
    "bySeverity": { "high": 4, "medium": 0, "low": 0 },
    "page": { "purposeClear": 0.07, "nextStepClear": 0.29 }
  },
  "findings": [ {
    "quote": "Readable is the ultimate all-in-one AI platform … Trusted by
              10,000+ companies worldwide.",
    "kind": "unsupported", "severity": "high", "role": "paragraph",
    "reason": "This says Readable is an all-in-one AI writing platform, but
               the facts say it reviews existing text and checks rewrites …",
    "fixes": [
      { "id": "f-b2-1", "text": "Readable checks your copy against the
                                original, so you can rewrite with AI and
                                keep the facts in place." }, …
    ]
  }, … ],
  "markdown": "# Review\n\n4 findings in 4 blocks …"
}

claude mcp add --transport http readable https://readable.md/mcp \
  --header "Authorization: Bearer $READABLE_API_KEY"

{
  "mcpServers": {
    "readable": {
      "url": "https://readable.md/mcp",
      "headers": { "Authorization": "Bearer rdbl_…" }
    }
  }
}

npm i -g readable-md
readable login                      # paste your key once

readable deslop draft.md > clean.md
pbpaste | readable check            # free
readable shorten report.pdf --length 0.4 --out short.md
readable simplify --url https://example.com/terms --audience customers
readable explain spec.md --level 1
readable workspaces                 # ids for --workspace
readable review https://example.com --workspace <id>
readable review draft.md --context product.json --fail-on high   # exit 5
readable mcp                       # print MCP setup for your editor

name: Docs slop check
on:
  pull_request:
    paths: ["**/*.md"]
jobs:
  readable:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check changed Markdown
        env:
          READABLE_API_KEY: ${{ secrets.READABLE_API_KEY }}
        run: |
          files=$(git diff --name-only --diff-filter=AM "origin/${{ github.base_ref }}...HEAD" -- '*.md')
          [ -z "$files" ] || npx --yes readable-md check --max-slop 30 $files