docs: redirect /pricing and close the remaining agentic-readiness gaps

[shirgoldbird]

Adds the /pricing redirect to deepl.com/pricing and works through the Is Agentic audit findings (81/100), keeping only the ones this repo can actually change.

What I found first

Two things changed the shape of this work.

head is not a valid docs.json property. Every branch of mintlify.com/docs.json sets additionalProperties: false and none lists head, so the whole block, including the rich Organization JSON-LD added in #425, was silently dropped. The live page has zero occurrences of contactPoint, address, or faxNumber. The root .css/.js files it referenced are auto-inlined by Mintlify from the repo root, so nothing depended on it.

Several findings are already satisfied, or are not about this site. Vary on the markdown-negotiated response is now rsc, Accept, User-Agent, so finding 3 is closed upstream. api.deepl.com does return JSON errors: an unauthenticated POST /v2/translate gives a 403 with {"message":"Missing Authorization header... You can find more info in our docs: .../auth"} plus an X-Trace-ID header. The spec already had 62 operations with unique operationIds, summaries, and descriptions, and 4xx/5xx responses on every one.

Changes

Finding	What changed
/pricing	Redirects to https://www.deepl.com/pricing
5, agent instruction / when-to-use	New AGENTS.md, served at /AGENTS.md and /AGENTS: job-to-endpoint table, when to use something else, base URLs, auth, spec URLs, error contract, throttling, contact. Linked from the 404 page and from markdown.instructions
2, JSON error responses	X-Trace-ID on all 22 error response components in the spec, a Retry-After header component on the response every 429 and 529 uses, and a response-headers table on the error handling page
6, rate-limit headers	Documents the convention the API actually follows: no RateLimit headers because the limit is dynamic, honor Retry-After, throttle from responses. In the spec, on the page, and in the markdown instructions
7 and 9, Organization / JSON-LD	Removed the dead head block. seo.organization now uses the #organization @id anchor and adds the Wikipedia sameAs
4, OpenAPI path	Short /openapi and /asyncapi redirects. Extension-less sources work; the existing /openapi.json entries cannot (see below)
8, function calling	Verified rather than changed: no duplicate or missing operationIds, all typed, now with documented error headers

Also in scope, found on the way:

• docs/getting-started/auth is now in the navigation. Every DeepL API auth error links to it, but it sat outside the navigation, so seo.indexing: navigable kept it out of the sitemap and llms.txt. An agent could follow the URL an error handed it but could never discover the page.
• Flattened the two redirect chains, so no redirect points at another redirect.

Tests

scripts/agentic-readiness.test.mjs, 28 tests, zero dependencies. It guards docs.json against unrecognized properties (the bug class above), redirect chains and dead destinations, the AGENTS.md sections and links, and the OpenAPI tool-definition and error-header invariants. The test workflow now runs on docs.json, AGENTS.md, and the spec files, not just scripts/.

Verification

• 28/28 tests pass
• docs.json validates against mintlify.com/docs.json: 3 errors before, 2 after, both pre-existing
• openapi.json regenerated with yq per CLAUDE.md; YAML and JSON parse equal
• Under mint dev: /pricing returns a 307 to the external URL, /openapi returns a 307, /AGENTS renders with one H1 and sequential headings, the auth page appears in the sidebar, and the custom CSS/JS injection counts are unchanged
• mint broken-links --check-anchors reports 44 findings, identical to main. All in pipeline/drafts/ except 4 pre-existing anchor issues
• The live API was probed directly to confirm every error and header claim before documenting it

Needs a decision or access, not code

1. Finding 1, content without JavaScript: platform-bound. The H2 before the H1 is Mintlify's own injected <blockquote class="sr-only" data-agent-docs-index> "Documentation Index". The 2.4% ratio is the Next.js shell, roughly 480KB of markup for 7.3KB of text. Neither is reachable from this repo, and padding the quickstart to chase a ratio would make the page worse. Needs a Mintlify request.
2. Finding 4, /openapi.json: needs an edge rewrite. Mintlify routes any path with a file extension as an asset and never consults the redirect table, which is why the existing /openapi.json and /api/openapi.yaml entries 404. This was already reverted once in e9a5eca. Options are a Cloudflare rewrite in front of developers.deepl.com, or moving the canonical file, which would break the public raw.githubusercontent.com URLs. The dead entries are left in place rather than expanding scope here.
3. Findings 7 and 9, contactPoint and address: blocked by Mintlify. seo.organization allows only id, name, legalName, url, logo, and sameAs, and a raw <script type="application/ld+json"> in MDX is stripped by the MDX pipeline. The address and contact points now live in AGENTS.md instead.
4. Finding 2 will probably stay failed unless the audit is pointed at api.deepl.com. The docs host serves no API of its own, so no in-repo change makes it return JSON errors.
5. Pre-existing bug, not touched here: footer.links[0].title should be header. As written, the "Resources" column heading is dropped from the footer. One-word fix, but it changes the visible footer, so it needs a design call.
6. Should /pricing be permanent: true? Left off to match the other 87 redirects.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
deepl-c950b784	🟢 Ready	View Preview	Sep 10, 2026, 10:10 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[shirgoldbird]

Verified on the preview deploy

All four checks pass, and Convert YAML specs to JSON committed nothing, so the yq regeneration in the commit matches CI's generator exactly.

Checked against deepl-c950b784-docs-agentic-readiness-round-2.mintlify.site:

Route	Result
/pricing	308 -> https://www.deepl.com/pricing
/openapi	308 -> /api-reference/openapi.yaml
/asyncapi	308 -> /api-reference/voice/voice.asyncapi.yaml
/agents	308 -> /AGENTS.md
/AGENTS.md	200 text/markdown, with the agent instructions prepended and the frontmatter rendered as # DeepL API instructions for AI agents plus a description blockquote
/AGENTS	200 text/html, one H1, sequential headings
/docs/getting-started/auth	200, and now listed in /llms.txt as "Access and authentication", which was the point of adding it to the navigation
/openapi.json	Still 404, as expected. Confirms the asset-route limitation in item 2 below rather than contradicting it

Also confirmed: Vary: rsc, accept-encoding, Accept, User-Agent on the Accept: text/markdown response, so finding 3 is closed. The custom CSS and JS are still inlined after removing the head block, so nothing regressed there.

Two corrections to the description:

• /pricing is already a 308, so permanent: true is unnecessary. Open question 6 can be dropped.
• The seo.organization change cannot be verified on a preview. Preview builds emit only Mintlify's own WebSite JSON-LD block; the @graph with the Organization node appears on production only, where I confirmed it before making the change. The new @id anchor and the Wikipedia sameAs will need a spot check on developers.deepl.com after merge. Note that contactPoint and address still will not appear, for the schema reason in item 3 of the description.

🤖 Generated with Claude Code