Migrate from Stoplight to Outworx Docs

Stoplight is one of the more polished API design tools on the market — but the moment your team grows, the per-editor seat pricing and the Studio-tied workflow start to feel like a tax. If you mostly need a hosted API reference (not the full design + governance + linting suite), Outworx Docs is a cleaner fit at $9–$19/mo with no per-seat billing.

This guide moves your existing Stoplight docs onto Outworx in about twenty minutes.

Step 1 — Export your spec from Stoplight (3 minutes)

Stoplight stores your API definition as OpenAPI under the hood, regardless of whether you authored it in Studio or in their web editor.

Stoplight Platform (web):

1. Open the project
2. Click the API node in the left sidebar
3. Export menu → Download OpenAPI → pick JSON or YAML

Stoplight Studio (desktop app): Your spec is the file you've been editing the whole time. Look for openapi.yaml (or openapi.json) in your project folder. Studio uses git, so it's already source-controlled.

Multi-file specs ($ref to other files): If your project uses Stoplight's split-file convention (one OpenAPI per resource, stitched via $ref), bundle them into a single file before uploading:

npx @redocly/cli bundle openapi.yaml -o bundled.yaml

Outworx Docs accepts a single file. The bundle command from @redocly/cli resolves all $ref pointers and emits a flat document.

Step 2 — Upload to Outworx Docs (1 minute)

1. Sign up at docs.outworx.io. Free tier, no card.
2. New Project → name → slug. URL: yourslug.docs.outworx.io.
3. API Spec tab → Upload → drag in bundled.yaml (or your single-file spec).

Docs go live. Endpoints, parameters, examples, Try It — all working.

Step 3 — Recreate versions (3 minutes)

Stoplight versions become Outworx versions one-to-one.

For each version:

1. API Spec tab → New version
2. Upload the bundled spec
3. Label as it was (v1, 2024-01-01, etc.)
4. Mark the default

URL shape: yourslug.docs.outworx.io/v1. Version switcher renders on every public docs page.

Step 4 — Migrate the custom domain (5 minutes)

If your docs live at docs.yourcompany.com:

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

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

On DNS:

1. Edit the CNAME currently pointing at Stoplight's hosting
2. Point it at Outworx's target
3. Cloudflare: DNS only (grey cloud), not orange — Outworx handles SSL itself

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

Step 5 — Mocking & governance — what to keep, what to drop

This is where you want to be honest about what you actually use.

Stoplight features that don't have direct Outworx equivalents (yet):

• API mocking (Prism)
• Spectral linting / style guides
• Visual API design in Studio

If you use these heavily, keep Stoplight alive on its cheapest tier for design, then publish the resulting OpenAPI spec to Outworx for hosted documentation. The handoff is automatic if you wire up auto-sync — Outworx fetches your published spec URL on a schedule.

If you don't use them (most teams who design APIs in their backend frameworks don't), drop Stoplight entirely. Use a free Spectral CLI run in CI for linting, use your existing dev environment for mocking.

Step 6 — Redirects for SEO (3 minutes)

Stoplight's path shape is typically /docs/<workspace>/<api-id>/operations/<operation-id>. Outworx is /endpoints/<operation-id>. Different shape → set up redirects so Google doesn't drop your indexed pages.

Keep the Stoplight subdomain alive for 30 days. Add a redirect rule on your DNS or CDN:

docs-old.yourcompany.com/docs/*/operations/* → docs.yourcompany.com/endpoints/$2

After ~30 days, Search Console shows the new URLs indexed. Cancel Stoplight then.

What you gain by leaving Stoplight

• No per-editor pricing. Stoplight charges per editor seat once you scale. Outworx Pro includes 3 seats, Business includes 10. Flat fee.
• Per-project MCP server. Stoplight doesn't ship one. Outworx Docs gives every Pro+ project a Model Context Protocol server — your AI assistants can list endpoints, generate types, ask docs, and execute live calls grounded in your spec.
• AI chat for visitors. Stoplight has no built-in AI chat for the rendered docs. Outworx ships streaming AI chat trained on your spec, with citation pills that link back to the referenced endpoint.
• Localhost CORS proxy. npx outworx-proxy lets your Try It playground hit http://localhost:3000 from a hosted docs domain without CORS errors. Stoplight's playground hits this every time.
• Plan inheritance for collaborators. Invite a Free user to your Business project, they use Business features on it. Stoplight's licensing model can't express this — you upgrade everybody or nobody.

After the migration

Wire auto-sync from your spec URL: Auto-sync API Docs from GitHub Actions on Every Push.

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

If your localhost API hits CORS errors when you Try It from the hosted docs, the outworx-proxy package solves it in one terminal command.

Total time: about twenty minutes for the average team. Longer if you're untangling a multi-file Stoplight project, shorter if your spec was already a single bundled file in your repo.

Start your migration →