docs: restructure IA around product lines (Phase 1)

api-reference/improve-text.mdx

@@ -163,7 +163,7 @@ The `/write/rephrase` endpoint returns a JSON object with Improvements under the
 
 #### Does Cost Control factor in Write API usage?
 
-Yes. If you set a [Cost Control limit](/docs/best-practices/cost-control), it will be enforced against a *sum of Translate API + Write API characters*. At this time, it is not possible to set separate Translate API and Write API cost control limits.
+Yes. If you set a [Cost Control limit](/docs/admin-api/control-costs), it will be enforced against a *sum of Translate API + Write API characters*. At this time, it is not possible to set separate Translate API and Write API cost control limits.
 
 #### Does the /usage endpoint response include Write API characters?
 
@@ -175,4 +175,4 @@ Yes! The Write API is accessed using the same API keys in [the API Keys tab](htt
 
 #### Can I see DeepL Write API usage in my reporting?
 
-We've added a new column to the [API key-level usage report](/docs/getting-started/managing-api-keys#get-api-key-level-usage) that breaks out text improvement characters separately. The character counts in the [Usage tab](https://www.deepl.com/your-account/usage) of your API account are a sum of both Translate *and* Write characters; these are not yet broken out separately.
+We've added a new column to the [API key-level usage report](/docs/admin-api/manage-api-keys#get-api-key-level-usage) that breaks out text improvement characters separately. The character counts in the [Usage tab](https://www.deepl.com/your-account/usage) of your API account are a sum of both Translate *and* Write characters; these are not yet broken out separately.

api-reference/translate.mdx

@@ -295,7 +295,7 @@ error.
   <Info>  
     The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
 
-    Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/best-practices/custom-instructions).
+    Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/translate-api/customizations/write-effective-instructions).
   </Info>
 </ParamField>
 <ParamField body="translation_memory_id" type="string">

api-reference/usage-and-quota.mdx

@@ -9,11 +9,11 @@ Retrieve usage information **within the current billing period** together with t
 * Text and document translation characters consumed in the current billing period in total _and_ for the API key used to make the request
 * Text improvement (`/write`) characters consumed in the current billing period in total _and_ for the API key used to make the request
 * Total characters consumed in the current billing period by the API key used to make the request
