docs: remove API Reference overview pages, fold into endpoints by shirgoldbird · Pull Request #389 · DeepL/api-docs

shirgoldbird · 2026-07-07T20:57:32Z

Summary

Consolidate API Reference overviews: remove 12 standalone overview/narrative pages from the API Reference tab and fold useful content into the first endpoint page of each group.

Before: Each API product (Translate, Document, Glossaries, etc.) had a separate narrative overview page in the API Reference tab alongside the endpoint pages.

After: The overview pages are deleted. Any useful context (auth requirements, usage notes, workflow descriptions) is folded into the first endpoint page of each group as a short intro paragraph above the auto-rendered spec. The about.mdx page in the Documentation tab absorbs general product capability info.

Pages removed

api-reference/admin-api.mdx
api-reference/document.mdx
api-reference/glossaries.mdx
api-reference/improve-text.mdx
api-reference/jobs-voice-translate.mdx
api-reference/languages.mdx
api-reference/multilingual-glossaries.mdx
api-reference/quality-evaluation.mdx
api-reference/style-rules.mdx
api-reference/translate.mdx
api-reference/usage-and-quota.mdx
api-reference/voice.mdx

Pages updated

12 endpoint pages (first endpoint in each group) — short intro paragraph added
docs/getting-started/about.mdx — updated capabilities section
docs.json — removed overview page entries from navigation

How to review

Check out this branch and run mint dev to preview locally
Verify each API Reference group still renders correctly without the overview page
Confirm no broken internal links

Generated by the agentic docs pipeline (batch.py → rework → evaluate → review → promote)

…te-api-reference-overviews Generated 13 pages for: admin-api, document, getting-started, glossaries, improve-text, jobs-voice-translate, languages, multilingual-glossaries, quality-evaluation, style-rules, translate, usage-and-quota, voice - api-reference/admin-api/managing-admin-keys.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/document/upload-and-translate-a-document.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/glossaries/create-a-glossary.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/improve-text/request-text-improvement.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/jobs-voice-translate/create-voice-translate-job.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/languages/retrieve-languages-by-resource.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/multilingual-glossaries/create-a-glossary.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/quality-evaluation/submit.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/style-rules/list-all-style-rules.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/translate/request-translation.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/usage-and-quota/check-usage-and-limits.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - api-reference/voice/request-session.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference. - docs/getting-started/about.mdx: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overview. No more narrative pages in the API Reference.

mintlify · 2026-07-07T21:06:44Z

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

Project	Status	Preview	Updated (UTC)
deepl-c950b784	🟢 Ready	View Preview	Jul 7, 2026, 9:07 PM

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

Task [0]: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overv

shirgoldbird

Pipeline review: 24 finding(s) from review-report.json.

shirgoldbird · 2026-07-07T21:15:17Z

 ---
 title: "Managing admin API keys"
-description: "Learn how admins can create and manage admin API keys."
+description: "Create, copy, rename, and deactivate admin API keys in the DeepL self-admin area."


Frontmatter description not fully action-oriented

The description 'Create, copy, rename, and deactivate admin API keys in the DeepL self-admin area.' reads as a feature list rather than a task-oriented statement. CLAUDE.md states descriptions should tell developers what they'll learn, favouring 'Learn how to X' framing.

Suggested change

description: "Create, copy, rename, and deactivate admin API keys in the DeepL self-admin area."

description: "Learn how to create, copy, rename, and deactivate admin API keys in the DeepL self-admin area."

shirgoldbird · 2026-07-07T21:15:18Z

+1. **Upload** — Submit the document with `POST /v2/document`. Returns a `document_id` and `document_key`.
+2. **Poll** — Check translation status with `POST /v2/document/{document_id}` until status is `done`.
+3. **Download** — Retrieve the translated file with `POST /v2/document/{document_id}/result`.
+


Info box could be a plain sentence

The callout contains only 2 short sentences that are not warnings and do not require special emphasis. CLAUDE.md says to use callout boxes sparingly and only where they improve clarity over regular prose. This information could be a short paragraph or appended to the intro.

Suggested fix: Remove the wrapper and append as a sentence after the three-step list: 'The uploaded document is automatically deleted from the server after download. To retranslate, upload the document again.'

shirgoldbird · 2026-07-07T21:15:18Z

 playground: none
---
+---
+


Introductory paragraph partially duplicates frontmatter description

The opening sentence ('Creates a monolingual glossary that maps source phrases to target phrases for a single language pair.') repeats almost verbatim the frontmatter description ('Learn how to create a v2 monolingual glossary that maps source phrases to target phrases for a single language pair.'). The body text should extend or add value beyond the description, not restate it.

