Mintlify

Mintlify Documentation Audit

Mintlify's docs are broad, well-structured, and unusually agent-aware — but the REST surface is split across three differently-named APIs (each base URL documented only per-endpoint, never in the introduction) with inconsistent error coverage, and the company's own llms.txt — the exact feature it sells — omits live pages it claims to list.

1. Error responses are inconsistently documented across the API surface — and 401/403/404/500 appear nowhere (critical)

Location: /docs/api/update/trigger, /docs/api/update/status, /docs/api/agent/v2/create-agent-job

Problem: Error documentation coverage is contradictory within the same REST surface. create-agent-job documents 400 and 429 (with a one-field Error schema, error: string). trigger documents only 202. status documents only 200. Across every endpoint, there is no documented 401, 403, 404, or 500 — despite the docs elsewhere relying on auth failures and 404s (auth denial "will receive a 404 error"). The introduction page defines no general error/status-code policy.

Consequence: A developer polling update-status or triggering a deployment has zero documented failure behavior — they cannot tell a real outage from an auth error from a bad statusId, and they can't write retry/error-handling logic against an undocumented contract. Agents generating client code will omit error handling entirely because the spec implies only success responses exist.

The fix: Document the full response set (at minimum 400/401/403/404/429/500) consistently on every endpoint, and add a single "Errors" page to the API section describing the shared Error schema and status-code semantics.

2. Three distinct REST APIs with three base URLs — documented per-endpoint but absent from the API introduction (significant)

Location: /docs/api/introduction (and per-endpoint OpenAPI blocks)

Problem: The API introduction lists endpoints and key prefixes but documents no base URL at all. The base URLs differ per endpoint and are present only in each endpoint's embedded OpenAPI servers block: create-agent-job declares title: Mintlify Admin API (v2.0.0) at https://api.mintlify.com; trigger/status declare title: Mintlify External API (v1.0.0) at https://api.mintlify.com/v1; the assistant message endpoint declares title: Mintlify Assistant API (v1.0.0) at https://api.mintlify.com/discovery. Three differently-named APIs with three roots, presented as one "Mintlify REST API."

Consequence: A developer reading the introduction has no base URL to construct a request and must open an endpoint page to find one. Worse, there's no signal anywhere that the host/path prefix changes between endpoint groups (/v1 vs the admin root vs /discovery), so anyone who carries one base URL across the "REST API" will silently build broken requests against the wrong root — and the resulting 404 isn't a documented response (see Finding 1).

The fix: Add a "Base URLs" table to /api/introduction mapping each endpoint group to its host and path prefix, and reconcile the three OpenAPI title values so it's clear whether these are one API or three products.

3. The auto-generated llms.txt is missing live pages despite claiming to list "all available pages" (significant)

Location: /docs/llms.txt and /docs/ai/llmstxt

Problem: The feature page /docs/ai/llmstxt states Mintlify "automatically hosts an llms.txt file at the root of your project that lists all available pages in your documentation. This file is always up to date and requires zero maintenance." Yet the live /docs/changelog page ("Product updates") returns HTTP 200, is a top-level nav tab alongside Documentation / Guides / API reference, and is absent from /docs/llms.txt (only the how-to pages "Changelogs" and "Update" appear). The deprecated-but-still-linked v1 endpoint page create-assistant-message.md is likewise missing from the index.

Consequence: This is a dogfooding failure on the exact promise the product makes. An AI agent indexing Mintlify's own docs via llms.txt — the intended consumer — will never discover the Product Updates / changelog page, and customers reasonably infer their own generated llms.txt is similarly incomplete. The "lists all available pages" guarantee is falsifiable from Mintlify's own output. (This is a credibility/accuracy failure on the flagship feature, not a request-blocking one — hence significant rather than critical.)

The fix: Either include all navigable pages (changelog, deprecated-but-linked endpoints) in the generated llms.txt, or soften the feature-page claim to describe exactly which page types are included/excluded (e.g., "excludes changelog and deprecated pages"). Don't promise "all available pages" while shipping a counterexample.

