Reverse proxy

To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding. When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking.

Set your base path

Set your base path on the Custom domain setup page in your dashboard. Then configure your reverse proxy to route that path to Mintlify. The default base path is /docs, but you can use any base path you choose, like /help or /resources. The directory that contains your documentation in your repository does not configure the public base path. For example, storing documentation under a /docs directory does not replace setting /docs as the base path in your dashboard. In all configurations, use mintlifysite.com as the proxy target.

Host at `/docs` subpath

Use this configuration when you want to serve documentation at the /docs path on your domain. Before configuring your reverse proxy:

Navigate to Custom domain setup in your dashboard.
Enable the Host at toggle.
Enter your domain.
Enter docs as your base path.
Click Add domain.

When you host at a subpath, your canonical docs URL becomes <your-subdomain>.mintlifysite.com<your-base-path>, like <your-subdomain>.mintlifysite.com/docs. Proxy to <your-subdomain>.mintlifysite.com so cache invalidation and updates take effect.

Routing configuration

Proxy these paths to your Mintlify subdomain:

Path	Destination	Caching
`/docs`	`<your-subdomain>.mintlifysite.com/docs`	No cache
`/docs/*`	`<your-subdomain>.mintlifysite.com/docs/*`	No cache
`/docs/_llms/*`	`<your-subdomain>.mintlifysite.com/docs/_llms/*`	No cache
`/.well-known/vercel/*`	`<your-subdomain>.mintlifysite.com/.well-known/vercel/*`	No cache
`/.well-known/skills/*` (optional)	`<your-subdomain>.mintlifysite.com/docs/.well-known/skills/*`	No cache
`/.well-known/agent-skills/*` (optional)	`<your-subdomain>.mintlifysite.com/docs/.well-known/agent-skills/*`	No cache
`/skill.md` (optional)	`<your-subdomain>.mintlifysite.com/docs/skill.md`	No cache
`/llms.txt` (optional)	`<your-subdomain>.mintlifysite.com/docs/llms.txt`	No cache
`/llms-full.txt` (optional)	`<your-subdomain>.mintlifysite.com/docs/llms-full.txt`	No cache

Your proxy must forward all HTTP methods on documentation paths. Mintlify sends analytics events as POST requests to /docs/_mintlify/api/v1/e. A proxy that only allows GET and HEAD requests silently breaks the analytics in your dashboard. Mintlify serves these files under your base path, like <your-subdomain>.mintlifysite.com/docs/llms.txt. They are available on your domain under your subpath, like your-domain.com/docs/llms.txt, through your main subpath route. The /docs/* route also covers generated llms.txt indexes under /docs/_llms/*. If your proxy uses a more granular path allowlist instead of forwarding all /docs/* requests, include /docs/_llms/* so agents can follow every index linked from /docs/llms.txt. Do not rewrite only /docs/llms.txt to a root-hosted /llms.txt. Set /docs as the deployment base path and forward the full /docs/* route. This keeps page links and generated /docs/_llms/* index links on the same public prefix. The /.well-known/skills/*, /.well-known/agent-skills/*, /skill.md, /llms.txt, and /llms-full.txt routes are optional. Include them only if you also want to serve these files at root paths on your domain, like your-domain.com/llms.txt. Each root path maps to the file under your base path on your Mintlify subdomain.

Required header configuration

Configure your reverse proxy with these header requirements:

Origin: Contains the target subdomain <your-subdomain>.mintlifysite.com.
X-Forwarded-For: Preserves client IP information.
X-Forwarded-Proto: Preserves the original protocol (HTTP/HTTPS).
X-Real-IP: Forwards the real client IP address.
User-Agent: Forwards the user agent.

Do not forward the Host header.

Example nginx configuration

server {
    listen 80;
    server_name <your-domain>.com;

    # Vercel verification paths
    location ~ ^/\.well-known/vercel/ {
        proxy_pass https://<your-subdomain>.mintlifysite.com;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # AI skills paths
    location ^~ /.well-known/skills/ {
        proxy_pass https://<your-subdomain>.mintlifysite.com/docs/.well-known/skills/;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Agent-skills discovery paths
    location ^~ /.well-known/agent-skills/ {
        proxy_pass https://<your-subdomain>.mintlifysite.com/docs/.well-known/agent-skills/;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Skill manifest (optional)
    location = /skill.md {
        proxy_pass https://<your-subdomain>.mintlifysite.com/docs/skill.md;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # LLM index files (optional)
    location = /llms.txt {
        proxy_pass https://<your-subdomain>.mintlifysite.com/docs/llms.txt;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    location = /llms-full.txt {
        proxy_pass https://<your-subdomain>.mintlifysite.com/docs/llms-full.txt;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Documentation root
    location = /docs {
        proxy_pass https://<your-subdomain>.mintlifysite.com;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # All documentation paths
    location /docs/ {
        proxy_pass https://<your-subdomain>.mintlifysite.com/docs/;
        proxy_set_header Origin <your-subdomain>.mintlifysite.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
}

Custom subpath

To use a subpath other than /docs (such as /help or /resources):

Navigate to the Custom domain setup page in your dashboard.
Enable the Host at toggle.
Enter your domain.
Enter your base path. For example, /docs or /help.
Click Add domain.

Mintlify rebuilds your documentation to serve at your base path, so <your-subdomain>.mintlifysite.com<your-base-path> serves your content. Configure your reverse proxy using the same routing configuration, header requirements, and nginx patterns as the /docs subpath, replacing /docs with your base path.

Troubleshooting

Changes not appearing

Symptoms: You publish documentation updates, but the changes don’t appear on your site. Cause: Your reverse proxy points to an outdated hostname. Solution: Update your reverse proxy configuration to point to <your-subdomain>.mintlifysite.com.

404 error

Symptoms: Documentation loads, but features don’t work. API calls fail. Cause: The reverse proxy forwards the Host header or the Origin header is missing. Solution:

Remove Host header forwarding.
Set the Origin header to your Mintlify subdomain (<your-subdomain>.mintlifysite.com).

Generated `/_llms/` links return 404

Symptoms: Your llms.txt file loads, but links under /_llms/ return 404 or omit your public subpath. Cause: The public subpath does not match the base path configured in Mintlify, or the proxy only forwards llms.txt and not its generated index routes. Solution:

Set the public subpath as the base path in your Mintlify dashboard. A repository directory with the same name does not configure it.
Forward the full <base-path>/* route, or add <base-path>/_llms/* to a granular allowlist.
Redeploy your documentation, then verify both <base-path>/llms.txt and one linked <base-path>/_llms/*.md URL.

Performance issues

Symptoms: Slow page loads and layout shifts. Cause: Incorrect caching configuration. Solution: Disable caching for documentation paths. If you proxy /mintlify-assets/_next/static/* paths, enable caching only for those static assets.

Get started

Create content

Manage your site

Agent

Assistant

Agent-ready content

Search and SEO

Document APIs

Integrations

Reference

Set your base path

Host at `/docs` subpath

Routing configuration

Required header configuration

Example nginx configuration

Custom subpath

Troubleshooting

Changes not appearing

404 error

Generated `/_llms/` links return 404

Performance issues

​Set your base path

​Host at /docs subpath

​Routing configuration

​Required header configuration

​Example nginx configuration

​Custom subpath

​Troubleshooting

​Changes not appearing

​404 error

​Generated /_llms/ links return 404

​Performance issues

Set your base path

Host at `/docs` subpath

Routing configuration

Required header configuration

Example nginx configuration

Custom subpath

Troubleshooting

Changes not appearing

404 error

Generated `/_llms/` links return 404

Performance issues