Migrate from Mintlify to Outworx Docs

Mintlify is great for narrative documentation but the bill compounds fast: $150/mo for the team plan, separate add-ons for AI features, and per-editor seats once you outgrow the starter tier. If your product is API-first and you mostly need a renderer for OpenAPI plus an AI assistant, Outworx Docs covers the same ground for $9–$19/mo with no seat math.

This guide walks the migration end-to-end: getting your spec out, mapping Mintlify's MDX-driven structure onto Outworx, preserving SEO, and what to do with your guide pages.

Step 1 — Locate your spec (2 minutes)

Mintlify usually keeps your OpenAPI definition as a file in your docs repo (openapi.yaml or openapi.json), referenced from mint.json.

# Most Mintlify repos have a spec file at the root
ls api/openapi.yaml openapi.yaml openapi.json 2>/dev/null

If you've been editing the spec in Mintlify's web editor instead of git, click Download in the dashboard to grab the current snapshot, then commit it to your repo. You want git as the source of truth before going further.

Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at docs.outworx.io. Free tier, no card.
2. New Project → name it after your API → pick a slug. URL becomes yourslug.docs.outworx.io.
3. API Spec tab → Upload → drag in openapi.yaml.

Docs go live instantly. Endpoints, parameters, examples, the Try It playground — all working against your real API.

Step 3 — Decide what to do with your MDX guides

This is the one Mintlify-specific decision. Mintlify mixes API reference (rendered from OpenAPI) with hand-written MDX guide pages (introduction.mdx, quickstart.mdx, etc.) in the same site.

Outworx Docs is API-reference-first. Two reasonable paths:

Path A — keep Mintlify alive for guides only. Move the API reference to Outworx (the expensive part), keep Mintlify on its cheapest tier ($24/mo) for your narrative docs. Set a Guides link in your top nav pointing to guides.yourcompany.com (Mintlify) and an API Reference link pointing to api.yourcompany.com (Outworx). Net cost: $24 + $19 = $43/mo, vs. $150/mo all-Mintlify.

Path B — host guides on Outworx's /guides hub. We support long-form MDX-style content at /guides/<slug>. Migrate each .mdx file as-is. Currently this requires a small content commit on our side (we ship guides via the registry); reach out at info@outworx.io and we'll set it up. Net cost: $19/mo, single domain, single login.

Most teams do Path A initially, then migrate to Path B once the API reference has been live for 30 days and they're sure they want everything on one platform.

Step 4 — Preserve versions (3 minutes)

If your Mintlify site had multiple API versions:

1. API Spec tab → New version
2. Upload the spec for each old version
3. Label them exactly as they were (v1, v2-beta, …)
4. Mark the default

URLs become yourslug.docs.outworx.io/v1, yourslug.docs.outworx.io/v2-beta. The version switcher renders on every public docs page automatically.

Step 5 — Migrate the custom domain (5 minutes)

If your docs live at docs.yourcompany.com:

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

1. Settings → Custom domain → enter your domain
2. Copy the CNAME target

On your DNS provider:

1. Edit the existing CNAME (currently pointing at mintlify.app or similar)
2. Point it at Outworx's target
3. Cloudflare: set the record to DNS only (grey cloud). Outworx provisions its own SSL — orange-cloud proxy will conflict.

Wait 1–5 minutes. SSL provisions automatically. Done.

Step 6 — SEO and redirects (3 minutes)

Mintlify path shape is typically /api-reference/v1/listUsers. Outworx is /endpoints/listUsers with the version on the subpath. Different shape → you need redirects to keep your search rankings.

Recommended: keep the old Mintlify subdomain alive for 30 days, set up a Cloudflare Page Rule:

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

Cancel Mintlify after Google has reindexed (~30 days). You'll see new pages in Search Console within 1–2 weeks.

What you actually gain

• Per-project MCP server. Mintlify doesn't ship one. Outworx Docs gives every Pro+ project a Model Context Protocol server — Claude, Cursor, Cline plug straight in.
• AI chat included. Mintlify's AI assistant is a separate add-on. Outworx bakes it into Pro and Business at no extra cost.
• Localhost dev loop. Run npx outworx-proxy, hit Send Request from the docs UI, the proxy routes through to your localhost:3000. CORS just works. No equivalent on Mintlify.
• No per-seat billing. Pro includes 3 collaborator seats, Business includes 10. Mintlify's team plan starts at $150/mo before per-seat upcharges.
• Plan inheritance. Invite a teammate who's still on Free, they get your project's full feature set when working on it. No "upgrade them first" friction.

After the migration

Set up auto-sync so docs stay current: paste your spec URL, we fetch hourly / daily / weekly. Or push from CI — see Auto-sync API Docs from GitHub Actions on Every Push.

Then wire MCP for Claude / Cursor / Cline: Connect Your API Docs to Claude Desktop via MCP.

That's the migration. Fifteen minutes, maybe an hour if you're untangling guide pages alongside the API reference.

Start your migration →