Reverse proxy - Mintlify

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. In all configurations, use mintlify.site 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>.mintlify.site<your-base-path>, like <your-subdomain>.mintlify.site/docs. Proxy to <your-subdomain>.mintlify.site so cache invalidation and updates take effect.

Routing configuration

Proxy these paths to your Mintlify subdomain:

Path	Destination	Caching
`/docs`	`<your-subdomain>.mintlify.site/docs`	No cache
`/docs/*`	`<your-subdomain>.mintlify.site/docs/*`	No cache
`/.well-known/vercel/*`	`<your-subdomain>.mintlify.site/.well-known/vercel/*`	No cache
`/.well-known/skills/*` (optional)	`<your-subdomain>.mintlify.site/docs/.well-known/skills/*`	No cache
`/.well-known/agent-skills/*` (optional)	`<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/*`	No cache
`/skill.md` (optional)	`<your-subdomain>.mintlify.site/docs/skill.md`	No cache
`/llms.txt` (optional)	`<your-subdomain>.mintlify.site/docs/llms.txt`	No cache
`/llms-full.txt` (optional)	`<your-subdomain>.mintlify.site/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, so 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>.mintlify.site/docs/llms.txt, so they are available on your domain under your subpath, like your-domain.com/docs/llms.txt, through your main subpath route. 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. Note that 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>.mintlify.site
X-Forwarded-For: Preserves client IP information
X-Forwarded-Proto: Preserves original protocol (HTTP/HTTPS)
X-Real-IP: Forwards the real client IP address
User-Agent: Forwards the user agent

Ensure that the Host header is not forwarded.

Example nginx configuration

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

    # Vercel verification paths
    location ~ ^/\.well-known/vercel/ {
        proxy_pass https://<your-subdomain>.mintlify.site;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site/docs/.well-known/skills/;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site/docs/.well-known/agent-skills/;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site/docs/skill.md;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site/docs/llms.txt;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site/docs/llms-full.txt;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site/docs/;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        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>.mintlify.site<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>.mintlify.site.

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>.mintlify.site)

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.

​Set your base path

​Host at /docs subpath

​Routing configuration

​Required header configuration

​Example nginx configuration

​Custom subpath

​Troubleshooting

​Changes not appearing

​404 error

​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

Performance issues