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/api-reference/admin-api/get-custom-tag-usage-analytics.mdx b/api-reference/admin-api/get-custom-tag-usage-analytics.mdx index 33d9d040..5926916a 100644 --- a/api-reference/admin-api/get-custom-tag-usage-analytics.mdx +++ b/api-reference/admin-api/get-custom-tag-usage-analytics.mdx @@ -1,6 +1,7 @@ --- openapi: get /v2/admin/analytics/custom-tags title: "Get custom tag usage analytics" +description: "Retrieve DeepL API usage broken down by custom tag for a date range, optionally aggregated by day, with paginated results." --- ## Date range diff --git a/api-reference/admin-api/get-usage-analytics.mdx b/api-reference/admin-api/get-usage-analytics.mdx index d4027f86..9a71e61b 100644 --- a/api-reference/admin-api/get-usage-analytics.mdx +++ b/api-reference/admin-api/get-usage-analytics.mdx @@ -1,6 +1,7 @@ --- openapi: get /v2/admin/analytics title: "Get usage analytics" +description: "Retrieve organization-wide DeepL API usage for a date range, optionally grouped by API key or by API key and day." --- ## Date range diff --git a/api-reference/admin-api/managing-developer-keys/create-key.mdx b/api-reference/admin-api/managing-developer-keys/create-key.mdx index f2593ea2..a790f0e2 100644 --- a/api-reference/admin-api/managing-developer-keys/create-key.mdx +++ b/api-reference/admin-api/managing-developer-keys/create-key.mdx @@ -1,4 +1,5 @@ --- openapi: post /v2/admin/developer-keys title: "Create a developer key" +description: "Create a new DeepL API key for your organization as an admin, using the Admin API." --- \ No newline at end of file diff --git a/api-reference/admin-api/managing-developer-keys/deactivate-key.mdx b/api-reference/admin-api/managing-developer-keys/deactivate-key.mdx index 5f27bb71..bf71b815 100644 --- a/api-reference/admin-api/managing-developer-keys/deactivate-key.mdx +++ b/api-reference/admin-api/managing-developer-keys/deactivate-key.mdx @@ -1,4 +1,5 @@ --- openapi: put /v2/admin/developer-keys/deactivate title: "Deactivate a developer key" +description: "Deactivate a DeepL API key as an admin so it can no longer be used to authenticate requests." --- \ No newline at end of file diff --git a/api-reference/admin-api/managing-developer-keys/get-keys.mdx b/api-reference/admin-api/managing-developer-keys/get-keys.mdx index faaeda15..f11f1b0f 100644 --- a/api-reference/admin-api/managing-developer-keys/get-keys.mdx +++ b/api-reference/admin-api/managing-developer-keys/get-keys.mdx @@ -1,4 +1,5 @@ --- openapi: get /v2/admin/developer-keys title: "Get developer keys" +description: "List every DeepL API key in your organization as an admin, including each key's label and usage limits." --- \ No newline at end of file diff --git a/api-reference/admin-api/managing-developer-keys/rename-key.mdx b/api-reference/admin-api/managing-developer-keys/rename-key.mdx index 682c0c71..7d64c6c9 100644 --- a/api-reference/admin-api/managing-developer-keys/rename-key.mdx +++ b/api-reference/admin-api/managing-developer-keys/rename-key.mdx @@ -1,4 +1,5 @@ --- openapi: put /v2/admin/developer-keys/label title: "Rename a developer key" +description: "Change the label on an existing DeepL API key as an admin, using the Admin API." --- \ No newline at end of file diff --git a/api-reference/admin-api/managing-developer-keys/set-usage-limits.mdx b/api-reference/admin-api/managing-developer-keys/set-usage-limits.mdx index e0ace3ae..90a14122 100644 --- a/api-reference/admin-api/managing-developer-keys/set-usage-limits.mdx +++ b/api-reference/admin-api/managing-developer-keys/set-usage-limits.mdx @@ -1,4 +1,5 @@ --- openapi: put /v2/admin/developer-keys/limits title: "Set developer key limits" +description: "Set or update the usage limit on an individual DeepL API key as an admin." --- \ No newline at end of file diff --git a/api-reference/document/check-document-status.mdx b/api-reference/document/check-document-status.mdx index 2688c61b..dff1c8e9 100644 --- a/api-reference/document/check-document-status.mdx +++ b/api-reference/document/check-document-status.mdx @@ -1,4 +1,5 @@ --- openapi: post /v2/document/{document_id} title: "Check document status" +description: "Check whether an uploaded document has finished translating, along with its billed character count and any error." --- \ No newline at end of file diff --git a/api-reference/document/download-translated-document.mdx b/api-reference/document/download-translated-document.mdx index ae1fbc1a..d3b54596 100644 --- a/api-reference/document/download-translated-document.mdx +++ b/api-reference/document/download-translated-document.mdx @@ -1,4 +1,5 @@ --- openapi: post /v2/document/{document_id}/result title: "Download translated document" +description: "Download the translated file once a document translation job has finished. Results are available for a limited time." --- \ No newline at end of file diff --git a/api-reference/document/upload-and-translate-a-document.mdx b/api-reference/document/upload-and-translate-a-document.mdx index 513c5670..7c8ae6dd 100644 --- a/api-reference/document/upload-and-translate-a-document.mdx +++ b/api-reference/document/upload-and-translate-a-document.mdx @@ -1,4 +1,5 @@ --- openapi: post /v2/document title: "Upload and translate a document" +description: "Upload a document for translation and receive the document ID and key needed to check status and download the result." --- \ No newline at end of file diff --git a/api-reference/glossaries/create-a-glossary.mdx b/api-reference/glossaries/create-a-glossary.mdx index 7498a80a..dc166138 100644 --- a/api-reference/glossaries/create-a-glossary.mdx +++ b/api-reference/glossaries/create-a-glossary.mdx @@ -1,5 +1,6 @@ --- openapi: post /v2/glossaries title: "Create a glossary" +description: "Create a v2 glossary from a list of source and target term pairs for a single language pair." playground: none --- \ No newline at end of file diff --git a/api-reference/glossaries/delete-a-glossary.mdx b/api-reference/glossaries/delete-a-glossary.mdx index 17626cfd..2fce6da4 100644 --- a/api-reference/glossaries/delete-a-glossary.mdx +++ b/api-reference/glossaries/delete-a-glossary.mdx @@ -1,5 +1,6 @@ --- openapi: delete /v2/glossaries/{glossary_id} title: "Delete a glossary" +description: "Delete a v2 glossary and all of its entries. Deleted glossaries cannot be recovered." playground: none --- \ No newline at end of file diff --git a/api-reference/glossaries/list-all-glossaries.mdx b/api-reference/glossaries/list-all-glossaries.mdx index bf780b91..efcf768e 100644 --- a/api-reference/glossaries/list-all-glossaries.mdx +++ b/api-reference/glossaries/list-all-glossaries.mdx @@ -1,5 +1,6 @@ --- openapi: get /v2/glossaries title: "List all glossaries" +description: "List every v2 glossary on your account with its metadata, without returning the glossary entries." playground: none --- \ No newline at end of file diff --git a/api-reference/glossaries/retrieve-glossary-details.mdx b/api-reference/glossaries/retrieve-glossary-details.mdx index 16cc2844..186bc05a 100644 --- a/api-reference/glossaries/retrieve-glossary-details.mdx +++ b/api-reference/glossaries/retrieve-glossary-details.mdx @@ -1,5 +1,6 @@ --- openapi: get /v2/glossaries/{glossary_id} title: "Retrieve glossary details" +description: "Retrieve the metadata for a single v2 glossary, including its language pair and entry count, without the entries." playground: none --- \ No newline at end of file diff --git a/api-reference/glossaries/retrieve-glossary-entries.mdx b/api-reference/glossaries/retrieve-glossary-entries.mdx index 5f8e37f1..8fe3f906 100644 --- a/api-reference/glossaries/retrieve-glossary-entries.mdx +++ b/api-reference/glossaries/retrieve-glossary-entries.mdx @@ -1,5 +1,6 @@ --- openapi: get /v2/glossaries/{glossary_id}/entries title: "Retrieve glossary entries" +description: "Retrieve the term pairs stored in a single v2 glossary, in the format requested through the Accept header." playground: none --- \ No newline at end of file diff --git a/api-reference/improve-text/deepl-write-api-service-specification-updates.mdx b/api-reference/improve-text/deepl-write-api-service-specification-updates.mdx index bd3f520c..390d18f6 100644 --- a/api-reference/improve-text/deepl-write-api-service-specification-updates.mdx +++ b/api-reference/improve-text/deepl-write-api-service-specification-updates.mdx @@ -1,5 +1,6 @@ --- title: "DeepL Write API Service Specification Updates" +description: "Service specification terms for the DeepL Write text improvement function, available on DeepL API Pro subscriptions." --- diff --git a/api-reference/jobs-voice-translate/create-voice-translate-job.mdx b/api-reference/jobs-voice-translate/create-voice-translate-job.mdx index 9da22982..ba2fe1b8 100644 --- a/api-reference/jobs-voice-translate/create-voice-translate-job.mdx +++ b/api-reference/jobs-voice-translate/create-voice-translate-job.mdx @@ -1,4 +1,5 @@ --- openapi: post /v1/jobs/voice/translate title: "Create a voice translation job" +description: "Create an asynchronous voice translation job and receive an upload URL for your source audio file." --- diff --git a/api-reference/jobs-voice-translate/get-voice-translate-job-status.mdx b/api-reference/jobs-voice-translate/get-voice-translate-job-status.mdx index b3a12643..b0dd429f 100644 --- a/api-reference/jobs-voice-translate/get-voice-translate-job-status.mdx +++ b/api-reference/jobs-voice-translate/get-voice-translate-job-status.mdx @@ -1,4 +1,5 @@ --- openapi: get /v1/jobs/voice/translate/{job_id} title: "Get voice translation job status" +description: "Check the status of a voice translation job and get a download URL and signature for each completed target." --- diff --git a/api-reference/languages/retrieve-languages-by-resource.mdx b/api-reference/languages/retrieve-languages-by-resource.mdx index be1a0bac..134f3895 100644 --- a/api-reference/languages/retrieve-languages-by-resource.mdx +++ b/api-reference/languages/retrieve-languages-by-resource.mdx @@ -1,5 +1,6 @@ --- openapi: get /v3/languages title: "Retrieve languages" +description: "Retrieve the languages a DeepL API resource supports, including source and target roles and per-resource features." --- diff --git a/api-reference/languages/retrieve-supported-languages.mdx b/api-reference/languages/retrieve-supported-languages.mdx index 8742f247..cf2ca35e 100644 --- a/api-reference/languages/retrieve-supported-languages.mdx +++ b/api-reference/languages/retrieve-supported-languages.mdx @@ -1,6 +1,7 @@ --- openapi: get /v2/languages title: "Retrieve supported languages (v2)" +description: "Reference for the deprecated v2/languages endpoint. New integrations should use the v3/languages endpoints instead." tag: "DEPRECATED" --- diff --git a/api-reference/multilingual-glossaries/create-a-glossary.mdx b/api-reference/multilingual-glossaries/create-a-glossary.mdx index cce66949..f79ae044 100644 --- a/api-reference/multilingual-glossaries/create-a-glossary.mdx +++ b/api-reference/multilingual-glossaries/create-a-glossary.mdx @@ -1,4 +1,5 @@ --- openapi: post /v3/glossaries title: "Create a glossary" +description: "Create a v3 multilingual glossary holding one or more dictionaries, each covering a source and target language pair." --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/delete-a-glossary.mdx b/api-reference/multilingual-glossaries/delete-a-glossary.mdx index ed5c7b66..f4ba0845 100644 --- a/api-reference/multilingual-glossaries/delete-a-glossary.mdx +++ b/api-reference/multilingual-glossaries/delete-a-glossary.mdx @@ -1,4 +1,5 @@ --- openapi: delete /v3/glossaries/{glossary_id} title: "Delete a glossary" +description: "Delete a v3 multilingual glossary along with all of its dictionaries and entries. This cannot be undone." --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id.mdx b/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id.mdx index d53aef94..253743b7 100644 --- a/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id.mdx +++ b/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id.mdx @@ -1,4 +1,5 @@ --- +description: "Delete a single dictionary from a v3 multilingual glossary by its source and target language pair." openapi: delete /v3/glossaries/{glossary_id}/dictionaries sidebarTitle: Delete a glossary dictionary --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/edit-glossary-details.mdx b/api-reference/multilingual-glossaries/edit-glossary-details.mdx index 7766583a..1d1310c8 100644 --- a/api-reference/multilingual-glossaries/edit-glossary-details.mdx +++ b/api-reference/multilingual-glossaries/edit-glossary-details.mdx @@ -1,3 +1,4 @@ --- +description: "Rename a v3 multilingual glossary, or edit the dictionary for one source and target language pair." openapi: patch /v3/glossaries/{glossary_id} --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/list-all-glossaries.mdx b/api-reference/multilingual-glossaries/list-all-glossaries.mdx index 0c887cba..8428750a 100644 --- a/api-reference/multilingual-glossaries/list-all-glossaries.mdx +++ b/api-reference/multilingual-glossaries/list-all-glossaries.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/glossaries title: "List all glossaries" +description: "List every v3 multilingual glossary on your account with its metadata, without returning the entries." --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx b/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx index 037bd73d..ed785952 100644 --- a/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx +++ b/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx @@ -1,6 +1,7 @@ --- openapi: "get /v2/glossary-language-pairs" title: "List language pairs supported for glossaries" +description: "Reference for the deprecated v2/glossary-language-pairs endpoint. New integrations should use v3/languages instead." tag: "DEPRECATED" playground: none --- diff --git a/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries.mdx b/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries.mdx index 7ed3d436..5f7d998c 100644 --- a/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries.mdx +++ b/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries.mdx @@ -1,4 +1,5 @@ --- +description: "Create a dictionary in a v3 multilingual glossary, or replace the entries in an existing one, for one language pair." openapi: put /v3/glossaries/{glossary_id}/dictionaries sidebarTitle: "Create or replace glossary entries" --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/retrieve-glossary-details.mdx b/api-reference/multilingual-glossaries/retrieve-glossary-details.mdx index 59bb9802..20340432 100644 --- a/api-reference/multilingual-glossaries/retrieve-glossary-details.mdx +++ b/api-reference/multilingual-glossaries/retrieve-glossary-details.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/glossaries/{glossary_id} title: "Retrieve glossary details" +description: "Retrieve the metadata for a single v3 multilingual glossary, including its dictionaries, without the entries." --- \ No newline at end of file diff --git a/api-reference/multilingual-glossaries/retrieve-glossary-entries.mdx b/api-reference/multilingual-glossaries/retrieve-glossary-entries.mdx index 3ca149c0..7607e563 100644 --- a/api-reference/multilingual-glossaries/retrieve-glossary-entries.mdx +++ b/api-reference/multilingual-glossaries/retrieve-glossary-entries.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/glossaries/{glossary_id}/entries title: "Retrieve glossary entries" +description: "Retrieve the term pairs stored in a v3 multilingual glossary dictionary, returned in TSV format." --- \ No newline at end of file diff --git a/api-reference/quality-evaluation/poll.mdx b/api-reference/quality-evaluation/poll.mdx index 50b2f8e7..1a3579e9 100644 --- a/api-reference/quality-evaluation/poll.mdx +++ b/api-reference/quality-evaluation/poll.mdx @@ -1,6 +1,7 @@ --- openapi: get /v1/quality-evaluation/{job_id} title: "Poll for the evaluation result" +description: "Poll an evaluation job for its status, and retrieve the full quality evaluation report once the job completes." --- See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, and limits. diff --git a/api-reference/quality-evaluation/submit.mdx b/api-reference/quality-evaluation/submit.mdx index 2aa6349e..7552cc89 100644 --- a/api-reference/quality-evaluation/submit.mdx +++ b/api-reference/quality-evaluation/submit.mdx @@ -1,6 +1,7 @@ --- openapi: post /v1/quality-evaluation title: "Submit an evaluation job" +description: "Submit translated segments for quality evaluation and receive a poll URL for retrieving the report." --- See the [Quality Evaluation overview](/api-reference/quality-evaluation) for severity values, sub-types, span semantics, and limits. diff --git a/api-reference/style-rules/create-custom-instruction.mdx b/api-reference/style-rules/create-custom-instruction.mdx index 1dfe0170..a05216f4 100644 --- a/api-reference/style-rules/create-custom-instruction.mdx +++ b/api-reference/style-rules/create-custom-instruction.mdx @@ -1,4 +1,5 @@ --- openapi: post /v3/style_rules/{style_id}/custom_instructions title: "Create a custom instruction" +description: "Add a custom instruction to a style rule list to shape translation output beyond the configured rules." --- diff --git a/api-reference/style-rules/create-style-rule.mdx b/api-reference/style-rules/create-style-rule.mdx index f9690c27..6191edd3 100644 --- a/api-reference/style-rules/create-style-rule.mdx +++ b/api-reference/style-rules/create-style-rule.mdx @@ -1,4 +1,5 @@ --- openapi: post /v3/style_rules title: "Create a style rule list" +description: "Create a style rule list, the container for the configured rules and custom instructions applied to translations." --- diff --git a/api-reference/style-rules/delete-custom-instruction.mdx b/api-reference/style-rules/delete-custom-instruction.mdx index 9f248d19..3db960f9 100644 --- a/api-reference/style-rules/delete-custom-instruction.mdx +++ b/api-reference/style-rules/delete-custom-instruction.mdx @@ -1,4 +1,5 @@ --- openapi: delete /v3/style_rules/{style_id}/custom_instructions/{instruction_id} title: "Delete a custom instruction" +description: "Remove a single custom instruction from a style rule list, leaving its configured rules in place." --- diff --git a/api-reference/style-rules/delete-style-rule.mdx b/api-reference/style-rules/delete-style-rule.mdx index 082af868..c9efd631 100644 --- a/api-reference/style-rules/delete-style-rule.mdx +++ b/api-reference/style-rules/delete-style-rule.mdx @@ -1,4 +1,5 @@ --- openapi: delete /v3/style_rules/{style_id} title: "Delete a style rule list" +description: "Delete a style rule list along with its configured rules and custom instructions." --- diff --git a/api-reference/style-rules/get-custom-instruction.mdx b/api-reference/style-rules/get-custom-instruction.mdx index e16be4a6..25806fa8 100644 --- a/api-reference/style-rules/get-custom-instruction.mdx +++ b/api-reference/style-rules/get-custom-instruction.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/style_rules/{style_id}/custom_instructions/{instruction_id} title: "Get a custom instruction" +description: "Retrieve a single custom instruction from a style rule list by its instruction ID." --- diff --git a/api-reference/style-rules/get-style-rule.mdx b/api-reference/style-rules/get-style-rule.mdx index 4c84edf0..ab6e8870 100644 --- a/api-reference/style-rules/get-style-rule.mdx +++ b/api-reference/style-rules/get-style-rule.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/style_rules/{style_id} title: "Get a style rule list" +description: "Retrieve a single style rule list, including its configured rules and custom instructions." --- diff --git a/api-reference/style-rules/list-all-style-rules.mdx b/api-reference/style-rules/list-all-style-rules.mdx index 874c1e0e..b871d3cf 100644 --- a/api-reference/style-rules/list-all-style-rules.mdx +++ b/api-reference/style-rules/list-all-style-rules.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/style_rules title: "Get all style rule lists" +description: "List every style rule list on your account, with the configured rules and custom instructions on each." --- \ No newline at end of file diff --git a/api-reference/style-rules/request-translation.mdx b/api-reference/style-rules/request-translation.mdx index faba379e..9e87ead4 100644 --- a/api-reference/style-rules/request-translation.mdx +++ b/api-reference/style-rules/request-translation.mdx @@ -1,5 +1,5 @@ --- openapi: /api-reference/style-rules/openapi-temp.yaml post /v2/translate title: "Translate text" -description: "" +description: "Translate text with a style rule list applied, using the style_id parameter on the translate endpoint." --- \ No newline at end of file diff --git a/api-reference/style-rules/update-configured-rules.mdx b/api-reference/style-rules/update-configured-rules.mdx index 4e959e53..04a9fbfe 100644 --- a/api-reference/style-rules/update-configured-rules.mdx +++ b/api-reference/style-rules/update-configured-rules.mdx @@ -1,4 +1,5 @@ --- openapi: put /v3/style_rules/{style_id}/configured_rules title: "Replace configured rules" +description: "Replace the full set of configured rules on a style rule list. Rules left out of the request are removed." --- diff --git a/api-reference/style-rules/update-custom-instruction.mdx b/api-reference/style-rules/update-custom-instruction.mdx index 1d2a1353..a0d81501 100644 --- a/api-reference/style-rules/update-custom-instruction.mdx +++ b/api-reference/style-rules/update-custom-instruction.mdx @@ -1,4 +1,5 @@ --- openapi: put /v3/style_rules/{style_id}/custom_instructions/{instruction_id} title: "Replace a custom instruction" +description: "Replace the text of an existing custom instruction on a style rule list." --- diff --git a/api-reference/style-rules/update-style-rule.mdx b/api-reference/style-rules/update-style-rule.mdx index 6be3a68d..c83780c2 100644 --- a/api-reference/style-rules/update-style-rule.mdx +++ b/api-reference/style-rules/update-style-rule.mdx @@ -1,4 +1,5 @@ --- openapi: patch /v3/style_rules/{style_id} title: "Update a style rule list's name" +description: "Rename an existing style rule list without changing its configured rules or custom instructions." --- diff --git a/api-reference/translate/request-translation.mdx b/api-reference/translate/request-translation.mdx index 88270858..4c71c5a2 100644 --- a/api-reference/translate/request-translation.mdx +++ b/api-reference/translate/request-translation.mdx @@ -1,5 +1,5 @@ --- openapi: post /v2/translate title: "Translate text" -description: "" +description: "Translate text between any supported language pair, with options for formality, glossaries, tag handling, and context." --- \ No newline at end of file diff --git a/api-reference/translation-memory/list-translation-memories.mdx b/api-reference/translation-memory/list-translation-memories.mdx index e44099f2..d63a1c42 100644 --- a/api-reference/translation-memory/list-translation-memories.mdx +++ b/api-reference/translation-memory/list-translation-memories.mdx @@ -1,5 +1,7 @@ --- openapi: get /v3/translation_memories title: "List translation memories" -description: "Retrieve translation memories associated with your account, used to store and reuse previously created translations. See [How to use translation memories](/docs/customize/using-translation-memories) to use them in translation requests." +description: "Retrieve the translation memories on your account, which store previously created translations for reuse." --- + +To apply a translation memory to a translation request, see [Using translation memories](/docs/customize/using-translation-memories). diff --git a/api-reference/voice/deepl-voice-api-service-specification-updates.mdx b/api-reference/voice/deepl-voice-api-service-specification-updates.mdx index a0172fb8..b7feb066 100644 --- a/api-reference/voice/deepl-voice-api-service-specification-updates.mdx +++ b/api-reference/voice/deepl-voice-api-service-specification-updates.mdx @@ -1,5 +1,6 @@ --- title: "DeepL Voice API Service Specification Updates" +description: "Service specification terms for the DeepL Voice API, including how audio minutes are defined and measured." --- diff --git a/api-reference/voice/reconnect-session.mdx b/api-reference/voice/reconnect-session.mdx index 52bcf1b1..2537dfea 100644 --- a/api-reference/voice/reconnect-session.mdx +++ b/api-reference/voice/reconnect-session.mdx @@ -1,4 +1,5 @@ --- openapi: get /v3/voice/realtime title: "Reconnect Session" +description: "Reconnect to an interrupted real-time voice translation session and resume streaming audio." --- diff --git a/api-reference/voice/request-session.mdx b/api-reference/voice/request-session.mdx index ffbf9b23..b3f9b9f6 100644 --- a/api-reference/voice/request-session.mdx +++ b/api-reference/voice/request-session.mdx @@ -1,4 +1,5 @@ --- openapi: post /v3/voice/realtime title: "Request Session" +description: "Request a real-time voice translation session and receive the WebSocket streaming URL to connect to." --- diff --git a/api-reference/voice/websocket-streaming.mdx b/api-reference/voice/websocket-streaming.mdx index 0406350b..77e14566 100644 --- a/api-reference/voice/websocket-streaming.mdx +++ b/api-reference/voice/websocket-streaming.mdx @@ -1,4 +1,5 @@ --- asyncapi: voiceStream title: "WebSocket Streaming" +description: "AsyncAPI reference for the real-time voice WebSocket protocol, covering the messages sent in each direction." --- \ No newline at end of file diff --git a/docs.json b/docs.json index 38559381..b4873789 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" + }, + { + "source": "/contact-us", + "destination": "/docs/resources/contact" + }, + { + "source": "/support", + "destination": "/docs/resources/contact" + }, + { + "source": "/privacy", + "destination": "/docs/resources/privacy" + }, + { + "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\",\"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/cors-requests.mdx b/docs/best-practices/cors-requests.mdx index a184a730..dd8b48dd 100644 --- a/docs/best-practices/cors-requests.mdx +++ b/docs/best-practices/cors-requests.mdx @@ -1,5 +1,6 @@ --- title: "CORS requests" +description: "Why the DeepL API rejects requests sent directly from a browser, and how to call it from your backend instead." mode: "wide" public: true --- diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 4ecbc39c..79f4b1ef 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -1,5 +1,6 @@ --- title: "Document translations" +description: "Handle file size limits, status codes, and error details when translating documents with the DeepL API." mode: "wide" public: true --- 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/best-practices/language-detection.mdx b/docs/best-practices/language-detection.mdx index 24f2a4ce..f7e9e52c 100644 --- a/docs/best-practices/language-detection.mdx +++ b/docs/best-practices/language-detection.mdx @@ -1,5 +1,6 @@ --- title: "Language detection" +description: "How DeepL detects the source language automatically, and why setting it yourself improves translation quality." mode: "wide" public: true --- diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx index 5a88d6b1..4b622cc3 100644 --- a/docs/getting-started/about.mdx +++ b/docs/getting-started/about.mdx @@ -1,5 +1,6 @@ --- title: "About" +description: "What the DeepL API offers, the use cases it covers, and which product to reach for when adding translation to your app." 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/getting-started/client-libraries-reference.mdx b/docs/getting-started/client-libraries-reference.mdx index 69934885..d82720b4 100644 --- a/docs/getting-started/client-libraries-reference.mdx +++ b/docs/getting-started/client-libraries-reference.mdx @@ -1,5 +1,6 @@ --- title: "Client libraries" +description: "The official DeepL client libraries for C#, Java, JavaScript, PHP, Python, and Ruby, with links to each repository." public: true --- ## Official client libraries diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index effedb43..15217e0e 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -1,5 +1,6 @@ --- title: "Quickstart" +description: "Get a DeepL API key and send your first translation request, with examples in curl and every official client library." public: true mode: "wide" --- diff --git a/docs/getting-started/supported-languages.mdx b/docs/getting-started/supported-languages.mdx index 5137fa22..98958bce 100644 --- a/docs/getting-started/supported-languages.mdx +++ b/docs/getting-started/supported-languages.mdx @@ -1,6 +1,6 @@ --- title: "Languages supported" -description: "The DeepL API supports the following languages." +description: "Every language the DeepL API supports, and how to retrieve the list programmatically with feature availability." public: true sidebarTitle: "Languages supported" mode: "wide" diff --git a/docs/resources/breaking-changes-change-notices.mdx b/docs/resources/breaking-changes-change-notices.mdx index 917cd2cb..ac6c2000 100644 --- a/docs/resources/breaking-changes-change-notices.mdx +++ b/docs/resources/breaking-changes-change-notices.mdx @@ -1,5 +1,6 @@ --- title: "Breaking changes (Change Notices)" +description: "Planned DeepL API deprecations and breaking changes that may affect your integration, with the notice for each." sidebarTitle: "Overview" mode: "wide" --- diff --git a/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites.mdx b/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites.mdx index 956e33fc..2a07833d 100644 --- a/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites.mdx +++ b/docs/resources/breaking-changes-change-notices/july-2024-deprecation-of-insecure-cipher-suites.mdx @@ -1,5 +1,6 @@ --- title: "July 2024: Deprecation of insecure cipher suites" +description: "DeepL deprecated insecure TLS cipher suites in 2024. Check which suites your TLS library negotiates if handshakes fail." --- ## Change Notice diff --git a/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx b/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx index d450e206..ed2aa884 100644 --- a/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx +++ b/docs/resources/breaking-changes-change-notices/march-2025-deprecating-get-requests-to-translate-and-authenticating-with-auth_key.mdx @@ -1,5 +1,6 @@ --- title: "March 2025: Deprecating GET requests to /translate and authenticating with auth_key" +description: "DeepL deprecated GET requests to /translate and auth_key authentication in March 2025. Use POST with an Authorization header." --- diff --git a/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods.mdx b/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods.mdx index 7e244a30..3353ecbb 100644 --- a/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods.mdx +++ b/docs/resources/breaking-changes-change-notices/november-2025-deprecation-of-legacy-auth-methods.mdx @@ -1,5 +1,6 @@ --- title: "November 2025: Deprecation of query parameter and request body authentication" +description: "DeepL is removing auth_key query parameter and request body authentication. Move to the Authorization header before the deadline." --- ## Change Notice 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/deepl-developer-community.mdx b/docs/resources/deepl-developer-community.mdx index 369dcbfd..e991e212 100644 --- a/docs/resources/deepl-developer-community.mdx +++ b/docs/resources/deepl-developer-community.mdx @@ -1,5 +1,6 @@ --- title: "Developer Community" +description: "Join the official DeepL developer community on Discord to ask questions and talk to other developers building on the API." mode: "wide" --- 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..626ab9e4 --- /dev/null +++ b/docs/resources/privacy.mdx @@ -0,0 +1,27 @@ +--- +title: "Privacy" +description: "Where to find DeepL's privacy policy, terms, and data security information, and what to plan for in your integration." +--- + +## 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 customers 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). diff --git a/docs/resources/usage-limits.mdx b/docs/resources/usage-limits.mdx index 8749810e..fde93b49 100644 --- a/docs/resources/usage-limits.mdx +++ b/docs/resources/usage-limits.mdx @@ -1,5 +1,6 @@ --- title: "Usage and limits" +description: "Request size, header, and character limits for the DeepL API, plus the maximum upload size for each document format." --- ### API Limits