Migrate from ReadMe to Outworx Docs in 15 Minutes

If you're on ReadMe and the $99/mo Startup plan is starting to feel steep for what is, fundamentally, a renderer for your OpenAPI file — this guide gets you off it and onto Outworx Docs in about fifteen minutes. No data loss, no SEO regression, no per-seat invoices.

We'll cover: exporting your spec, preserving versions, migrating the custom domain, redirecting old URLs to keep your search rankings, and the things ReadMe doesn't ship that Outworx Docs does.

Step 1 — Export your spec (2 minutes)

ReadMe stores the source OpenAPI definition for every API version you've added.

1. Open the ReadMe dashboard
2. API Reference tab
3. Click the three-dot menu on your active version → Export OpenAPI

You get a .json file. Save it. Repeat for every version you want to keep (v1, v2-beta, etc.).

If you've been editing your spec inside ReadMe's web editor instead of in git, that exported JSON is your source of truth — commit it to your repo before going further. You don't want to lose hand-edits made over the past year because your only copy lived in a vendor dashboard.

Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at docs.outworx.io — free tier, no credit card.
2. Click New Project, name it after your API, pick a slug. This becomes your default URL: yourslug.docs.outworx.io.
3. API Spec tab → Upload → drag in the JSON.

Your docs go live immediately. Every endpoint, every parameter, every example. The Try It playground works against your real API the moment it's uploaded.

Step 3 — Recreate your versions (3 minutes)

ReadMe versions become Outworx versions one-to-one. Versions appear in a switcher on your public docs site, so existing customers reading /v1/users don't suddenly hit a 404 because you migrated.

For each exported file:

1. API Spec tab → New version
2. Upload the file
3. Label it exactly as it was on ReadMe (v1, v2-beta, …)
4. Mark the version that should be the default

URL shape: yourslug.docs.outworx.io/v1, yourslug.docs.outworx.io/v2-beta. This matches ReadMe's path conventions, which matters for Step 5.

Step 4 — Migrate the custom domain (5 minutes)

If your docs live at docs.yourcompany.com, keep them there.

On Outworx Docs (Business plan, $19/mo — vs ReadMe's $99/mo Startup, $399/mo Business):

1. Settings → Custom domain → enter docs.yourcompany.com
2. Copy the CNAME target

On your DNS provider:

1. Edit (don't delete) the existing CNAME pointing at readmedocs.com
2. Change it to point at Outworx's target
3. Cloudflare specifically: set proxy to DNS only (grey cloud). Outworx provisions its own Let's Encrypt cert; Cloudflare's orange-cloud proxy double-encrypts and breaks things.

Wait 1–5 minutes for propagation. Outworx polls and auto-issues SSL the moment the CNAME resolves. Green "Verified" badge appears in the dashboard.

Your custom domain now serves from Outworx. Bill drops to $19/mo.

Step 5 — Keep your SEO with proper redirects (3 minutes)

This is the step every migration guide handwaves and the one that costs you traffic if you skip it.

ReadMe paths look like /reference/listPosts. Outworx paths look like /endpoints/listPosts. Google has indexed the old shape; if endpoint pages 404 after the switch, your hard-earned rankings disappear.

Two safe paths:

Option A — keep the old ReadMe subdomain alive for 30 days. Run both in parallel. Add a Cloudflare Page Rule (or equivalent) redirecting old paths to new:

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

After Google reindexes (~30 days), cancel ReadMe.

Option B — accept a temporary dip. Skip redirects. Rankings recover in 4–8 weeks once Google sees Outworx serving canonical content. Cheaper, slightly more painful.

Most teams use Option A. The 30-day overlap is the cost of a clean migration.

What you gain by leaving ReadMe

• Per-project MCP server. ReadMe doesn't ship one. Outworx Docs gives every Pro and Business project a Model Context Protocol server — Claude Desktop, Cursor, and Cline can connect directly to your docs and operate your API.
• AI chat included. ReadMe charges extra for AI features. Outworx ships AI chat trained on your spec, on every public docs page, included in Pro and Business.
• Team seats included. ReadMe's higher tiers gate seats. Outworx includes 3 (Pro) or 10 (Business) collaborator seats with no per-seat billing.
• Localhost dev loop. npx outworx-proxy lets your Try It playground talk to localhost APIs through a CORS-bypass proxy. No equivalent on ReadMe.
• Pricing honesty. $9 Pro, $19 Business. No annual-only discount tier, no "Contact Sales" enterprise gating.

After the migration

Wire up auto-sync so the docs stay in lockstep with your repo. Either:

• Paste your spec URL into the project settings — we fetch on hourly / daily / weekly cadence
• Or push from CI: see Auto-sync API Docs from GitHub Actions on Every Push

Then connect your AI assistant via MCP: Connect Your API Docs to Claude Desktop via MCP.

That's the full migration. Most teams finish in under fifteen minutes if they don't have an unusual custom domain setup.

Start your migration →