Suggested fix: Remove the redundant first clause from the body text and lead directly with the legacy/v3 context. For example: 'These are legacy v2 endpoints for creating monolingual glossaries. For new integrations, use the v3 glossary endpoints, which support multilingual glossaries and editing.'

shirgoldbird · 2026-07-07T21:15:18Z


-The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording.
+The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), fixes mistakes with minimal changes to wording.
+


Introductory paragraph duplicates frontmatter description

The opening sentence closely restates the frontmatter description ('Improve one or more texts by correcting spelling and grammar...'). In a reference page this is minor, but tightening the prose would reduce redundancy and add net-new value.

Suggested fix: Rewrite the opening sentence to lead with what distinguishes this endpoint from /v2/write/correct, e.g. 'The /v2/write/rephrase endpoint corrects spelling and grammar and rephrases sentences for clarity. Use the optional writing_style or tone parameters to target a specific style or tone.' Then keep the cross-reference sentence as-is.

shirgoldbird · 2026-07-07T21:15:18Z

-The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording.
+The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), fixes mistakes with minimal changes to wording.
+
+See the [Improve text overview](/api-reference/improve-text) for supported languages, request body descriptions, response field descriptions, and frequently asked questions.


Cross-reference sentence could be more specific about what the overview covers

The final sentence lists four categories of content on the overview page in a comma-separated run. This is accurate but slightly overwhelming; reader would benefit from knowing which items are most relevant when they arrive here mid-task.

Suggested fix: Simplify to: 'See the Improve text overview for supported languages, parameter details, response fields, and FAQs.' (minor reordering and shortening only — no content change required).

shirgoldbird · 2026-07-07T21:15:18Z

 openapi: get /v2/usage
 title: "Check usage and limits"
---
+description: "Retrieve character usage and account limits for the current billing period."


Frontmatter description not action-oriented

The description 'Retrieve character usage and account limits for the current billing period.' is noun-phrase oriented rather than action-oriented. Per CLAUDE.md, descriptions should tell developers what they'll learn or do, using 'Learn how to X' framing or imperative phrasing.

Suggested change

description: "Retrieve character usage and account limits for the current billing period."

description: "Check how many characters your account has used and the limits for the current billing period."

shirgoldbird · 2026-07-07T21:15:18Z

 ---
 openapi: post /v3/voice/realtime
 title: "Request Session"
+description: "Request an ephemeral streaming URL and authentication token to initiate a Voice API WebSocket session."


Description slightly exceeds action-oriented framing convention

The frontmatter description is functional but starts with a noun phrase ('Request an ephemeral streaming URL...') rather than an imperative or 'Learn how to' framing. CLAUDE.md asks descriptions to tell developers what they'll do, not what the endpoint does.

Suggested change

description: "Request an ephemeral streaming URL and authentication token to initiate a Voice API WebSocket session."

description: "Get an ephemeral streaming URL and authentication token to start a Voice API WebSocket session."

shirgoldbird · 2026-07-07T21:15:18Z

+- **Multilingual products**: Translate chat conversations in real time, localize user-generated content, or embed translation as a core product feature.

