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