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>

…anslate-overview Generated 2 pages for: learning-how-tos, translate - api-reference/translate/request-translation.mdx: Retire api-reference/translate.mdx overview page. Route unique content to appropriate docs/ pages per Diataxis. The endpoint page api-reference/translate/request-translation.mdx should stay as a clean openapi stub. ## Target: api-reference/translate/request-translation.mdx Keep this as a clean OpenAPI stub. It should only contain the frontmatter with `openapi: post /v2/translate`, a title, and optionally a brief one-sentence description. Remove any narrative content, parameter descriptions, or code examples. Current content is already correct — preserve it as-is. ## Target: docs/learning-how-tos/examples-and-guides/translating-text.mdx Create a new How-to page titled 'How to Translate Text'. This is the primary destination for the narrative and example content from api-reference/translate.mdx. Include the following sections: 1. **Overview / intro**: A brief intro explaining the /v2/translate endpoint is used for text translation, with a note that the request body must not exceed 128 KiB and to split text across multiple calls if needed. 2. **Basic translation examples** (cURL, HTTP, Python, PHP, C#, Node.js, Java tabs): Port the multi-tab code examples verbatim — both the 'without glossary' and 'with glossary' variants. Include the note that auth keys should not be hard-coded in production. 3. **Same-source-and-target-language warning**: Include the Info callout that same-language requests are still billed, and link to the translating-between-variants guide. 4. **About the model_type parameter**: Port the entire 'About the model_type parameter' section as-is, explaining latency_optimized vs quality_optimized, the best-effort nature, the December 2025 language coverage note, and the note about /languages endpoint future updates. 5. **Multiple Sentences**: Port the 'Multiple Sentences' section with its explanation and cURL/HTTP code examples. 6. **Translating Large Volumes of Text**: Port the 'Translating Large Volumes of Text' section with its three bullet-point strategies and cURL/HTTP code examples. 7. **In-Text Markup**: Port the 'In-Text Markup' section explaining the risk of embedded markers and the recommendation to use XML/HTML handling. Add links back to api-reference/translate/request-translation for the OpenAPI spec reference, and forward links to docs/xml-and-html-handling/xml, docs/xml-and-html-handling/html, and docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter where referenced. ## Target: docs/best-practices/translating-large-volumes.mdx Create a new Best Practices page titled 'Translating Large Volumes of Text'. This is an extraction and expansion of the 'Translating Large Volumes of Text' section from api-reference/translate.mdx. Include: the three strategies (submitting whole paragraphs, multiple text parameters up to 50 per request, parallel requests), the code examples showing the multi-text array request/response. Cross-link from docs/learning-how-tos/examples-and-guides/translating-text.mdx to this page. This page is a best-practices / how-to focused on batching and throughput. ## Content to discard - Intro sentence 'The text-translation API currently consists of a single endpoint' — generic boilerplate restating what the nav already shows. - Forward links to 'Request Body Descriptions' section on the same page — the section is being moved to the OpenAPI spec rendering on request-translation.mdx. - All ParamField/request body parameter definitions (text, source_lang, target_lang, context, model_type, split_sentences, preserve_formatting, formality, glossary_id, glossary_ids, style_id, custom_instructions, translation_memory_id, translation_memory_threshold, show_billed_characters, tag_handling, tag_handling_version, outline_detection, non_splitting_tags, splitting_tags, ignore_tags) — these are duplicated by the OpenAPI spec auto-rendering on api-reference/translate/request-translation.mdx and must not be re-documented in narrative pages. - Note 'we do not include examples for client libraries in every section but they do support all use cases' — generic boilerplate. - Link 'You can find the auto-generated spec here' pointing to request-translation — self-referential nav boilerplate. - docs/learning-how-tos/examples-and-guides/translating-text.mdx: Retire api-reference/translate.mdx overview page. Route unique content to appropriate docs/ pages per Diataxis. The endpoint page api-reference/translate/request-translation.mdx should stay as a clean openapi stub. ## Target: api-reference/translate/request-translation.mdx Keep this as a clean OpenAPI stub. It should only contain the frontmatter with `openapi: post /v2/translate`, a title, and optionally a brief one-sentence description. Remove any narrative content, parameter descriptions, or code examples. Current content is already correct — preserve it as-is. ## Target: docs/learning-how-tos/examples-and-guides/translating-text.mdx Create a new How-to page titled 'How to Translate Text'. This is the primary destination for the narrative and example content from api-reference/translate.mdx. Include the following sections: 1. **Overview / intro**: A brief intro explaining the /v2/translate endpoint is used for text translation, with a note that the request body must not exceed 128 KiB and to split text across multiple calls if needed. 2. **Basic translation examples** (cURL, HTTP, Python, PHP, C#, Node.js, Java tabs): Port the multi-tab code examples verbatim — both the 'without glossary' and 'with glossary' variants. Include the note that auth keys should not be hard-coded in production. 3. **Same-source-and-target-language warning**: Include the Info callout that same-language requests are still billed, and link to the translating-between-variants guide. 4. **About the model_type parameter**: Port the entire 'About the model_type parameter' section as-is, explaining latency_optimized vs quality_optimized, the best-effort nature, the December 2025 language coverage note, and the note about /languages endpoint future updates. 5. **Multiple Sentences**: Port the 'Multiple Sentences' section with its explanation and cURL/HTTP code examples. 6. **Translating Large Volumes of Text**: Port the 'Translating Large Volumes of Text' section with its three bullet-point strategies and cURL/HTTP code examples. 7. **In-Text Markup**: Port the 'In-Text Markup' section explaining the risk of embedded markers and the recommendation to use XML/HTML handling. Add links back to api-reference/translate/request-translation for the OpenAPI spec reference, and forward links to docs/xml-and-html-handling/xml, docs/xml-and-html-handling/html, and docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter where referenced. ## Target: docs/best-practices/translating-large-volumes.mdx Create a new Best Practices page titled 'Translating Large Volumes of Text'. This is an extraction and expansion of the 'Translating Large Volumes of Text' section from api-reference/translate.mdx. Include: the three strategies (submitting whole paragraphs, multiple text parameters up to 50 per request, parallel requests), the code examples showing the multi-text array request/response. Cross-link from docs/learning-how-tos/examples-and-guides/translating-text.mdx to this page. This page is a best-practices / how-to focused on batching and throughput. ## Content to discard - Intro sentence 'The text-translation API currently consists of a single endpoint' — generic boilerplate restating what the nav already shows. - Forward links to 'Request Body Descriptions' section on the same page — the section is being moved to the OpenAPI spec rendering on request-translation.mdx. - All ParamField/request body parameter definitions (text, source_lang, target_lang, context, model_type, split_sentences, preserve_formatting, formality, glossary_id, glossary_ids, style_id, custom_instructions, translation_memory_id, translation_memory_threshold, show_billed_characters, tag_handling, tag_handling_version, outline_detection, non_splitting_tags, splitting_tags, ignore_tags) — these are duplicated by the OpenAPI spec auto-rendering on api-reference/translate/request-translation.mdx and must not be re-documented in narrative pages. - Note 'we do not include examples for client libraries in every section but they do support all use cases' — generic boilerplate. - Link 'You can find the auto-generated spec here' pointing to request-translation — self-referential nav boilerplate.

