From d19a58eb2e8e6846d913926b1be82606d045250a Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Thu, 5 Feb 2026 20:50:13 -0500 Subject: [PATCH 1/4] add regional endpoint documentation --- docs.json | 1 + docs/getting-started/regional-endpoints.mdx | 195 ++++++++++++++++++++ 2 files changed, 196 insertions(+) create mode 100644 docs/getting-started/regional-endpoints.mdx diff --git a/docs.json b/docs.json index fb43207..aeac6e3 100644 --- a/docs.json +++ b/docs.json @@ -40,6 +40,7 @@ "docs/getting-started/intro", "docs/getting-started/about", "docs/getting-started/auth", + "docs/getting-started/regional-endpoints", "docs/getting-started/client-libraries", "docs/getting-started/managing-api-keys", "docs/getting-started/your-first-api-request", diff --git a/docs/getting-started/regional-endpoints.mdx b/docs/getting-started/regional-endpoints.mdx new file mode 100644 index 0000000..3cf96bf --- /dev/null +++ b/docs/getting-started/regional-endpoints.mdx @@ -0,0 +1,195 @@ +--- +title: "Regional API Endpoints" +description: "Reference documentation for DeepL's regional API endpoints, including endpoint URLs, configuration, and technical specifications." +public: false +--- + +DeepL offers regional API endpoints that process and store data within specific geographic regions. Regional endpoints provide the same API functionality as the standard endpoint, with data processing occurring in data centers located in specific regions. These endpoints help organizations meet data residency and compliance requirements, and can also reduce latency for users in specific geographic regions. + + +Regional endpoints are only available to customers who have signed a regional deployment addendum. Without a signed addendum, requests to regional endpoints will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to discuss access. + + +## Endpoint URLs + +DeepL currently offers the following regional endpoints: + +| **Region** | **Endpoint URL** | +|------------|------------------| +| **United States** | `https://api-us.deepl.com` | +| **Japan** | `https://api-jp.deepl.com` | +| **European Union (default)** | `https://api.deepl.com` | + + +--- + +## Configuration + +Regional endpoints are configured by specifying the endpoint URL in the API client. The standard endpoint URL (`https://api.deepl.com`) is replaced with the regional endpoint URL (`https://api-us.deepl.com` or `https://api-jp.deepl.com`). + + + + +```bash +# Standard endpoint +curl -X POST 'https://api.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": ["Hello, world!"], + "target_lang": "DE" +}' + +# US regional endpoint +curl -X POST 'https://api-us.deepl.com/v2/translate' \ +--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ +--header 'Content-Type: application/json' \ +--data '{ + "text": ["Hello, world!"], + "target_lang": "DE" +}' +``` + + + + +The Python client library accepts a `server_url` parameter: + +```python +import deepl + +# Standard endpoint +translator = deepl.Translator("[yourAuthKey]") + +# US regional endpoint +translator = deepl.Translator( + "[yourAuthKey]", + server_url="https://api-us.deepl.com" +) + +# Usage remains identical +result = translator.translate_text("Hello, world!", target_lang="DE") +print(result.text) +``` + + + + +The Node.js client library accepts a `serverUrl` option: + +```javascript +const deepl = require('deepl-node'); + +// Standard endpoint +const translator = new deepl.Translator('[yourAuthKey]'); + +// US regional endpoint +const translator = new deepl.Translator( + '[yourAuthKey]', + { serverUrl: 'https://api-us.deepl.com' } +); + +// Usage remains identical +(async () => { + const result = await translator.translateText('Hello, world!', null, 'de'); + console.log(result.text); +})(); +``` + + + + +The Java client library accepts a `TranslatorOptions` object with `setServerUrl()` method: + +```java +import com.deepl.api.*; + +// Standard endpoint +Translator translator = new Translator("[yourAuthKey]"); + +// US regional endpoint +TranslatorOptions options = new TranslatorOptions() + .setServerUrl("https://api-us.deepl.com"); +Translator translator = new Translator("[yourAuthKey]", options); + +// Usage remains identical +TextResult result = translator.translateText("Hello, world!", null, "de"); +System.out.println(result.getText()); +``` + + + + +The .NET client library accepts a `TranslatorOptions` object with `ServerUrl` property: + +```csharp +using DeepL; + +// Standard endpoint +var translator = new Translator("[yourAuthKey]"); + +// US regional endpoint +var translator = new Translator( + "[yourAuthKey]", + new TranslatorOptions { ServerUrl = "https://api-us.deepl.com" } +); + +// Usage remains identical +var result = await translator.TranslateTextAsync("Hello, world!", null, "de"); +Console.WriteLine(result.Text); +``` + + + + +The PHP client library accepts a `server_url` option in the options array: + +```php +use DeepL\Translator; + +// Standard endpoint +$translator = new Translator('[yourAuthKey]'); + +// US regional endpoint +$translator = new Translator( + '[yourAuthKey]', + ['server_url' => 'https://api-us.deepl.com'] +); + +// Usage remains identical +$result = $translator->translateText('Hello, world!', null, 'de'); +echo $result->text; +``` + + + + +--- + +## Technical specifications + +### API compatibility + +Regional endpoints maintain full API compatibility with the standard endpoint: + +- All API endpoints and parameters are identical +- Request and response formats are unchanged +- All features and functionality are available (text translation, document translation, glossaries, style rules, etc.) +- All API keys can be used with any regional endpoint + +### Glossaries and style rules + +Glossaries and style rules are unique to each of DeepL's regional data centers and are not shared between them. Glossaries and style rules created via the API on one regional endpoint (e.g., `api-us.deepl.com`) are only accessible from that same endpoint + +Additionally, the DeepL web UI (at [deepl.com](https://www.deepl.com)) currently only accesses the European Union data center. Glossaries and style rules created in the UI are only accessible via the standard `api.deepl.com` endpoint, not regional endpoints like `api-us.deepl.com` or `api-jp.deepl.com`. + +For more details, see the [Style rules documentation](/api-reference/style-rules). + +--- + +## Related documentation + +- [Client libraries](/docs/getting-started/client-libraries) - Language-specific client library documentation and configuration +- [Authentication and access](/docs/getting-started/auth) - API authentication methods and security best practices +- [Text translation](/api-reference/translate) - Text translation API reference +- [Admin API](/api-reference/admin-api) - Programmatic API key management for enterprise administrators From 9eac166fcf0944859887e47349a5879433b44afd Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Fri, 6 Feb 2026 10:55:56 -0500 Subject: [PATCH 2/4] docs: improve regional endpoints documentation - Change access requirement callout from Info to Warning for visibility - Add Access requirements subsection in Technical specifications - Restate activation requirement to catch users who skip intro - Specify 403 error code for unauthorized access Co-Authored-By: Claude Sonnet 4.5 --- docs/getting-started/regional-endpoints.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/regional-endpoints.mdx b/docs/getting-started/regional-endpoints.mdx index 3cf96bf..5a11def 100644 --- a/docs/getting-started/regional-endpoints.mdx +++ b/docs/getting-started/regional-endpoints.mdx @@ -6,9 +6,9 @@ public: false DeepL offers regional API endpoints that process and store data within specific geographic regions. Regional endpoints provide the same API functionality as the standard endpoint, with data processing occurring in data centers located in specific regions. These endpoints help organizations meet data residency and compliance requirements, and can also reduce latency for users in specific geographic regions. - + Regional endpoints are only available to customers who have signed a regional deployment addendum. Without a signed addendum, requests to regional endpoints will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to discuss access. - + ## Endpoint URLs @@ -168,6 +168,10 @@ echo $result->text; ## Technical specifications +### Access requirements + +Regional endpoints require activation through a regional deployment addendum. Requests to regional endpoints without activation will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to activate regional endpoints for your account. + ### API compatibility Regional endpoints maintain full API compatibility with the standard endpoint: From 541d70e8abc0ecc810f27ed95a2abd78b4806a11 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Fri, 6 Feb 2026 12:05:01 -0500 Subject: [PATCH 3/4] Update docs/getting-started/regional-endpoints.mdx Co-authored-by: Jason Gardella --- docs/getting-started/regional-endpoints.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/regional-endpoints.mdx b/docs/getting-started/regional-endpoints.mdx index 5a11def..f6353c9 100644 --- a/docs/getting-started/regional-endpoints.mdx +++ b/docs/getting-started/regional-endpoints.mdx @@ -183,7 +183,7 @@ Regional endpoints maintain full API compatibility with the standard endpoint: ### Glossaries and style rules -Glossaries and style rules are unique to each of DeepL's regional data centers and are not shared between them. Glossaries and style rules created via the API on one regional endpoint (e.g., `api-us.deepl.com`) are only accessible from that same endpoint +Glossaries and style rules are unique to each of DeepL's regional data centers and are not shared between them. Glossaries and style rules created via the API on one regional endpoint (e.g., `api-us.deepl.com`) are only accessible from that same endpoint. Additionally, the DeepL web UI (at [deepl.com](https://www.deepl.com)) currently only accesses the European Union data center. Glossaries and style rules created in the UI are only accessible via the standard `api.deepl.com` endpoint, not regional endpoints like `api-us.deepl.com` or `api-jp.deepl.com`. From 0a13697826b17461e8fe1600df022d0836cf3405 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Fri, 6 Feb 2026 16:51:22 -0500 Subject: [PATCH 4/4] clarify API compatibility --- docs/getting-started/regional-endpoints.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/regional-endpoints.mdx b/docs/getting-started/regional-endpoints.mdx index f6353c9..a0e06a5 100644 --- a/docs/getting-started/regional-endpoints.mdx +++ b/docs/getting-started/regional-endpoints.mdx @@ -172,14 +172,16 @@ echo $result->text; Regional endpoints require activation through a regional deployment addendum. Requests to regional endpoints without activation will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to activate regional endpoints for your account. +If your account has regional endpoint access, any API key can be used with any regional endpoint. + ### API compatibility -Regional endpoints maintain full API compatibility with the standard endpoint: +Regional endpoints support all DeepL API functionality except: + +- Voice API +- Admin Analytics API -- All API endpoints and parameters are identical -- Request and response formats are unchanged -- All features and functionality are available (text translation, document translation, glossaries, style rules, etc.) -- All API keys can be used with any regional endpoint +These endpoints are only available on the standard `api.deepl.com` endpoint. ### Glossaries and style rules