Migrate from ReadMe or Mintlify to Outworx in 15 Minutes

If you're paying $99/mo for ReadMe or $150/mo for Mintlify and wondering if it's worth it — the answer is usually "no" once you've shipped your spec and the maintenance-mode bill keeps coming. This guide is the exact path to move off either one and onto Outworx Docs in about fifteen minutes.

We'll cover: exporting your spec, preserving versions, migrating custom domains, and what to do with old redirects so you don't lose backlinks.

Step 1 — Export your spec (2 minutes)

Both platforms let you export your OpenAPI / Swagger source.

ReadMe: Dashboard → API Reference → click the three-dot menu on your version → Export OpenAPI. You get a .json file.

Mintlify: Your spec is usually already a file in your docs repo (openapi.yaml or openapi.json). If you've been editing it in the Mintlify web editor instead of git, use the Download button in their dashboard to get the current snapshot.

One gotcha: ReadMe and Mintlify both augment their display with guide pages, changelogs, and sometimes custom MDX. For this guide we're migrating the API reference only. If you've written extensive long-form docs on top, plan to port those as MDX pages after the spec is live — Outworx Docs will soon support custom MDX pages out of the box.

Step 2 — Upload to Outworx (1 minute)

1. Sign up at docs.outworx.io (free, no card).
2. Click New Project → name it whatever your API is called. Pick a slug — this becomes your hosted URL.
3. In the API Spec tab, click Upload. Drag the file in.

Your docs go live at yourslug.docs.outworx.io immediately. Click the link. Every endpoint is there, the Try It playground works, code snippets are pre-generated in cURL, Fetch, Axios, and Python.

Step 3 — Preserve versions (3 minutes)

If your old provider had multiple API versions (say v1, v2-beta), you want each to become its own Outworx version so existing customers don't hit 404s.

On Outworx:

1. API Spec tab → New version
2. Upload the spec file for each old version, labeling it exactly as it was before (v1, v2-beta, etc.)
3. Mark the version that should be the default landing page

Your per-version URLs are yourslug.docs.outworx.io/v1, yourslug.docs.outworx.io/v2-beta — usually the same path shape your old provider used, which is critical for the next step.

Step 4 — Migrate the custom domain (5 minutes)

If your docs lived at docs.yourcompany.com, you want to keep it.

On Outworx (Business plan, $19/mo):

1. Settings tab → Custom domain → enter docs.yourcompany.com
2. Copy the CNAME target we show you (it's our Vercel endpoint)

On your DNS provider (Cloudflare, Route 53, etc.):

1. Find the existing CNAME for docs.yourcompany.com — it currently points at readmedocs.com or mintlify.app
2. Change it to point at the Outworx target. Don't delete and re-add — just edit so the TTL stays short and propagation is instant.
3. On Cloudflare specifically: set proxy to DNS only (grey cloud). Outworx provisions its own SSL; the orange proxy will double-encrypt and break things.

Wait 1-5 minutes for propagation. Outworx polls and auto-provisions a Let's Encrypt cert as soon as the CNAME resolves. You'll see a green "Verified" badge in the dashboard.

Your custom domain now serves from Outworx. Cost went from $99-$150/mo to $19/mo.

Step 5 — Handle old URLs so you keep your SEO (3 minutes)

This is the step most migration guides skip, and it's the one that matters most for traffic-bearing docs.

Google has indexed your endpoints at the old URL shape. If you just redirect the root and let individual endpoint pages 404, you lose months of ranking.

If your old provider used the same path shape as Outworx (most do — /docs/<slug>/<endpoint-id> or similar), just point the custom domain and you're done. Existing backlinks keep working.

If the shapes differ (e.g. ReadMe uses /reference/listPosts but Outworx uses /endpoints/listPosts), set up redirects. The simplest way:

1. Keep the old subdomain on the old provider for 30 days
2. Add a Cloudflare Page Rule (or equivalent) redirecting old paths to new ones:

docs-old.yourcompany.com/reference/* → docs.yourcompany.com/endpoints/$1

3. After 30 days, Google has reindexed. Cancel the old provider.

This also gives you a rollback window if you spot something missing.

Step 6 — Wire the MCP server (1 minute — optional but worth it)

Neither ReadMe nor Mintlify ship a per-project Model Context Protocol server. Outworx does, on every Pro and Business project.

Open the MCP tab, copy the Claude Desktop or Cursor snippet, and paste it into your MCP client config. Now your customers (and your own team) can plug your API docs straight into their AI assistant — endpoint listing, typed-client generation, live calls, all through one URL. Details in our Connect Your API Docs to Claude Desktop via MCP guide.

What you lose by switching

Honest trade-offs:

• Custom MDX guide pages: not yet supported on Outworx (coming soon). If your docs include a lot of hand-written prose tutorials, plan to port those manually or hold off until the MDX pages feature ships.
• Proprietary auth/SSO integrations: ReadMe has some niche enterprise auth plugins. Outworx supports magic-link and OAuth (GitHub/Google) on the reading side; password-protected docs on paid tiers.
• Very high-scale plans: if you serve 10M+ monthly pageviews on docs, chat with us before migrating — we'll confirm the infra handles your load.

What you gain

• 5-15x cheaper: $9/mo Pro vs $99/mo ReadMe Growth. $19/mo Business vs $150/mo Mintlify Pro.
• Minute-one AI: the AI chat drawer works the instant your spec is uploaded. No extra config.
• MCP server per project: unique in this category. Your users get a native integration path to Claude, Cursor, and Cline.
• Self-healing types: when your spec is incomplete, MCP's live-call sampling infers response schemas and keeps generated TypeScript accurate.
• Auto-sync from spec URL: set it and forget it. Your docs stay in lockstep with your API.

Rollback plan

If something goes wrong:

1. Point the CNAME back at your old provider (2-5 min)
2. Tell support info@outworx.io — if it's a spec parsing bug, we usually fix it within the hour

The whole migration is non-destructive. Your old provider still has a copy of your spec until you cancel, and your Outworx account stays free until you deliberately upgrade.

Ready?

Start your Outworx Docs account (no card required) and follow the steps above. If you get stuck, email info@outworx.io — it comes to a real person who'll help you migrate the same day.