From b135c287b7f045cab7b671c9b914f6a430c0c696 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Wed, 2 Sep 2026 17:05:49 -0400 Subject: [PATCH] improve agentic readiness of docs --- .mintignore | 2 - docs.json | 96 +++++++++++++++++++++++++- docs/best-practices/error-handling.mdx | 65 +++++++++++++++-- docs/getting-started/about.mdx | 9 +-- docs/resources/contact.mdx | 33 +++++++++ docs/resources/open-api-spec.mdx | 22 +++--- docs/resources/privacy.mdx | 27 ++++++++ 7 files changed, 229 insertions(+), 25 deletions(-) create mode 100644 docs/resources/contact.mdx create mode 100644 docs/resources/privacy.mdx diff --git a/.mintignore b/.mintignore index 8d1cc48b..34472b6f 100644 --- a/.mintignore +++ b/.mintignore @@ -1,3 +1 @@ reviews/* -api-reference/openapi.json -api-reference/voice/voice.asyncapi.json diff --git a/docs.json b/docs.json index 38559381..ceb5f9d0 100644 --- a/docs.json +++ b/docs.json @@ -2,6 +2,7 @@ "$schema": "https://mintlify.com/docs.json", "theme": "mint", "name": "DeepL Documentation", + "description": "Developer documentation for the DeepL API: translate text and documents, transcribe and translate speech in real time, improve text, and customize output with glossaries, style rules, and translation memories.", "colors": { "primary": "#0f2b46", "light": "#ffffff", @@ -101,6 +102,13 @@ "drilldown": false } ] + }, + { + "group": "Support", + "pages": [ + "docs/resources/contact", + "docs/resources/privacy" + ] } ] }, @@ -418,6 +426,10 @@ { "label": "DeepL Status", "href": "https://status.deepl.com" + }, + { + "label": "Contact", + "href": "/docs/resources/contact" } ] } @@ -430,6 +442,8 @@ } }, "api": { + "openapi": "api-reference/openapi.yaml", + "asyncapi": "api-reference/voice/voice.asyncapi.yaml", "examples": { "languages": [ "curl" @@ -442,7 +456,9 @@ }, "errors": { "404": { - "redirect": false + "redirect": false, + "title": "Page not found", + "description": "This page does not exist. Humans: check out the [Quickstart](/docs/getting-started/quickstart) or the [API reference](/api-reference/translate/request-translation). Machines: try [/llms.txt](/llms.txt), [the docs MCP server](https://developers.deepl.com/mcp), or OpenAPI specs for [Text](/api-reference/openapi.yaml) and [Voice](/api-reference/voice/voice.asyncapi.yaml)." } }, "redirects": [ @@ -749,6 +765,50 @@ { "source": "/docs/learning-how-tos/cookbook/context-parameter-examples", "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter" + }, + { + "source": "/about", + "destination": "/docs/getting-started/about" + }, + { + "source": "/contact", + "destination": "/docs/resources/contact-and-support" + }, + { + "source": "/contact-us", + "destination": "/docs/resources/contact-and-support" + }, + { + "source": "/support", + "destination": "/docs/resources/contact-and-support" + }, + { + "source": "/privacy", + "destination": "/docs/resources/privacy-and-data-security" + }, + { + "source": "/openapi.yaml", + "destination": "/api-reference/openapi.yaml" + }, + { + "source": "/openapi.json", + "destination": "/api-reference/openapi.json" + }, + { + "source": "/api/openapi.yaml", + "destination": "/api-reference/openapi.yaml" + }, + { + "source": "/api/openapi.json", + "destination": "/api-reference/openapi.json" + }, + { + "source": "/asyncapi.yaml", + "destination": "/api-reference/voice/voice.asyncapi.yaml" + }, + { + "source": "/asyncapi.json", + "destination": "/api-reference/voice/voice.asyncapi.json" } ], "integrations": { @@ -788,6 +848,38 @@ "src": "/user-data.js", "defer": true } + }, + { + "tag": "script", + "attrs": { + "type": "application/ld+json" + }, + "children": "{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://www.deepl.com/#organization\",\"name\":\"DeepL\",\"legalName\":\"DeepL SE\",\"alternateName\":\"DeepL SE\",\"description\":\"DeepL SE is a Language AI company. Its developer products include the DeepL API for text, document, and real-time voice translation, and the DeepL Write API for text improvement.\",\"url\":\"https://www.deepl.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://static.deepl.com/img/logo/deepl-logo-blue.svg\"},\"email\":\"info@deepl.com\",\"faxNumber\":\"+49 221 95018653\",\"vatID\":\"DE349242045\",\"foundingDate\":\"2017\",\"address\":{\"@type\":\"PostalAddress\",\"streetAddress\":\"Maarweg 165\",\"postalCode\":\"50825\",\"addressLocality\":\"Cologne\",\"addressCountry\":\"DE\"},\"contactPoint\":[{\"@type\":\"ContactPoint\",\"contactType\":\"technical support\",\"url\":\"https://developers.deepl.com/docs/resources/contact-and-support\",\"areaServed\":\"Worldwide\",\"availableLanguage\":[\"en\"]},{\"@type\":\"ContactPoint\",\"contactType\":\"customer support\",\"url\":\"https://support.deepl.com/hc/en-us/requests/new\",\"areaServed\":\"Worldwide\"},{\"@type\":\"ContactPoint\",\"contactType\":\"sales\",\"url\":\"https://www.deepl.com/en/contact-us\",\"areaServed\":\"Worldwide\"},{\"@type\":\"ContactPoint\",\"contactType\":\"security\",\"email\":\"security@deepl.com\",\"areaServed\":\"Worldwide\",\"availableLanguage\":[\"en\"]}],\"sameAs\":[\"https://github.com/DeepL\",\"https://www.linkedin.com/company/deepl\",\"https://x.com/DeepLcom\",\"https://www.youtube.com/@DeepLcom\",\"https://en.wikipedia.org/wiki/DeepL_Translator\"]},{\"@type\":[\"SoftwareApplication\",\"WebAPI\"],\"@id\":\"https://developers.deepl.com/#deepl-api\",\"name\":\"DeepL API\",\"description\":\"REST and WebSocket APIs for translating text and documents, transcribing and translating speech in real time, improving text, and customizing output with glossaries, style rules, and translation memories.\",\"url\":\"https://developers.deepl.com\",\"applicationCategory\":\"DeveloperApplication\",\"operatingSystem\":\"Any\",\"provider\":{\"@id\":\"https://www.deepl.com/#organization\"},\"documentation\":\"https://developers.deepl.com/docs/getting-started/quickstart\",\"termsOfService\":\"https://www.deepl.com/pro-license\",\"privacyPolicy\":\"https://www.deepl.com/en/privacy\",\"offers\":[{\"@type\":\"Offer\",\"name\":\"DeepL API Free\",\"url\":\"https://www.deepl.com/en/pro#api\",\"price\":\"0\",\"priceCurrency\":\"EUR\",\"category\":\"free\"},{\"@type\":\"Offer\",\"name\":\"DeepL API Pro\",\"url\":\"https://www.deepl.com/en/pro#api\",\"category\":\"subscription\"}]}]}" + } + ], + "markdown": { + "instructions": [ + "Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.", + "Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).", + "Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key `. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.", + "Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid." + ] + }, + "seo": { + "indexing": "navigable", + "organization": { + "id": "https://www.deepl.com/", + "name": "DeepL", + "legalName": "DeepL SE", + "url": "https://www.deepl.com", + "logo": "https://static.deepl.com/img/logo/deepl-logo-blue.svg", + "sameAs": [ + "https://github.com/DeepL", + "https://www.linkedin.com/company/deepl", + "https://x.com/DeepLcom", + "https://www.instagram.com/deeplhq/", + "https://www.youtube.com/@DeepLcom" + ] } - ] + } } diff --git a/docs/best-practices/error-handling.mdx b/docs/best-practices/error-handling.mdx index ac9fd2f9..bc810913 100644 --- a/docs/best-practices/error-handling.mdx +++ b/docs/best-practices/error-handling.mdx @@ -1,17 +1,70 @@ --- title: "Error handling" +description: "Parse DeepL API error responses, decide which status codes to retry, and throttle your client so it stays inside the API's limits." mode: "wide" public: true --- -Errors are indicated by [standard HTTP status codes](https://developer.mozilla.org/docs/Web/HTTP/Status). It is important to make sure that your application handles errors in an appropriate way. To that end, please consult the list of expected status code results that are provided with each endpoint's documentation in the API Reference. +Errors are indicated by [standard HTTP status codes](https://developer.mozilla.org/docs/Web/HTTP/Status). Branch on the status code first, then read the JSON body for detail. The expected status codes for each endpoint are listed with that endpoint in the [API Reference](/api-reference/translate/request-translation). -* **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). +## Error response body -* **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/check-usage-and-limits) to find out your currently used and available quota. +Error responses carry a JSON body. Parse it rather than the status text. You should also log the `X-Trace-ID` response header, as it will help our team debug if you need to raise a support ticket. -* **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). You can check the [API Status Page](https://status.deepl.com/?tab=api) for current service availability and incident information. +```json Example error response +{ + "message": "Value for 'target_lang' not supported." +} +``` -The service dynamically adjusts to the load on the system. Please wait to stop receiving errors to send more requests again. As the service adapts, you will be able to send increasingly more requests within a given amount of time without encountering errors. +| **Field** | **Description** | +| --- | --- | +| `message` | Human-readable description of the error. Present on error responses | +| `code` | Machine-readable identifier for the error, where available. Branch on this rather than on `message`, which can change wording | -Additional information may be provided by a JSON response that contains more details about the error. In this case, this additional information will be contained in the message key. + +Don't match on `message` strings. They are written for humans and are not part of the API contract. Use the status code, and `code` where it is present. + + +Failures that occur before a request reaches the API, in DeepL's edge infrastructure, use a nested shape instead, with the message under an `error` object: + +```json Example infrastructure error response +{ + "error": { + "message": "Bad Gateway." + } +} +``` + +Handle both shapes in your parser. Reading `body.message ?? body.error?.message` covers every error the API can return, and keeps your client from crashing on a gateway error during an incident. + +## Which errors to retry + +| **Status** | **Meaning** | **Retry?** | +| --- | --- | --- | +| `400` | The request itself is invalid | No. Fix the request | +| `403` | Authorization failed, or the API key lacks the [permission scope](/docs/admin/permission-scopes) for this endpoint | No. Check the key and its scopes | +| `404` | The resource does not exist, or a document has already been downloaded | No | +| `413` | The request exceeds the [request size limit](/docs/resources/usage-limits) | No. Split the payload into smaller requests | +| `429`, `529` | Too many requests in a short period | Yes, with exponential backoff | +| `456` | Quota exhausted for the billing period or for a [Cost Control](/docs/best-practices/cost-control) limit | No. Retrying will not succeed until the quota is raised or the period resets | +| `500`, `503`, `504` | Temporary error in DeepL services | Yes, with exponential backoff | + +Details on the errors you are most likely to hit: + +* **HTTP 429: too many requests.** You may receive this when sending many API requests in a short period of time. Resend the request after a delay, using 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/check-usage-and-limits) to find out your currently used and available quota. + +* **HTTP 500: internal server error.** You'll receive this if there are temporary errors in DeepL services. Resend the request after a delay, using retries with exponential backoff. Check the [API Status Page](https://status.deepl.com/?tab=api) for current service availability and incident information. + +## Throttling your client + +The service dynamically adjusts to the load on the system, so there is no fixed request-per-second figure to code against. Design your client to find the limit rather than to assume one: + +* Retry `429` and 5xx responses with exponential backoff and jitter. Honor the `Retry-After` header when a response includes one, in preference to your own backoff interval +* Cap the number of requests you have in flight at once, and lower that cap while you are receiving `429` responses +* Batch multiple strings into a single [translate request](/api-reference/translate/request-translation) instead of sending one request per string, staying inside the [request size limit](/docs/resources/usage-limits) +* Treat `456` as a stop condition, not a retry condition, and poll the [usage endpoint](/api-reference/usage-and-quota/check-usage-and-limits) to see how close an account is to its quota before you get there + +As the service adapts to your traffic, you will be able to send increasingly more requests within a given amount of time without encountering errors. diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx index 5a88d6b1..6d402744 100644 --- a/docs/getting-started/about.mdx +++ b/docs/getting-started/about.mdx @@ -1,5 +1,6 @@ --- title: "About" +description: "Understand what the DeepL API does." public: false mode: "wide" --- @@ -26,10 +27,4 @@ In addition, many leading computer-assisted translation (CAT) tool providers hav - **Maximum data security**: With DeepL API paid plans, texts aren’t saved on persistent storage and aren’t used to train our models. And DeepL adheres strictly to EU data protection laws and ISO 27001. [Learn more about data security at DeepL](https://www.deepl.com/pro-data-security/). - **Customization with glossaries**: [Specify your own translations for words and phrases](/docs/customize/managing-glossaries), and customize your translations consistently and at scale. -To access the DeepL API, [sign up for a plan](https://www.deepl.com/en/pro#api). - ---- - -**Intended Purpose of the DeepL API** - -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). +To access the DeepL API, [sign up for a plan](https://www.deepl.com/en/pro#api). \ No newline at end of file diff --git a/docs/resources/contact.mdx b/docs/resources/contact.mdx new file mode 100644 index 00000000..ea3a1300 --- /dev/null +++ b/docs/resources/contact.mdx @@ -0,0 +1,33 @@ +--- +title: "Contact" +description: "Find the right DeepL channel to get help with our API." +--- + +Support for the DeepL API is split across a few channels. + +## Where to send your request + +| **What you need** | **Where to go** | +| --- | --- | +| Discussion and knowledge sharing about the API | [DeepL Developer Community on Discord](https://discord.gg/deepl) | +| Account, subscription, billing, or plan changes | [Submit a support request](https://support.deepl.com/hc/en-us/requests/new) | +| Pricing, volume plans, or enterprise agreements | [Contact DeepL sales](https://www.deepl.com/en/contact-us) | +| A security vulnerability | Email [security@deepl.com](mailto:security@deepl.com). A PGP public key is published in [`SECURITY.md`](https://github.com/DeepL/api-docs/blob/main/SECURITY.md) | +| Issues with the documentation | [Open an issue on `DeepL/api-docs`](https://github.com/DeepL/api-docs/issues) | +| DeepL API availability and status | [DeepL API status page](https://status.deepl.com/?tab=api) | +| General answers | [DeepL Help Center](https://support.deepl.com/hc/en-us) | + +## Before you open a support request + +Include the following to help us get you the fastest possible answer: + +- The `X-Trace-ID` response header from a failing request. DeepL API responses include this header, and it identifies that exact request in DeepL's logs +- The HTTP status code and the JSON `message` from the response body +- The endpoint you called +- The email address your subscription is linked to + +Never include an API key or sensitive content in your message. If a key has been exposed, [deactivate it immediately](/docs/admin/managing-api-keys). + +## Company details + +DeepL API products are provided by DeepL SE. Full publisher information is available on the [DeepL publisher page](https://www.deepl.com/publisher). diff --git a/docs/resources/open-api-spec.mdx b/docs/resources/open-api-spec.mdx index 3b404226..1378945e 100644 --- a/docs/resources/open-api-spec.mdx +++ b/docs/resources/open-api-spec.mdx @@ -1,16 +1,22 @@ --- title: "OpenAPI spec" -description: "Download the OpenAPI specification for the DeepL API" +description: "How to fetch the OpenAPI specifications for the DeepL API" --- -This repository contains an [OpenAPI specification](https://openapis.org/) of the DeepL API in YAML and JSON formats. +The DeepL API is described by an [OpenAPI specification](https://openapis.org/) for the REST endpoints and an [AsyncAPI specification](https://www.asyncapi.com/) for the streaming Voice API. Both are published in YAML and JSON. -| File | Format | Description | +Fetch them from this documentation site at a stable URL: + +| **Spec** | **Format** | **URL** | |---|---|---| -| [`openapi.yaml`](https://raw.githubusercontent.com/DeepL/api-docs/main/api-reference/openapi.yaml) | YAML | Main REST API spec (source of truth) | -| [`openapi.json`](https://raw.githubusercontent.com/DeepL/api-docs/main/api-reference/openapi.json) | JSON | Same content, auto-generated from YAML | -| [`voice.asyncapi.yaml`](https://raw.githubusercontent.com/DeepL/api-docs/main/api-reference/voice/voice.asyncapi.yaml) | YAML | AsyncAPI spec for the streaming Voice API | -| [`voice.asyncapi.json`](https://raw.githubusercontent.com/DeepL/api-docs/main/api-reference/voice/voice.asyncapi.json) | JSON | Same content, auto-generated from YAML | +| REST API (source of truth) | YAML | [`/api-reference/openapi.yaml`](/api-reference/openapi.yaml) | +| REST API | JSON | [`/api-reference/openapi.json`](/api-reference/openapi.json) | +| Voice WebSocket API (source of truth) | YAML | [`/api-reference/voice/voice.asyncapi.yaml`](/api-reference/voice/voice.asyncapi.yaml) | +| Voice WebSocket API | JSON | [`/api-reference/voice/voice.asyncapi.json`](/api-reference/voice/voice.asyncapi.json) | + +The JSON files are generated from the YAML sources, so treat the YAML as authoritative. + +The same files are available on [GitHub](https://github.com/DeepL/api-docs/tree/main/api-reference) if you prefer to pin a revision. You can use these specs to explore the API in tools like [Postman](https://www.postman.com/), or to auto-generate SDKs and code libraries using tools such as [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/DeepL/api-docs/main/api-reference/openapi.yaml) or [OpenAPI Generator](https://openapi-generator.tech/). @@ -18,4 +24,4 @@ You can use these specs to explore the API in tools like [Postman](https://www.p Swagger's "Try it out" in-browser simulator creates valid curl requests, but requests will fail due to [CORS restrictions](/docs/best-practices/cors-requests). -The spec files live in the [`api-reference/`](https://github.com/DeepL/api-docs/tree/main/api-reference) directory of the [api-docs repository](https://github.com/DeepL/api-docs). If you encounter issues or have feature requests, [create an issue](https://github.com/DeepL/api-docs/issues). +If you encounter issues or have feature requests, [create an issue](https://github.com/DeepL/api-docs/issues). diff --git a/docs/resources/privacy.mdx b/docs/resources/privacy.mdx new file mode 100644 index 00000000..e45459f2 --- /dev/null +++ b/docs/resources/privacy.mdx @@ -0,0 +1,27 @@ +--- +title: "Privacy" +description: "How DeepL handles privacy and security." +--- + +## Privacy Policies & Information + +| **Document** | **Area** | +| --- | --- | +| [DeepL Privacy Policy](https://www.deepl.com/privacy) | What personal data DeepL processes, on what legal basis, and your rights | +| [DeepL Terms & Conditions](https://www.deepl.com/pro-license) | The contractual terms for using DeepL services | +| [Data security at DeepL](https://www.deepl.com/pro-data-security) | Additional information on data protections for paid plans | + +## What this means for your integration + +Plan the following into your integration rather than discovering it in production: + +- **Data handling may differ between the Free and Pro plans.** Confirm which plan your key belongs to and check the terms above before development. +- **Understand data residency if required.** DeepL offers [Regional API endpoints](/docs/getting-started/regional-endpoints) for certain cusotmers that guarantee data processing within specific geographies. + +## Intended purpose + +The DeepL API is intended to translate or otherwise process general documents or other content provided by the customer in accordance with this documentation. It is not intended for any high-risk application 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 that provision. + +## Reporting a problem + +Report suspected vulnerabilities to [security@deepl.com](mailto:security@deepl.com), using the PGP key published in [`SECURITY.md`](https://github.com/DeepL/api-docs/blob/main/SECURITY.md). For privacy requests and any other question about your data, see [Contact and support](/docs/resources/contact-and-support).