Mintlify's docs are unusually well-maintained — fresh changelog, zero dead internal links in a 162-link sample, full llms.txt/Markdown-export infrastructure — but the API reference contradicts its own security guidance, under-documents error responses in its published OpenAPI specs, and scatters rate limits across the wrong pages.
1. Recommended assistant integration embeds the API key client-side, contradicting the docs' own security warning (critical)
Problem: The page presents the useChat hook as "the recommended way to integrate the assistant API into your application," and the primary code example is a browser React component that sends the key directly from the client: Authorization: Bearer ${process.env.PUBLIC_MINTLIFY_ASSISTANT_KEY}``. A PUBLIC_-prefixed environment variable is, by convention, inlined into the client bundle — exactly the pattern the API introduction page explicitly forbids: "Do not directly embed the assistant API key in client-side code. Any visitor who extracts the key can call the assistant message endpoint on your behalf, consuming credits and potentially triggering overage charges." The assistant-embed tutorial agrees with the warning ("This tutorial keeps the key server-side using a backend proxy so it never reaches the client bundle... Avoid the VITE_ prefix, which bundles the value into your client code"). The only proxy caveat on the endpoint page itself is buried in the OpenAPI security-scheme description at the very bottom.
Consequence: A developer (or an AI coding agent) who lands on the endpoint reference — the most likely destination for "how do I call this API" — copies the recommended snippet and ships a billable, rate-limited secret in their JavaScript bundle. The docs elsewhere say this leads to key extraction, quota theft, and overage charges. Agents are especially vulnerable: they extract the first complete example and won't reconcile it with a warning on a different page.
The fix: Rewrite the useChat example to point api: at a same-origin backend proxy route (as the assistant-embed tutorial does), and move the "proxy in production, never embed the key client-side" warning into a visible <Warning> at the top of the endpoint page instead of the OpenAPI scheme description.
2. Trigger update's rate limit is documented only on a different endpoint's page (significant)
Problem: The Trigger update endpoint page contains no rate limit section at all — the page body is just the summary, "Authenticate with an admin API key," and the embedded OpenAPI block. The limit exists, but it is documented on the Trigger automation page: "This endpoint shares a rate limit with Trigger update: up to 10 requests per 10 seconds per organization." Meanwhile sibling endpoints document their own limits in place (Trigger preview deployment: "This endpoint allows up to 5 requests per minute per organization"; Create agent job: "100 uses per Mintlify project per hour"), so a reader has every reason to assume the absence of a rate-limits section on Trigger update means there is no limit.
Consequence: The docs pitch Trigger update for "Automated deployments: Trigger site updates at set intervals" and CI/CD pipelines — exactly the callers that will burst past 10 requests/10 seconds and be throttled with no guidance on the page they'd consult to debug it.
The fix: Add the "Rate limits" section (10 requests per 10 seconds per organization, shared with Trigger automation) to the Trigger update page itself, matching the pattern used on the preview and agent endpoint pages.
3. Published OpenAPI specs document only success responses; documented failure modes never appear in the machine-readable contract (significant)
Problem: The platform spec ("Mintlify External API", served at /docs/openapi.json) declares POST /project/update/{projectId} with responses ['202'] only and GET /project/update-status/{statusId} with ['200'] only. No operation in the spec documents a 401 or 429 response. Yet the API introduction states, in prose, that expired keys "return a 401 response," IP-allowlist violations "return a 403 response," and scope violations "return a 403 response" — and the Trigger automation page documents a shared rate limit (10 requests per 10 seconds) whose enforcement responses are absent from the spec entirely. The preview and workflow operations document a partial error set (400/403 and 400/404 respectively), making the coverage inconsistent even within one spec.
Consequence: Anyone generating a client, retry logic, or tests from the published spec — including AI agents, which Mintlify explicitly courts — gets a contract that claims requests can only succeed. Auth failures, scope errors, and throttling all surface as "undocumented" responses, and generated clients won't model retry or key-rotation paths.
The fix: Add 401, 403, and rate-limit response objects (with error body schemas) to every authenticated operation in openapi.json and the sibling specs (admin-openapi.json, discovery-openapi.json, analytics.openapi.json), so the machine-readable contract matches the failure behavior the API introduction describes in prose.
4. Dead external link: the "agent-skills 0.2.0 discovery spec" host does not resolve (significant)
Problem: The page anchors its recommended discovery format to a spec link that is dead at the DNS level: "The /.well-known/agent-skills/ endpoint follows the agent-skills 0.2.0 discovery spec". schemas.agentskills.io returns NXDOMAIN (the apex agentskills.io resolves and serves 200, so the subdomain simply doesn't exist). The same unresolvable URL is also shown as the $schema value in the example index.json manifest, so it propagates into what implementers and validators will actually fetch.
Consequence: Developers evaluating the "recommended" discovery endpoint can't read the spec it claims to follow, and any tooling that dereferences the $schema URL for validation fails with a DNS error. For a feature aimed at programmatic agent consumption, the canonical machine-readable reference is unreachable.
The fix: Point the link and the example $schema at a URL that resolves (e.g., the spec location on agentskills.io), or host a copy of the schema; add this external URL to the broken-link checks that already keep internal links clean.
5. Deployment URL domain contradiction: .mintlify.app vs .mintlify.site (minor)
Problem: The help-center page states "Your subdomain identifies your deployment. It appears in your <subdomain>.mintlify.app URL" — the only .mintlify.app reference in the entire current corpus (1 of 90 domain mentions in llms-full.txt), while the quickstart and everything else say "Your documentation site is now deployed at https://<your-project-name>.mintlify.site" and instruct agents to "verify that https://<subdomain>.mintlify.site loads." Both mintlify.mintlify.app and mintlify.mintlify.site return HTTP 200, so nothing external disambiguates which is canonical.
Consequence: A developer following the rename help article while scripting against the quickstart's .mintlify.site URL can't tell whether these are two domains, one alias, or a stale page — and automation that string-matches the deployment URL (as the docs' own agent workflow instructs) will check the wrong host.
The fix: Standardize on one domain across all pages (or add one sentence explaining that both resolve and which is canonical), and update the help-center page to match the quickstart.
6. Same endpoint named "Trigger deployment" and "Trigger update" depending on where you read (minor)
Problem: The endpoint page's H1 and its llms.txt entry call it "Trigger deployment," but the OpenAPI summary embedded on that very page says "Trigger update," and the Trigger automation page cross-references it as "Trigger update." Two names for one operation — including both names on one page.
Consequence: Developers and agents searching or cross-referencing by name get inconsistent hits: searching "Trigger update" doesn't obviously match the page titled "Trigger deployment," and an agent reconciling llms.txt entries against cross-references elsewhere sees what looks like two different endpoints.
The fix: Pick one name and apply it to the page title, the OpenAPI summary, the llms.txt description, and all cross-references.
7. llms.txt lists API spec links as root-relative paths while every page link is absolute (minor)
Problem: All 180 page links in llms.txt are fully-qualified URLs (https://www.mintlify.com/docs/...), but the spec links at the bottom are root-relative: - [openapi](/docs/es/openapi.json), - [asyncapi](/docs/asyncapi.yaml), etc. Mintlify's own llms.txt documentation positions the file as something AI tools fetch and follow to discover content.
Consequence: An agent that fetched llms.txt (possibly via a proxy, mirror, or with only the file contents in context) has no base URL to resolve /docs/openapi.json against, so the most machine-valuable links in the file — the API specs — are the only ones that can silently fail to resolve.
The fix: Emit the spec links as absolute URLs, consistent with the page links in the same file.
What they do well
Genuinely agent-ready infrastructure: llms.txt with recursive /_llms/ split indexes, a full llms-full.txt, a .md Markdown export of every page, and discovery headers on every response.
Link hygiene and freshness: all 162 sampled internal links and all 7 published spec URLs return 200, and the changelog's newest entry is days old.
Auth is concretely specified: three key types with distinct prefixes (mint_, mint_dsc_, mint_us_), scopes, IP allowlists, expiration behavior, and per-key security posture in one table.
Top 3 recommendations
Fix the useChat example on create-assistant-message-v2 to route through a backend proxy, and surface the client-side-key warning on that page — the current recommended snippet is the exact anti-pattern the docs warn about.
Bring the OpenAPI specs up to the prose contract: add 401/403 and rate-limit responses to authenticated operations, and put Trigger update's rate limit on its own page.
Repair the dead schemas.agentskills.io spec link and reconcile the .mintlify.app/.mintlify.site and "Trigger deployment"/"Trigger update" naming splits.