-* The key-level character limit for the API key used to make the request, if applicable (if a [key-level usage limit](../docs/getting-started/managing-api-keys#set-api-key-level-usage-limits) is set, it will be reflected in the `api_key_character_limit` field in the response; `1000000000000` will be returned if no key-level limit is set)
+* The key-level character limit for the API key used to make the request, if applicable (if a [key-level usage limit](/docs/admin-api/manage-api-keys#set-api-key-level-usage-limits) is set, it will be reflected in the `api_key_character_limit` field in the response; `1000000000000` will be returned if no key-level limit is set)
 * The current billing period start timestamp
 * The current billing period end timestamp
 * Total characters consumed in the current billing period
-* Subscription-level character limit that applies to the current billing period (if [Cost Control](../docs/best-practices/cost-control.md) is set, it will be reflected in the `character_limit` field in the response; `1000000000000` will be returned if no limit is set)
+* Subscription-level character limit that applies to the current billing period (if [Cost Control](/docs/admin-api/control-costs) is set, it will be reflected in the `character_limit` field in the response; `1000000000000` will be returned if no limit is set)
 
 An example request and response is shown below.
 

docs/resources/roadmap-and-release-notes.mdx → docs/changelog.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Roadmap and release notes"
+title: "Changelog"
 description: "The latest features and improvements in the DeepL API, plus what's coming next"
 rss: true
 ---
@@ -56,37 +56,37 @@ Use the `DeepL-Auth-Key` header instead.
 - Note that these languages only work with `quality_optimized` model or when no model is specified, and are not compatible with `latency_optimized` requests.
 - The `enable_beta_languages` parameter is maintained for backward compatibility but has no effect. 
 
-See [here](../getting-started/supported-languages) for the complete language list.
+See [here](/docs/translate-api/languages/supported-languages) for the complete language list.
 </Update>
 
 <Update label="2025">
 ## Q4 2025
 - Added API reference for the Voice API
 - Add contextual menu in the to make it easier to copy any API documentation page as context for AI tools
 - Add support for style rules in the API to programmatically get your created style rules and translate with them.
-- Overhauled the tag-handling algorithm that backs translation of XML and HTML in the DeepL API. To enable it and benefit from all the improvements, set the `tag_handling_version` parameter to `v2` in the text translation API. See [here](../xml-and-html-handling/tag-handling-v2) for more information.
+- Overhauled the tag-handling algorithm that backs translation of XML and HTML in the DeepL API. To enable it and benefit from all the improvements, set the `tag_handling_version` parameter to `v2` in the text translation API. See [here](/docs/translate-api/structured-content/how-tag-handling-works) for more information.
 - Added new usage analytics endpoint in the Admin API, including key-level reporting. See [here](/api-reference/admin-api/get-usage-analytics) for more details
 - Enabled support for multiple admins in an API subscription
-- Added support for 75 new languages, initially through the `enable_beta_languages` parameter, for text and document translation. Beta languages are not billed during the beta phase and do not yet support glossaries or formality. See [here](../getting-started/supported-languages#beta-languages) for more information
+- Added support for 75 new languages, initially through the `enable_beta_languages` parameter, for text and document translation. Beta languages are not billed during the beta phase and do not yet support glossaries or formality. See [here](/docs/translate-api/languages/supported-languages#beta-languages) for more information
 - Added HE, TH and VI to the languages endpoint, since they are now also available in document translation
 - Added 6 additional beta languages, for text and document translation. See the previous note about 75 new languages.
 - Added a new parameter to the text translation API to allow custom instructions, making it possible to customize the translation behavior (e.g. ["Use a friendly, diplomatic tone"])
 - Added support for JPEG and PNG images in [document translation](/api-reference/document), currently in Beta.
 
 ## Q3 2025
 - Creation of an admin API, making it possible to manage API keys programmatically. See [here](/api-reference/admin-api) for more information
-- Added support for new language: ES-419 (Latin American Spanish). For this release, this language will be available for the API in next-gen models only. See [here](../getting-started/supported-languages) for more information.
+- Added support for new language: ES-419 (Latin American Spanish). For this release, this language will be available for the API in next-gen models only. See [here](/docs/translate-api/languages/supported-languages) for more information.
 - Refreshed our API documentation and added new try-it explorers to support interacting with our APIs. See [here](/api-reference) to try it out!
 
 ## Q2 2025
-- Added support for new language: TH (Thai). For this release, this language will only support text translation. See [here](../getting-started/supported-languages) for more information.
-- Added support for new languages: HE (Hebrew) and VI (Vietnamese). For this release, these languages will be available for Pro v2 API in next-gen models only. See [here](../getting-started/supported-languages) for more information.
+- Added support for new language: TH (Thai). For this release, this language will only support text translation. See [here](/docs/translate-api/languages/supported-languages) for more information.
+- Added support for new languages: HE (Hebrew) and VI (Vietnamese). For this release, these languages will be available for Pro v2 API in next-gen models only. See [here](/docs/translate-api/languages/supported-languages) for more information.
 - Added improvements to API glossaries, including the ability to edit glossaries and create multilingual glossaries. Learn more [here](/api-reference/multilingual-glossaries/).
 - Improvements to the `/usage` endpoint for Pro API customers ([API reference](/api-reference/usage-and-quota/))
-- Improvements to key-level usage reporting, making it possible to pull reports with a custom date range and to group data by calendar day. Learn more [here](../getting-started/managing-api-keys#get-api-key-level-usage).
+- Improvements to key-level usage reporting, making it possible to pull reports with a custom date range and to group data by calendar day. Learn more [here](/docs/admin-api/manage-api-keys#get-api-key-level-usage).
 
 ## Q1 2025
-- Added support for API key-level usage limits, making it possible to set a character limit at the API key-level. Learn more [here](../getting-started/managing-api-keys#set-api-key-level-usage-limits).
+- Added support for API key-level usage limits, making it possible to set a character limit at the API key-level. Learn more [here](/docs/admin-api/manage-api-keys#set-api-key-level-usage-limits).
 - DeepL API for Write is generally available to Pro API customers, making it possible to improve texts in (at the time of release) 6 different languages. Learn more and get started [here](/api-reference/improve-text/).
 </Update>
 

docs/learning-how-tos/cookbook/nodejs-proxy.mdx → docs/cookbooks/build-a-translation-proxy-nodejs.mdx

@@ -12,7 +12,7 @@ These proxies are intended for prototyping and frontend testing. For production
 
 The DeepL API does not permit calls from client-side JavaScript - that is, from JavaScript running in a browser. This policy exists to keep your API key safe. When you place a call from your website directly to the DeepL API, that call needs to include your API key. Anyone using your website could look at the network calls or your code itself, find your API key, and use it themselves.
 
-For this and other security considerations, DeepL [does not enable the CORS headers](/docs/best-practices/cors-requests) you would need to call the API from a webpage hosted on your origin. The industry-standard approach is to call APIs like DeepL’s from a back-end service. DeepL enforces this best practice to keep your credentials secure.
+For this and other security considerations, DeepL [does not enable the CORS headers](/docs/going-to-production/solve-cors-errors) you would need to call the API from a webpage hosted on your origin. The industry-standard approach is to call APIs like DeepL’s from a back-end service. DeepL enforces this best practice to keep your credentials secure.
 
 ## When to use a quick proxy
 

docs/getting-started/about.mdx

@@ -5,7 +5,7 @@ mode: "wide"
 ---
 
 <Info>
-  For information about API updates and improvements, please refer to our [release notes](/docs/resources/release-notes).
+  For information about API updates and improvements, please refer to our [release notes](/docs/changelog).
 </Info>
 
 The DeepL API provides programmatic access to DeepL’s language AI technology, making it possible to bring high quality translation capabilities directly to your websites and applications.

docs/getting-started/auth.mdx

@@ -32,7 +32,7 @@ Keep your API key secure at all times. Do not use it in client-side code.
 
 If your authentication key becomes compromised, you also deactivate it and create a new key in [the "API Keys" tab](https://www.deepl.com/your-account/keys).
 
-Learn more about managing your DeepL API keys [here](/docs/getting-started/managing-api-keys).
+Learn more about managing your DeepL API keys [here](/docs/admin-api/manage-api-keys).
 
 The authentication key is provided by setting the *Authorization* HTTP header to `DeepL-Auth-Key [yourAuthKey]`.
 

docs/getting-started/breaking-changes.mdx

@@ -0,0 +1,16 @@
+---
+title: "Breaking changes"
+sidebarTitle: "Overview"
+mode: "wide"
+---
+
+In this section, we'll outline **planned deprecations and breaking changes** that might affect applications using the DeepL API.
+
+To learn about new releases, please see the [Release notes](/docs/changelog) page.
+
+<Card title="July 2024: Deprecation of insecure cipher suites" href="/docs/getting-started/breaking-changes/july-2024-deprecation-of-insecure-cipher-suites">
+</Card>
+<Card title='March 2025: Deprecating GET requests to /translate and authenticating with auth_key' href="/docs/getting-started/breaking-changes/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key">
+</Card>
+<Card title='November 2025: Deprecating query parameter and request body authentication' href="/docs/getting-started/breaking-changes/november-2025-deprecation-of-legacy-auth-methods">
+</Card>

docs/getting-started/client-libraries.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Client libraries"
+title: "SDKs"
 public: true
 mode: "wide"
 ---

docs/getting-started/intro.mdx

@@ -239,16 +239,14 @@ New user? Follow these quick steps to get started with the DeepL API.
     </Tabs>
   </Step>
   <Step title="Step 3: Keep building with our client libraries and how-to guides" titleSize="h3">
-    [Our official client libraries](/docs/getting-started/client-libraries) let you use the API with six popular programming languages - [Python](https://www.github.com/deeplcom/deepl-python), [JavaScript](https://www.github.com/deeplcom/deepl-node), [PHP](https://www.github.com/deeplcom/deepl-php), [.NET](https://www.github.com/deeplcom/deepl-dotnet), [Java](https://www.github.com/deeplcom/deepl-java), or [Ruby](https://www.github.com/deeplcom/deepl-rb). The DeepL community has [contributed client libraries](https://github.com/DeepLcom/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), and [Rust](https://github.com/Avimitin/deepl-rs). You may also wish to check out [these examples and guides](/docs/learning-how-tos/examples-and-guides).
+    [Our official client libraries](/docs/getting-started/client-libraries) let you use the API with six popular programming languages - [Python](https://www.github.com/deeplcom/deepl-python), [JavaScript](https://www.github.com/deeplcom/deepl-node), [PHP](https://www.github.com/deeplcom/deepl-php), [.NET](https://www.github.com/deeplcom/deepl-dotnet), [Java](https://www.github.com/deeplcom/deepl-java), or [Ruby](https://www.github.com/deeplcom/deepl-rb). The DeepL community has [contributed client libraries](https://github.com/DeepLcom/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), and [Rust](https://github.com/Avimitin/deepl-rs). You may also wish to check out [our cookbooks](/docs/cookbooks).
   </Step>
 </Steps>
 
 ## Keep exploring
 
 - [Your first API request](/docs/getting-started/your-first-api-request) - With just a few lines of code, make your first request to the DeepL Translate or Write API
-- [**DeepL 101**](/docs/learning-how-tos/examples-and-guides/first-things-to-try-with-the-deepl-api) - A quick guide to text and document translation, using Postman to play with the API, client libraries for your favorite programming language, and joining our developer community
-- [Cookbook](/docs/learning-how-tos/cookbook) - Explore short tutorials, examples, projects, and use cases
-- [Guides](/docs/learning-how-tos/examples-and-guides) - Discover in-depth explanations for API features and real-world applications
+- [Cookbooks](/docs/cookbooks) - Explore short tutorials, examples, projects, and use cases
 
 ## Community and Support
 
@@ -262,7 +260,7 @@ New user? Follow these quick steps to get started with the DeepL API.
   <Card icon="signal-stream" horizontal href="https://www.deeplstatus.com/">
     Status Page
   </Card>
-  <Card icon="notes" horizontal href="/docs/resources/release-notes">
+  <Card icon="notes" horizontal href="/docs/changelog">
     Release Notes
   </Card>
 </CardGroup>

docs/getting-started/test-your-api-requests-with-postman.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Test your API requests with Postman"
+title: "Postman"
 description: "Use our official Postman collection to get familiar with and test the DeepL API."
 mode: "wide"
 public: true

docs/best-practices/error-handling.mdx → docs/going-to-production/error-handling.mdx

@@ -8,7 +8,7 @@ Errors are indicated by [standard HTTP status codes](https://developer.mozilla.o
 
 * **HTTP 429: too many requests.** This is an error that you might receive when sending many API requests in a short period of time. Your application should be configured to resend the requests after some delay. Specifically, we recommend implementing retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries).
 
-* **HTTP 456: quota exceeded** **If you're a Free API user**, you'll receive this error when the monthly 500,000 character limit of your subscription has been reached. You can consider [upgrading your subscription](https://www.deepl.com/pro) if you need more character volume. **If you're a Pro API user**, you'll receive this error when your [Cost Control](/docs/best-practices/cost-control) limit has been reached, and you can increase or remove your Cost Control limit if you need to continue translating. You can also use the [usage endpoint](/api-reference/usage-and-quota) to find out your currently used and available quota.
+* **HTTP 456: quota exceeded** **If you're a Free API user**, you'll receive this error when the monthly 500,000 character limit of your subscription has been reached. You can consider [upgrading your subscription](https://www.deepl.com/pro) if you need more character volume. **If you're a Pro API user**, you'll receive this error when your [Cost Control](/docs/admin-api/control-costs) limit has been reached, and you can increase or remove your Cost Control limit if you need to continue translating. You can also use the [usage endpoint](/api-reference/usage-and-quota) to find out your currently used and available quota.
 
 * **HTTP 500: internal server error** This is an error you'll receive if there are temporary errors in DeepL Services. Your application should be configured to resend the requests after some delay. Specifically, we recommend implementing retries with exponential backoff. This is implemented in all of the official, DeepL-supported [client libraries](/docs/getting-started/client-libraries).