-In addition, many leading computer-assisted translation (CAT) tool providers have [integrated DeepL’s technology into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). This lets translators benefit from DeepL’s high-quality neural translations within their favorite translation tool. If you would like to develop a DeepL plugin for your CAT tool, [please contact us at here](https://support.deepl.com/hc/en-us/requests/new).
+Many leading computer-assisted translation (CAT) tool providers have [integrated DeepL into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). To develop a DeepL plugin for your CAT tool, [contact DeepL support](https://support.deepl.com/hc/en-us/requests/new).


Marketing-adjacent phrasing in use case bullets

The bullet 'Company communications' links to 'maximum data security' as anchor text for a marketing/product page. Anchor text should be descriptive of what the link leads to, not a superlative claim. 'maximum data security' reads as marketing copy embedded in a link.

Suggested change

Many leading computer-assisted translation (CAT) tool providers have [integrated DeepL into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). To develop a DeepL plugin for your CAT tool, [contact DeepL support](https://support.deepl.com/hc/en-us/requests/new).

Many leading computer-assisted translation (CAT) tool providers have [integrated DeepL into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). To develop a DeepL plugin for your CAT tool, [contact DeepL support](https://support.deepl.com/hc/en-us/requests/new).

shirgoldbird · 2026-07-07T21:15:18Z

+**Intended purpose**

-DeepL API is intended to translate or otherwise process general documents or other content provided by the Customer in accordance with the documentation. DeepL API is not intended for any high-risk applications as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/) (including any applicable delegated acts adopted by the European Commission on the basis of this provision).
+The DeepL API is intended to translate or otherwise process general documents or other content in accordance with the documentation. It is not intended for high-risk applications as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/) (including any applicable delegated acts adopted by the European Commission).


Horizontal rule used as section divider for legal/intended-use content

An --- horizontal rule separates the 'Intended purpose' block from the main content, and the block uses bold text as an ad-hoc heading rather than a proper markdown heading. This is visually inconsistent and may not render as intended in Mintlify. The intended-purpose content could be a <Note> or <Warning> callout, or a proper H2 section.

Suggested fix: Replace the --- + bold-text pattern with a Mintlify callout, e.g.: <Note>**Intended purpose**: The DeepL API is intended to translate or otherwise process general documents or other content in accordance with the documentation. It is not intended for high-risk applications as defined in [Article 6 of the EU AI Act](https://artificialintelligenceact.eu/article/6/) (including any applicable delegated acts adopted by the European Commission).</Note> — or promote it to a proper ## Intended purpose H2 heading.

shirgoldbird · 2026-07-07T21:15:18Z

@@ -1,5 +1,6 @@
 ---


No next-steps or onboarding path for new readers

This is an 'About' page at the top of a getting-started section. After reading about capabilities and plans, a first-time developer has no clear path forward. CLAUDE.md recommends linking generously and cross-referencing related pages.

Suggested fix: Add a brief 'Next steps' section or inline links after the plan sign-up line pointing to the quickstart or authentication guide, e.g.: 'Once you have a plan, see Authentication to make your first API request.'

Remove 12 standalone overview pages from the API Reference tab. Fold useful content into the first endpoint page of each group and into the Documentation tab overview (about.mdx). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…de to v2 section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

The pipeline deleted 14 overview pages but did not actually fold their content into the endpoint pages. This restores all deleted pages and reverts endpoint page modifications to their pre-pipeline state. The consolidation will be redone incrementally with manual review. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

shirgoldbird added 2 commits July 7, 2026 16:57

mintlify Bot deployed to staging July 7, 2026 21:02 View deployment

mintlify Bot deployed to staging July 7, 2026 21:07 View deployment

docs: consolidate api reference overviews

be4c81a

Task [0]: Consolidate API Reference overviews: remove standalone overview pages from the API Reference tab. Fold any useful content into the first endpoint page of each group or into the Documentation tab overv

shirgoldbird commented Jul 7, 2026

View reviewed changes

mintlify Bot deployed to staging July 7, 2026 21:15 View deployment

mintlify Bot deployed to staging July 7, 2026 21:22 View deployment

shirgoldbird changed the title ~~docs: pipeline-generated pages (13 families)~~ docs: remove API Reference overview pages, fold into endpoints Jul 7, 2026

docs: remove languages overview page missed in consolidation

952d111

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

mintlify Bot deployed to staging July 7, 2026 21:28 View deployment

docs: fold languages use cases into endpoint page, move migration gui…

b585c36

…de to v2 section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

mintlify Bot deployed to staging July 7, 2026 21:29 View deployment

mintlify Bot deployed to staging July 7, 2026 21:45 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: remove API Reference overview pages, fold into endpoints#389

docs: remove API Reference overview pages, fold into endpoints#389
shirgoldbird wants to merge 7 commits into
mainfrom
docs/ia-phase2-overviews

shirgoldbird commented Jul 7, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

shirgoldbird left a comment

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

shirgoldbird Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	description: "Create, copy, rename, and deactivate admin API keys in the DeepL self-admin area."
	description: "Learn how to create, copy, rename, and deactivate admin API keys in the DeepL self-admin area."


		The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording.
		The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), fixes mistakes with minimal changes to wording.

	description: "Retrieve character usage and account limits for the current billing period."
	description: "Check how many characters your account has used and the limits for the current billing period."

	description: "Request an ephemeral streaming URL and authentication token to initiate a Voice API WebSocket session."
	description: "Get an ephemeral streaming URL and authentication token to start a Voice API WebSocket session."

	Many leading computer-assisted translation (CAT) tool providers have [integrated DeepL into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). To develop a DeepL plugin for your CAT tool, [contact DeepL support](https://support.deepl.com/hc/en-us/requests/new).
	Many leading computer-assisted translation (CAT) tool providers have [integrated DeepL into their software](https://support.deepl.com/hc/articles/360019358599-CAT-tools-supported). To develop a DeepL plugin for your CAT tool, [contact DeepL support](https://support.deepl.com/hc/en-us/requests/new).

Uh oh!

Conversation

shirgoldbird commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Pages removed

Pages updated

How to review

Uh oh!

mintlify Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shirgoldbird left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shirgoldbird commented Jul 7, 2026 •

edited

Loading

mintlify Bot commented Jul 7, 2026 •

edited

Loading