The /api Namespace is Now Open

You can now create documentation pages at the /api path in your Mintlify docs. This means your API reference can live at /api/endpoint-name instead of /api-reference/endpoint-name, giving you cleaner URLs that match your actual API structure.

What This Enables

Previously, Mintlify reserved the /api path for internal endpoints, forcing API documentation to use alternative paths like /api-reference. This created a disconnect between your documentation URLs and the APIs they describe.

Now you can structure your docs.json navigation to put pages at /api/{route}, creating a more intuitive sitemap:

{
  "navigation": [
    {
      "group": "API Reference",
      "pages": ["api/users", "api/authentication", "api/webhooks"]
    }
  ]
}

Your documentation will be available at URLs like docs.yourcompany.com/api/users instead of docs.yourcompany.com/api-reference/users.

How App Router Made This Possible

This feature became available through Mintlify's migration from NextJS Pages Router to App Router.

The Pages Router Limitation

In Pages Router, the /pages/api/* directory is reserved exclusively for API routes. Any file placed in /pages/api/ automatically becomes a serverless function endpoint, not a page that can render documentation. This structural constraint meant:

• Users couldn't create documentation pages at /api/* because that entire namespace was reserved for API route handlers
• Mintlify's internal endpoints (playground requests, file uploads, OG image generation, cache revalidation) had to live in /pages/api/, blocking the path for everyone

There was no way to have both API endpoints and rendered pages coexisting under /api.

The App Router Solution

App Router changes this completely. Instead of entire directories being reserved for specific purposes, App Router uses explicit file naming:

• route.ts files define API endpoints
• page.tsx files define rendered pages

This means /app/api/users/route.ts can be an API endpoint while /app/api/authentication/page.tsx is a documentation page. They coexist in the same namespace because the file system is explicit about intent.

By moving Mintlify's internal endpoints to /app/_mintlify/api/*/route.ts, the entire /app/api/* namespace opened up for user-defined pages. The underscore prefix keeps internal routes clearly separated from user content while maintaining organization within the app directory structure.

Start Using /api Routes Today

Your API reference can now live at /api/{route} instead of /api-reference/{route}. Update your docs.json navigation to use /api paths and deploy, no other changes required.