shirgoldbird

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

shirgoldbird · 2026-07-08T15:01:15Z

@@ -1,5 +1,5 @@
 ---
 openapi: post /v2/translate
 title: "Translate text"


Description not action-oriented for developer learning

The frontmatter description 'Translate one or more text strings into a target language.' is functional but reads as a feature description rather than telling developers what they'll accomplish or learn. Per CLAUDE.md, descriptions should use 'Learn how to X' framing or equivalent.

Suggested fix: Change to: 'Send text to the DeepL API and receive translations in a target language.' This orients the reader toward the action and outcome without being generic.

shirgoldbird · 2026-07-08T15:01:15Z

@@ -0,0 +1,349 @@
+---
+title: "How to Translate Text"


Frontmatter description could be more specific

The description 'Send text translation requests to the DeepL API, with examples for glossaries, multiple sentences, large volumes, and in-text markup' is good but slightly list-heavy. It reads more like a table of contents than an action-oriented description.

Suggested change

title: "How to Translate Text"

title: "How to Translate Text"

description: "Learn how to send text translation requests to the DeepL API, including handling glossaries, large volumes, and in-text markup."

shirgoldbird · 2026-07-08T15:01:15Z

+public: true
+---
+
+The `/v2/translate` endpoint translates one or more text strings into a target language. The total request body size must not exceed 128 KiB (128 · 1024 bytes). If your content exceeds this limit, split it across multiple requests.


Intro paragraph buries the request body limit detail

The 128 KiB limit and the advice to split requests is useful, but it reads as a parenthetical to the endpoint description. Developers scanning for the limit may miss it.

Suggested change

The `/v2/translate` endpoint translates one or more text strings into a target language. The total request body size must not exceed 128 KiB (128 · 1024 bytes). If your content exceeds this limit, split it across multiple requests.

The `/v2/translate` endpoint translates one or more text strings into a target language.

:::warning

The total request body size must not exceed 128 KiB (128 · 1024 bytes). If your content exceeds this limit, split it across multiple requests.

:::

shirgoldbird · 2026-07-08T15:01:15Z

+                deeplClient.translateText("Hello, world!", null, "fr");
+        System.out.println(result.getText()); // Output: Bonjour, le monde !
+    }
+}


Parallel requests strategy lacks a code example or link

The 'Make parallel requests' bullet in the large volumes section advises calling translate from multiple threads or processes simultaneously, but gives no example or link to guidance on rate limits, concurrency, or SDK async patterns. Developers following this path may hit rate limit errors.

Suggested fix: Add a link to rate limit documentation or the API reference after the parallel requests bullet, e.g., 'See Rate limits for concurrency guidelines.'

shirgoldbird · 2026-07-08T15:01:15Z

+--header 'Content-Type: application/json' \
+--data '{
+  "text": [
+    "Hello, world!"


In-text markup section lacks a code example

The 'In-text markup' section describes a problem and two mitigation strategies but includes no code example. CLAUDE.md says to show, not just tell, and to pair explanations with concrete examples.

Suggested fix: Add a minimal cURL example showing text with embedded markers, the recommended conversion to XML/HTML tags, and the resulting request with tag_handling enabled. Even a two-line before/after text comparison would improve clarity.

shirgoldbird · 2026-07-08T15:01:15Z

+      "Hello, world!",
+      LanguageCode.English,
+      LanguageCode.French);
+Console.WriteLine(translatedText); // Output: Bonjour, le monde !


Hard-coded auth key warning placement

The warning 'In production code, do not hard-code your authentication key' (line 131) appears after the Basic translation tab block but before subsequent sections that also contain hard-coded keys in SDK examples. Placing it once after the first block is reasonable, but it may be missed by readers who jump to a specific tab.

Suggested fix: Consider moving the warning to immediately before the Tabs block, or folding it into the first Info box so it appears before any code is shown. No change needed if current placement is intentional.

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

shirgoldbird commented Jul 8, 2026

View reviewed changes

mintlify Bot deployed to staging July 8, 2026 15:02 View deployment

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

	title: "How to Translate Text"
	title: "How to Translate Text"
	description: "Learn how to send text translation requests to the DeepL API, including handling glossaries, large volumes, and in-text markup."

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!

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!

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