4. Request rate limits are scattered across three pages with no central reference and incompatible scopes (significant)

Location: /docs/api/agent/v2/create-agent-job, /docs/api/assistant/create-assistant-message-v2, /docs/ai/model-context-protocol (intro: /docs/api/introduction)

Problem: Request-throughput limits are defined in at least three places with no canonical reference and mismatched scoping units: agent-job says "100 uses per Mintlify project per hour"; the assistant endpoint says "10,000 requests per Mintlify organization per hour" and "10,000 requests per IP per day"; the MCP page lists yet another table (5,000/hr per user IP, 10,000/hr search per domain, 5,000/hr authenticated search per domain, etc.). The limits are variously scoped per-project, per-organization, per-IP, and per-domain. (Separately, the introduction's "up to 10 API keys per hour per organization" is a key-creation/account limit, a different limit class — and is the only limit the introduction mentions.)

Consequence: A developer cannot reason about their total budget because the limiting dimension changes per endpoint, and there's no single page to consult. An agent batching requests has no consistent throttle target and will hit 429s it can't predict — especially since 429 is documented on only one of the endpoints (see Finding 1).

The fix: Add a single "Rate limits" reference page summarizing every request limit with its scope (project / org / IP / domain), distinguish it clearly from the API-key-creation limit, and link to it from each endpoint instead of restating ad-hoc numbers per page.

5. The assistant v2 endpoint contradicts itself on AI SDK version (significant)

Location: /docs/api/assistant/create-assistant-message-v2

Problem: The prose states the endpoint is "compatible with AI SDK v5+" and "If you use AI SDK v4, use the [assistant message v1 endpoint]." But the install command in the same page pins AI SDK v6: npm i ai@^6 @ai-sdk/react. So the stated compatibility floor (v5+) and the pinned install (^6) disagree, and the v1 page it points to pins ai@^4.1.15 with a different import (from 'ai/react' vs from "ai").

Consequence: A developer on AI SDK v5 reads "compatible with v5+," runs the documented install, and is silently upgraded to v6 — or, if they hold at v5, they're unsure whether the snippet (which imports DefaultChatTransport from "ai") even works. An agent copy-pasting the block will pin ^6 while the surrounding text says v5, producing an unexplained version mismatch.

The fix: Make the install command match the stated compatibility (ai@^5 if v5+ is supported, or change the prose to "v6+"), and add a short compatibility table mapping endpoint version → supported AI SDK range → import path.

6. The current assistant endpoint routes AI SDK v4 users to a Deprecated endpoint (significant)

Location: /docs/api/assistant/create-assistant-message-v2 → /docs/api/assistant/create-assistant-message

Problem: The live v2 page instructs "If you use AI SDK v4, use the [assistant message v1 endpoint]" and links to create-assistant-message, which is itself marked Deprecated at the top of the page. So the recommended path for a still-supported use case (AI SDK v4) points directly at a deprecated API, with no inline note on the v2 page that the target is deprecated.

Consequence: A developer on AI SDK v4 follows the official pointer and builds against a deprecated endpoint without warning — they don't see the "Deprecated" banner until after they click through, and an agent following the link will generate v1 client code with no deprecation signal. When v1 is eventually removed, those integrations break with no migration runway.

The fix: On the v2 page, mark the v1 link as deprecated inline and recommend upgrading AI SDK to v5+ as the primary path; if v1 must remain the v4 route, state its deprecation status and removal expectations at the point of the recommendation.

7. The CLI commands page advertises mint build, which is documented nowhere (significant)

Location: /docs/cli/commands

Problem: The page's own description reads: "Complete reference for every Mintlify CLI command and flag, including mint dev, mint build, mint validate, mint analytics, and more." But there is no mint build command anywhere in the reference. The actual documented commands are: dev, login, logout, status, analytics, config, broken-links, a11y, validate, export, score.

Consequence: A developer who runs mint build (because the page that claims to be the "complete reference for every command" told them it exists) gets an error, with no explanation of what to run instead. This also undermines confidence in the "complete reference" framing.

The fix: Remove mint build from the description if it doesn't exist, or add the command's documentation. Decide whether the deploy/build step is mint dev + git push (per the quickstart) and say so explicitly.

8. The migration page advertises GitBook migration it doesn't actually support (significant)

Location: /docs/migration

Problem: The page description promises migration "from Docusaurus, ReadMe, GitBook, or another platform with step-by-step instructions and CLI tooling." But the body's "Choose your migration path" only lists Docusaurus and ReadMe under Automated migration; GitBook is not specifically supported and falls through to "any other platform → Manual migration."

Consequence: A GitBook user lands here expecting first-class automated tooling (the headline named their platform), then discovers they're in the generic manual path. This is exactly the kind of named-platform promise that drives a migration decision and then disappoints after commitment.

The fix: Either add real GitBook automated-migration support/instructions, or remove GitBook from the description and explicitly state under Manual migration which named platforms are handled there.

9. The llms.txt feature page contradicts itself on page ordering (minor)

Location: /docs/ai/llmstxt

Problem: The structure section states the file "lists your pages alphabetically in the order they appear in your repository." Alphabetical order and repository order are two different orderings; the sentence asserts both at once for the same file.

Consequence: A developer or agent trying to predict, diff, or validate the generated llms.txt can't tell whether entries are sorted alphabetically or follow repository/navigation structure — so they can't confirm their generated file is correct, and tooling that assumes one ordering may flag false diffs.

The fix: State the single actual ordering precisely (e.g., "alphabetically within each repository directory, traversed from the root") and drop the contradictory phrasing.

10. Two different $HOME config directories are referenced without explaining the distinction (minor)

Location: /docs/cli/install, /docs/cli/commands, /docs/cli/preview

Problem: install.md troubleshooting tells users to "delete the ~/.mintlify folder" to fix preview issues. But commands.md and preview.md state credentials and config save in ~/.config/mintlify/config.json. Two distinct directories under $HOME (~/.mintlify vs ~/.config/mintlify) are referenced with no explanation of which holds what.

Consequence: Deleting ~/.mintlify is the documented, safe cache fix and never touches ~/.config/mintlify, so credentials aren't actually at risk — but a user can't know that from the docs and may fear the cleanup wipes their login, or hesitate to run the documented fix. An agent automating cleanup has no way to know these are separate cache vs. config locations.

The fix: State explicitly that ~/.mintlify is a cache directory and ~/.config/mintlify/config.json holds credentials/config, and reference both by their full distinct paths wherever cleanup is suggested.

11. Authentication denial returns 404, which can silently chain into the default 404 auto-redirect (minor)

Location: /docs/deploy/authentication-setup and /docs/organize/settings-reference

Problem: The auth docs state that a user lacking a required group "will receive a 404 error" (not a 403). Separately, the docs.json schema reference shows errors.404.redirect defaults to true (auto-redirect on 404). The interaction between "access denied = 404" and "404 = auto-redirect" is never discussed.

Consequence: A developer configuring group-based access may not realize that a denied user isn't shown an access error at all — they're 404'd and then potentially auto-redirected by the default 404 behavior, making access-control failures hard to diagnose from the user's side or in logs.

The fix: Document the deliberate "denied → 404" choice alongside errors.404.redirect, and note how the two interact (e.g., whether denied users get redirected) so operators can predict the end-user experience.

12. The migration page mixes two scraper invocation styles for the same tool (minor)

Location: /docs/migration

Problem: The page installs the package as @mintlify/scraping (npm install @mintlify/scraping@latest -g) but then invokes it two different ways: a global binary mintlify-scrape section ... / mintlify-scrape page ..., and elsewhere npx @mintlify/scraping@latest openapi-file -o. The package name, the binary name, and the npx invocation are three different strings.

Consequence: A reader can't tell whether the command is mintlify-scrape, @mintlify/scraping, or something run via npx, and an agent extracting the command may call a binary name that doesn't match the installed package.

The fix: Standardize on one invocation style (or explicitly note that mintlify-scrape is the binary provided by the @mintlify/scraping package) and use it consistently across all examples on the page.

13. Credit pricing tiers are hard-coded on a page that also tells you to look elsewhere for current pricing (minor)

Location: /docs/credits

Problem: The page renders a full hard-coded pricing table (10 tiers from $0 to $10,000, overage at $0.01/credit, 50% rollover) while also linking out to the Pricing page for "the most current pricing."

Consequence: Two sources of truth for the same numbers means they can drift; a developer budgeting against the docs table may quote figures that no longer match the live pricing page, and there's no "last updated" signal to tell which is authoritative.

The fix: Either generate the credits table from the same source as the pricing page, or replace the hard-coded tiers with a single canonical link and keep only the formulas (overage rate, rollover %) that change less often.

14. Two similarly named, security-critical expiration fields are easy to conflate (minor)

Location: /docs/deploy/authentication-setup

Problem: The user-data format defines two expiration concepts with near-identical names: expiresAt (session length, "hours to weeks") and the JWT exp claim, which the docs say should be "a short duration (10 seconds or less) for security." The distinction — and the security-critical 10-second guidance — appears only in a sub-note under expiresAt ("This differs from the JWT's exp claim...").

Consequence: A developer scanning the field list can easily set the JWT exp to their intended session length (hours/weeks), defeating the short-lived-token security guidance, or set expiresAt too short. The two fields control different things but read as synonyms, and the safety guidance is buried where a reader skimming the schema can miss it.

The fix: Surface the "exp ≤ 10s for security" guidance at the same prominence as the field definitions (not in a sub-note), and add a short "which field to set, and to what" table pairing exp vs expiresAt.

15. A localized (i18n) docs surface exists but is undocumented and absent from the index (minor)

Location: /docs/llms.txt and /docs/api/assistant/create-assistant-message

Problem: The deprecated v1 endpoint page's "Related topics" link to localized variants /docs/fr/api/assistant/create-assistant-message-v2.md and /docs/zh/api/assistant/create-assistant-message-v2.md, revealing French and Chinese documentation surfaces. None of these localized pages appear in the English /docs/llms.txt index, and the localization surface isn't documented anywhere in the scraped material.

Consequence: Given that the product's whole pitch is index completeness for agents, an agent indexing via llms.txt has no way to discover that localized docs exist, and a developer can't tell which content is translated or how to reach a per-locale index.

The fix: Document the localization surface, and either include localized pages in llms.txt or publish (and link to) per-locale llms.txt indexes so agents can discover them.

What they do well

• Genuinely agent-aware structure — .md versions of every page, embedded OpenAPI per endpoint, a search MCP server with .well-known discovery documents, and mint score for agent-readiness checks. The intent to serve AI consumers is real and ahead of most docs.
• Strong docs.json schema reference — every property with type, default, and required badge, including non-obvious couplings (e.g., disabling telemetry also disables feedback features).
• Honest deprecation signposting — the v1 assistant endpoint is clearly marked Deprecated with a forward link to v2, and mint openapi-check is explicitly noted as superseded by mint validate.

Top 3 recommendations

1. Document a real error contract — at minimum 400/401/403/404/429/500 on every endpoint plus a shared "Errors" page. Today only one endpoint admits failure responses exist; this is the single finding that breaks error-handling code developers actually ship.
2. Unify the API reference — one base-URL table in the introduction, reconciled OpenAPI titles, and one rate-limits page covering project/org/IP/domain scopes. Right now the "REST API" is three differently-named APIs with base URLs you can only find by opening each endpoint.
3. Fix the headline-vs-body mismatches — mint build (advertised, undocumented), GitBook migration (advertised, unsupported), the AI SDK v5-vs-^6 install conflict, v4 users routed to a deprecated endpoint, and an llms.txt that promises "all available pages" while omitting its own changelog. Each is a case where the headline promises what the body doesn't deliver.