From 37fb52241c81219758b48c6d1e1818fbe2b92c88 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Fri, 20 May 2022 15:21:57 +0200 Subject: [PATCH] Add OpenAPI spec, changelog and readme --- .gitignore | 1 + CHANGELOG.md | 17 + README.md | 27 +- openapi.json | 1751 ++++++++++++++++++++++++++++++++++++++++++++++++++ openapi.yaml | 1525 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 3320 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 openapi.json create mode 100644 openapi.yaml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9f11b75 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d2e6355 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,17 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +The major and minor version numbers reflect changes to the DeepL API +(backward-incompatible and backward-compatible, respectively). The patch version +number is used only for corrections to the OpenAPI specification, for example: +typos, schema fixes, or adding examples. + + +## [2.0.0] +Initial release of the OpenAPI specification. + + +[2.0.0]: https://github.com/DeepLcom/openapi/releases/tag/v2.0.0 diff --git a/README.md b/README.md index 9291040..e7f7f80 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,27 @@ -# openapi +# DeepL OpenAPI Specification +This project contains an [OpenAPI specification][openapi-specification] of the +[DeepL API][deepl-api], in [YAML](openapi.yaml) and [JSON](openapi.json) +formats. + +You can use this specification to explore the API in tools like +[Postman][postman], or to auto-generate documentation, SDKs, and code libraries +using tools such as [Swagger Editor][swagger-editor] or +[OpenAPI Generator][openapi-generator]. + +[Changelog](CHANGELOG.md) + +If you encounter issues while using this OpenAPI specification or have feature +requests, please [create an issue][issues]. + +[deepl-api]: https://www.deepl.com/pro-api + +[issues]: https://github.com/DeepLcom/openapi/issues + +[openapi-specification]: https://openapis.org/ + +[openapi-generator]: https://openapi-generator.tech/ + +[postman]: https://www.postman.com/ + +[swagger-editor]: https://editor.swagger.io/?url=https://raw.githubusercontent.com/DeepLcom/openapi/main/openapi.yaml \ No newline at end of file diff --git a/openapi.json b/openapi.json new file mode 100644 index 0000000..d571f8f --- /dev/null +++ b/openapi.json @@ -0,0 +1,1751 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "DeepL API", + "description": "The DeepL API provides programmatic access to DeepL\u2019s machine translation technology.", + "termsOfService": "https://www.deepl.com/pro-license/", + "contact": { + "name": "DeepL - Contact us", + "url": "https://www.deepl.com/contact-us" + }, + "version": "2.0.0" + }, + "externalDocs": { + "description": "DeepL Pro - Plans and pricing", + "url": "https://www.deepl.com/pro?cta=header-prices/" + }, + "servers": [ + { + "url": "https://api.deepl.com/v2", + "description": "DeepL API Pro" + }, + { + "url": "https://api-free.deepl.com/v2", + "description": "DeepL API Free" + } + ], + "tags": [ + { + "name": "TranslatingText", + "description": "The text-translation API currently consists of a single endpoint, `translate`, which is described below." + }, + { + "name": "HandlingXML", + "description": "By default, the translation engine does not take tags into account.\nBy setting the `tag_handling` parameter to `xml`, the API will process XML input by extracting text out of the structure,\nsplitting it into individual sentences, translating them, and placing them back into the XML structure.\n\nFor the translation of HTML content please see [Handling HTML (Beta)](https://www.deepl.com/docs-api/html) \n\nWe will look at the XML handling engine in the following cases:\n\n- Sentences with markup\n- Structured content\n- Restricting splitting\n- Disabling automatic outline detection\n- Splitting on newlines\n- Ignored text" + }, + { + "name": "HandlingHTML", + "description": "By default, the translation engine does not take HTML tags into account.\nBy setting the `tag_handling` parameter to `html`, the API will process HTML input by extracting text\nout of the structure, splitting it into individual sentences, translating them, and placing them back\ninto the HTML structure.\nThis functionality is in beta. If you encounter issues, please let us know at support@DeepL.com.\n\nFor the translation of generic XML content please see [Handling XML](https://www.deepl.com/docs-api/xml)" + }, + { + "name": "TranslatingDocuments", + "description": "The document translation API allows you to translate whole documents.\nTranslating a document usually involves three types of HTTP requests:\n- [upload](https://www.deepl.com/docs-api/documents/translate-document) the document to be translated,\n- periodically [check the status](https://www.deepl.com/docs-api/documents/get-document-status) of the document translation,\n- once the status call reports `done`, [download](https://www.deepl.com/docs-api/documents/download-document) the translated document.\n\nPlease note that with every submitted document of type .pptx, .docx, or .pdf,\nyou are billed a minimum of 50,000 characters with the DeepL API plan,\nno matter how many characters are included in the document." + }, + { + "name": "ManagingGlossaries", + "description": "The *glossary* functions allow you to create, inspect, and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently, glossaries for the following language combinations are supported:\n\n- EN (English) \u2192 DE (German)\n- DE (German) \u2192 EN (English)\n- EN (English) \u2192 FR (French)\n- FR (French) \u2192 EN (English)\n- EN (English) \u2192 ES (Spanish)\n- ES (Spanish) \u2192 EN (English)\n- EN (English) \u2192 JA (Japanese)\n- JA (Japanese) \u2192 EN (English)\n- DE (German) \u2192 FR (French)\n- FR (French) \u2192 DE (German)\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\n\nGlossaries created via the DeepL API are distinct from glossaries created via the DeepL website and DeepL apps.\nThis means API glossaries cannot be used on the website and vice versa." + }, + { + "name": "MetaInformation", + "description": "Information about API usage and value ranges" + } + ], + "paths": { + "/translate": { + "post": { + "tags": [ + "TranslatingText" + ], + "summary": "Request Translation", + "operationId": "translateText", + "description": "The translate function.", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "examples": { + "Basic": { + "summary": "Basic Example", + "value": { + "text": [ + "Hello, world" + ], + "target_lang": "DE" + } + }, + "Glossary": { + "summary": "Using a Glossary", + "value": { + "text": [ + "Hello, world" + ], + "target_lang": "DE", + "source_lang": "EN", + "glossary_id": "[yourGlossaryId]" + } + }, + "MultipleSentences": { + "summary": "Multiple Sentences", + "value": { + "text": [ + "The table is green. The chair is black." + ], + "target_lang": "DE" + } + }, + "LargeVolumes": { + "summary": "Large Volumes of Text", + "value": { + "text": [ + "This is the first sentence.", + "This is the second sentence.", + "This is the third sentence." + ], + "target_lang": "DE" + } + } + }, + "schema": { + "type": "object", + "required": [ + "text", + "target_lang" + ], + "properties": { + "text": { + "description": "Text to be translated. Only UTF-8-encoded plain text is supported. The parameter may be specified multiple times and translations are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences. Up to 50 texts can be sent for translation in one request.", + "type": "array", + "maxItems": 50, + "items": { + "type": "string" + } + }, + "source_lang": { + "$ref": "#/components/schemas/SourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguage" + }, + "split_sentences": { + "description": "Sets whether the translation engine should first split the input into sentences. This is enabled by default. Possible values are:\n * `0` - no splitting at all, whole input is treated as one sentence\n * `1` - splits on punctuation and on newlines\n * `nonewlines` - splits on punctuation only, ignoring newlines\n\nFor applications that send one sentence per text parameter, it is advisable to set `split_sentences` to `0`, in order to prevent the engine from splitting the sentence unintentionally.\n\n\nPlease note that newlines will split sentences. You should therefore clean files to avoid breaking sentences or set the parameter `split_sentences` to `nonewlines`. In the example below, the two parts of the sentence have been translated separately and this has caused an error: The word \"the\" has been incorrectly translated as \"die\" (the feminine definite article in German), though the German word for \"sentence\", \"Satz\", is masculine (der Satz).\n * Example request:\n```\n
This is the first\nsentence.
\n```\n * Example response:\n```\n
Dies ist die erste\nSatz.
\n```", + "type": "string", + "enum": [ + "0", + "1", + "nonewlines" + ], + "default": "1" + }, + "preserve_formatting": { + "description": "Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. Possible values are:\n * `0`\n * `1`\n\nThe formatting aspects affected by this setting include:\n * Punctuation at the beginning and end of the sentence\n * Upper/lower case at the beginning of the sentence", + "type": "string", + "enum": [ + "0", + "1" + ], + "default": "0" + }, + "formality": { + "$ref": "#/components/schemas/Formality" + }, + "glossary_id": { + "description": "Specify the glossary to use for the translation. **Important:** This requires the `source_lang` parameter to be set and the language pair of the glossary has to match the language pair of the request.", + "type": "string" + }, + "tag_handling": { + "description": "Sets which kind of tags should be handled. Options currently available:\n * `xml`: Enable XML tag handling; see [Handling XML](https://www.deepl.com/docs-api/xml).\n * `html`: Enable HTML tag handling; see [Handling HTML (Beta)](https://www.deepl.com/docs-api/html).", + "type": "string", + "enum": [ + "xml", + "html" + ] + }, + "non_splitting_tags": { + "description": "Comma-separated list of XML tags which never split sentences.\n\n\nFor some XML files, finding tags with textual content and splitting sentences using those tags won't yield the best results. The following example shows the engine splitting sentences on `par` tags and proceeding to translate the parts separately, resulting in an incorrect translation:\n * Example request:\n```\nThe firm said it had been conducting an internal investigation.\n```\n * Example response:\n```\nDie Firma sagte, es sei eine gute Idee gewesen. Durchf\u00fchrung einer internen Untersuchung.\n```\n\n\nAs this can lead to bad translations, this type of structure should either be avoided, or the `non_splitting_tags` parameter should be set. The following example shows the same call, with the parameter set to `par`:\n * Example request:\n```\nThe firm said it had been conducting an internal investigation.\n```\n * Example response:\n```\nDie Firma sagte, dass sie eine interne Untersuchung durchgef\u00fchrt habe.\n```\n\n\nThis time, the sentence is translated as a whole. The XML tags are now considered markup and copied into the translated sentence. As the translation of the words \"had been\" has moved to another position in the German sentence, the two par tags are duplicated (which is expected here).", + "type": "string" + }, + "outline_detection": { + "description": "The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the `outline_detection` parameter to `0` and selecting the tags that should be considered structure tags. This will split sentences using the `splitting_tags` parameter.\n\n\nIn the example below, we achieve the same results as the automatic engine by disabling automatic detection with `outline_detection=0` and setting the parameters manually to `tag_handling=xml`, `split_sentences=nonewlines`, and `splitting_tags=par,title`.\n * Example request:\n\n\n \n \n A document's title\n \n \n This is the first sentence. Followed by a second one.\n This is the third sentence.\n \n \n\n * Example response:\n\n\n \n \n Der Titel eines Dokuments\n \n \n Das ist der erste Satz. Gefolgt von einem zweiten.\n Dies ist der dritte Satz.\n \n \n\n\nWhile this approach is slightly more complicated, it allows for greater control over the structure of the translation output.", + "type": "string", + "enum": [ + "0" + ] + }, + "splitting_tags": { + "description": "Comma-separated list of XML tags which always cause splits.\n\n\nSee the example in the `outline_detection` parameter's description.", + "type": "string" + }, + "ignore_tags": { + "description": "Comma-separated list of XML tags that indicate text not to be translated.\n\n\nUse this paramter to ensure that elements in the original text are not altered in the translation (e.g., trademarks, product names) and insert tags into your original text. In the following example, the `ignore_tags` parameter is set to `keep`:\n * Example request:\n```\nPlease open the page Settings to configure your system.\n```\n * Example response:\n```\nBitte \u00f6ffnen Sie die Seite Settings um Ihr System zu konfigurieren.\n```", + "type": "string" + } + } + }, + "encoding": { + "text": { + "style": "form", + "explode": true + } + } + } + } + }, + "responses": { + "200": { + "description": "The translate function returns a JSON representation of the translations in the order the text parameters have been specified.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "translations": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "detected_source_language": { + "allOf": [ + { + "$ref": "#/components/schemas/SourceLanguage" + }, + { + "description": "The language detected in the source text. It reflects the value of the `source_lang` parameter, when specified." + } + ] + }, + "text": { + "description": "The translated text.", + "type": "string" + } + } + } + } + } + }, + "examples": { + "Basic": { + "value": { + "translations": [ + { + "detected_source_language": "EN", + "text": "Hallo, Welt!" + } + ] + } + }, + "Glossary": { + "value": { + "translations": [ + { + "text": "Hallo, Welt!" + } + ] + } + }, + "MultipleSentences": { + "value": { + "translations": [ + { + "detected_source_language": "EN", + "text": "Der Tisch ist gr\u00fcn. Der Stuhl ist schwarz." + } + ] + } + }, + "LargeVolumes": { + "value": { + "translations": [ + { + "detected_source_language": "EN", + "text": "Das ist der erste Satz." + }, + { + "detected_source_language": "EN", + "text": "Das ist der zweite Satz." + }, + { + "detected_source_language": "EN", + "text": "Dies ist der dritte Satz." + } + ] + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "414": { + "$ref": "#/components/responses/URITooLong" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/document": { + "post": { + "tags": [ + "TranslatingDocuments" + ], + "summary": "Upload and Translate a Document", + "operationId": "translateDocument", + "description": "This call uploads a document and queues it for translation.\nThe call returns once the upload is complete, returning a document ID and key which can be used to\n[query the translation status](https://www.deepl.com/docs-api/documents/get-document-status)\nand to [download the translated document](https://www.deepl.com/docs-api/documents/download-document) once translation is complete.\n\n\n\nBecause the request includes a file upload, it must be an HTTP POST request with content type `multipart/form-data`.\n\n\nPlease be aware that the uploaded document is automatically removed from the server once the translated document has been downloaded.\nYou have to upload the document again in order to restart the translation.\n\n\nThe maximum upload limit for any document is 10 MiB and 1.000.000 characters.\n\n\nYou may specify the glossary to use for the document translation using the `glossary_id` parameter.\n**Important:** This requires the `source_lang` parameter to be set and the language pair of the glossary has to match the language pair of the request.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "example": { + "target_lang": "DE" + }, + "schema": { + "type": "object", + "required": [ + "target_lang", + "file" + ], + "properties": { + "source_lang": { + "$ref": "#/components/schemas/SourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguage" + }, + "file": { + "type": "string", + "format": "binary", + "description": "The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n\nPlease note that in order to translate PDF documents you need to give one-time consent to using the Adobe API via the account interface." + }, + "filename": { + "type": "string", + "description": "The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition." + }, + "formality": { + "$ref": "#/components/schemas/Formality" + }, + "glossary_id": { + "$ref": "#/components/schemas/GlossaryId" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The document function returns a JSON object containing the ID and encryption key assigned to the uploaded document. Once received by the server, uploaded documents are immediately encrypted using a uniquely generated encryption key. This key is not persistently stored on the server. Therefore, it must be stored by the client and sent back to the server with every subsequent request that refers to this particular document.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "document_id": { + "description": "A unique ID assigned to the uploaded document and the translation process. Must be used when referring to this particular document in subsequent API requests.", + "type": "string" + }, + "document_key": { + "description": "A unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. Must be provided with every subsequent API request regarding this particular document.", + "type": "string" + } + } + }, + "example": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/document/{document_id}": { + "post": { + "tags": [ + "TranslatingDocuments" + ], + "summary": "Check Document Status", + "description": "Retrieve the current status of a document translation process.\nIf the translation is still in progress, the estimated time remaining is also included in the response.", + "operationId": "getDocumentStatus", + "parameters": [ + { + "$ref": "#/components/parameters/DocumentID" + } + ], + "requestBody": { + "$ref": "#/components/requestBodies/DocumentKey" + }, + "responses": { + "200": { + "description": "The document status request returns a JSON object containing the document ID that was used in the request as well as string indicating the current status of the translation process. While the translation is running, the estimated number of seconds remaining until the process is done is also included in the response.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_id", + "status" + ], + "properties": { + "document_id": { + "description": "A unique ID assigned to the uploaded document and the requested translation process. The same ID that was used when requesting the translation status.", + "type": "string" + }, + "status": { + "description": "A short description of the state the document translation process is currently in. Possible values are:\n * `queued` - the translation job is waiting in line to be processed\n * `translating` - the translation is currently ongoing\n * `done` - the translation is done and the translated document is ready for download\n * `error` - an irrecoverable error occurred while translating the document", + "type": "string", + "enum": [ + "queued", + "translating", + "done", + "error" + ] + }, + "seconds_remaining": { + "description": "Estimated number of seconds until the translation is done.\nThis parameter is only included while `status` is `\"translating\"`.", + "type": "integer" + }, + "billed_characters": { + "description": "The number of characters billed to your account.", + "type": "integer" + }, + "error_message": { + "description": "A short description of the error, if available.\nNote that the content is subject to change.\nThis parameter may be included if an error occurred during translation.", + "type": "string" + } + } + }, + "examples": { + "translating": { + "summary": "Translating", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "translating", + "seconds_remaining": 20 + } + }, + "done": { + "summary": "Done", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "done", + "billed_characters": 1337 + } + }, + "queued": { + "summary": "Queued", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "queued" + } + }, + "error": { + "summary": "Error", + "value": { + "document_id": "04DE5AD98A02647D83285A36021911C6", + "status": "error", + "message": "Source and target language are equal." + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/document/{document_id}/result": { + "post": { + "tags": [ + "TranslatingDocuments" + ], + "summary": "Download Translated Document", + "operationId": "downloadDocument", + "description": "Once the status of the document translation process is `done`, the result can be downloaded.\n\n\nFor privacy reasons the translated document is automatically removed from the server once it was downloaded and cannot be downloaded again.", + "parameters": [ + { + "$ref": "#/components/parameters/DocumentID" + } + ], + "requestBody": { + "$ref": "#/components/requestBodies/DocumentKey" + }, + "responses": { + "200": { + "description": "The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type.", + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + }, + "examples": { + "OK": { + "summary": "OK", + "description": "binary document data" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound404DocTransDownload" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable503DocTransDownload" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/glossary-language-pairs": { + "get": { + "tags": [ + "ManagingGlossaries" + ], + "summary": "List Language Pairs Supported by Glossaries", + "description": "Retrieve the list of language pairs supported by the glossary feature.", + "operationId": "listGlossaryLanguages", + "responses": { + "200": { + "description": "A JSON object containing the language pairs in its `supported_languages` property.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "supported_languages": { + "type": "array", + "description": "The list of supported languages", + "items": { + "type": "object", + "required": [ + "source_lang", + "target_lang" + ], + "properties": { + "source_lang": { + "description": "The language in which the source texts in the glossary are specified.", + "type": "string" + }, + "target_lang": { + "description": "The language in which the target texts in the glossary are specified.", + "type": "string" + } + } + } + } + } + }, + "example": { + "supported_languages": [ + { + "source_lang": "de", + "target_lang": "en" + }, + { + "source_lang": "en", + "target_lang": "de" + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/glossaries": { + "post": { + "tags": [ + "ManagingGlossaries" + ], + "summary": "Create a Glossary", + "operationId": "createGlossary", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "required": [ + "name", + "source_lang", + "target_lang", + "entries", + "entries_format" + ], + "properties": { + "name": { + "description": "Name to be associated with the glossary.", + "type": "string", + "example": "My Glossary" + }, + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "entries": { + "description": "The entries of the glossary. The entries have to be specified in the format provided by the `entries_format` parameter.", + "type": "string", + "example": "Hello!\tGuten Tag!" + }, + "entries_format": { + "description": "The format in which the glossary entries are provided. Formats currently available:\n* `tsv` - Tab-separated values. Entries have to be specified as tab-separated values with the \"source entry\" being the text in the source language of the glossary and the \"target entry\" being the text in the target language of the glossary.\n\n In addition the following restrictions apply:\n * Duplicate source entries are not allowed.\n * Source-target entry pairs are separated by a newline.\n * Source entries and target entries are separated by a tab.\n * Source entries and target entries are not empty.\n * Source and target entries must not contain any [C0 or C1 control characters](https://en.wikipedia.org/wiki/C0_and_C1_control_codes) (including e.g. `\"\\t\"` or `\"\\n\"`) or any [Unicode newline](https://en.wikipedia.org/wiki/Newline#Unicode).\n * Source and target entries must not contain any leading or trailing Unicode whitespace.\n\n Valid glossary entries in the TSV format could be created in a programming language with backslash escape sequences (e.g. Python, JavaScript, etc.) like this:\n\n `\"sourceEntry1\\ttargetEntry1\\nsourceEntry2\\targetEntry2\"`", + "type": "string", + "enum": [ + "tsv" + ], + "example": "tsv" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The function for creating a glossary returns a JSON object containing the ID of the newly created glossary and a boolean flag that indicates if the created glossary can already be used in translate requests.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Glossary" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "get": { + "tags": [ + "ManagingGlossaries" + ], + "summary": "List all Glossaries", + "operationId": "listGlossaries", + "description": "List all glossaries and their meta-information, but not the glossary entries.", + "responses": { + "200": { + "description": "JSON object containing a the glossaries.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "glossaries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Glossary" + } + } + } + }, + "example": { + "glossaries": [ + { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "ready": true, + "source_lang": "EN", + "target_lang": "DE", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/glossaries/{glossary_id}": { + "get": { + "tags": [ + "ManagingGlossaries" + ], + "summary": "Retrieve Glossary Details", + "description": "Retrieve meta information for a single glossary, omitting the glossary entries.", + "operationId": "getGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "responses": { + "200": { + "description": "JSON object containing the glossary meta-information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Glossary" + }, + "example": { + "id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "name": "My Glossary", + "ready": true, + "source_lang": "EN", + "target_lang": "DE", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + }, + "delete": { + "tags": [ + "ManagingGlossaries" + ], + "summary": "Delete a Glossary", + "description": "Deletes the specified glossary.", + "operationId": "deleteGlossary", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + } + ], + "responses": { + "204": { + "description": "Returns no content upon success." + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/glossaries/{glossary_id}/entries": { + "get": { + "tags": [ + "ManagingGlossaries" + ], + "summary": "Retrieve Glossary Entries", + "operationId": "getGlossaryEntries", + "description": "List the entries of a single glossary in the format specified by the `Accept` header.", + "parameters": [ + { + "$ref": "#/components/parameters/GlossaryID" + }, + { + "name": "Accept", + "in": "header", + "schema": { + "type": "string", + "enum": [ + "text/tab-separated-values" + ], + "default": "text/tab-separated-values" + }, + "description": "The requested format of the returned glossary entries. Currently, supports only `text/tab-separated-values`.", + "example": "text/tab-separated-values" + } + ], + "responses": { + "200": { + "description": "The entries in the requested format.", + "content": { + "text/tab-separated-values": { + "example": "Hello!\tGuten Tag!" + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequestGlossaries" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/ForbiddenGlossaries" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedMediaTypeGlossaries" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "503": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/usage": { + "get": { + "tags": [ + "MetaInformation" + ], + "summary": "Check Usage and Limits", + "description": "Retrieve usage information within the current billing period together with the corresponding account limits. Usage is returned for:\n- translated characters\n- translated documents\n- translated documents, team totals (for team accounts only)\n\nCharacter usage includes both text and document translations, and is measured by the source text length in Unicode code points,\nso for example \"A\", \"\u0394\", \"\u3042\", and \"\u6df1\" are each counted as a single character.\n\nDocument usage only includes document translations, and is measured in individual documents.\n\nDepending on the user account type, some usage types will be omitted.\nCharacter usage is only included for developer accounts.\nDocument usage is only included for non-developer accounts, and team-combined document usage is only included for non-developer team accounts.", + "operationId": "getUsage", + "responses": { + "200": { + "description": "The account's usage and limits.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "character_count": { + "description": "Characters translated so far in the current billing period.", + "type": "integer", + "format": "int64" + }, + "character_limit": { + "description": "Current maximum number of characters that can be translated per billing period.", + "type": "integer", + "format": "int64" + }, + "document_limit": { + "description": "Documents translated so far in the current billing period.", + "type": "integer", + "format": "int64" + }, + "document_count": { + "description": "Current maximum number of documents that can be translated per billing period.", + "type": "integer", + "format": "int64" + }, + "team_document_limit": { + "description": "Documents translated by all users in the team so far in the current billing period.", + "type": "integer", + "format": "int64" + }, + "team_document_count": { + "description": "Current maximum number of documents that can be translated by the team per billing period.", + "type": "integer", + "format": "int64" + } + } + }, + "example": { + "character_count": 180118, + "character_limit": 1250000 + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, + "/languages": { + "get": { + "tags": [ + "MetaInformation" + ], + "summary": "Retrieve Supported Languages", + "description": "Retrieve the list of languages that are currently supported for translation, either as source or target language, respectively.", + "operationId": "getLanguages", + "parameters": [ + { + "name": "type", + "in": "query", + "description": "Sets whether source or target languages should be listed. Possible options are:\n * `source` (default): For languages that can be used in the `source_lang` parameter of [translate](https://www.deepl.com/docs-api/translating-text/translate-text) requests.\n * `target`: For languages that can be used in the `target_lang` parameter of [translate](https://www.deepl.com/docs-api/translating-text/translate-text) requests.", + "schema": { + "type": "string", + "enum": [ + "source", + "target" + ], + "default": "source" + }, + "example": "target" + } + ], + "responses": { + "200": { + "description": "JSON array where each item represents a supported language.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "required": [ + "language", + "name" + ], + "properties": { + "language": { + "description": "The language code of the given language.", + "type": "string" + }, + "name": { + "description": "Name of the language in English.", + "type": "string" + }, + "supports_formality": { + "description": "Denotes formality support in case of a target language listing.", + "type": "boolean" + } + } + } + }, + "example": [ + { + "language": "BG", + "name": "Bulgarian", + "supports_formality": false + }, + { + "language": "CS", + "name": "Czech", + "supports_formality": false + }, + { + "language": "DA", + "name": "Danish", + "supports_formality": false + }, + { + "language": "DE", + "name": "German", + "supports_formality": true + }, + { + "language": "EL", + "name": "Greek", + "supports_formality": false + }, + { + "language": "EN-GB", + "name": "English (British)", + "supports_formality": false + }, + { + "language": "EN-US", + "name": "English (American)", + "supports_formality": false + }, + { + "language": "ES", + "name": "Spanish", + "supports_formality": true + }, + { + "language": "ET", + "name": "Estonian", + "supports_formality": false + }, + { + "language": "FI", + "name": "Finnish", + "supports_formality": false + }, + { + "language": "FR", + "name": "French", + "supports_formality": true + }, + { + "language": "HU", + "name": "Hungarian", + "supports_formality": false + }, + { + "language": "ID", + "name": "Indonesian", + "supports_formality": false + }, + { + "language": "IT", + "name": "Italian", + "supports_formality": true + }, + { + "language": "JA", + "name": "Japanese", + "supports_formality": false + }, + { + "language": "LT", + "name": "Lithuanian", + "supports_formality": false + }, + { + "language": "LV", + "name": "Latvian", + "supports_formality": false + }, + { + "language": "NL", + "name": "Dutch", + "supports_formality": true + }, + { + "language": "PL", + "name": "Polish", + "supports_formality": true + }, + { + "language": "PT-BR", + "name": "Portuguese (Brazilian)", + "supports_formality": true + }, + { + "language": "PT-PT", + "name": "Portuguese (European)", + "supports_formality": true + }, + { + "language": "RO", + "name": "Romanian", + "supports_formality": false + }, + { + "language": "RU", + "name": "Russian", + "supports_formality": true + }, + { + "language": "SK", + "name": "Slovak", + "supports_formality": false + }, + { + "language": "SL", + "name": "Slovenian", + "supports_formality": false + }, + { + "language": "SV", + "name": "Swedish", + "supports_formality": false + }, + { + "language": "TR", + "name": "Turkish", + "supports_formality": false + }, + { + "language": "ZH", + "name": "Chinese", + "supports_formality": false + } + ] + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + }, + "529": { + "$ref": "#/components/responses/TooManyRequests" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + } + }, + "components": { + "parameters": { + "DocumentID": { + "name": "document_id", + "description": "The document ID that was sent to the client when the document was uploaded to the API.", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "example": "04DE5AD98A02647D83285A36021911C6" + }, + "GlossaryID": { + "name": "glossary_id", + "description": "A unique ID assigned to the glossary.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + "SourceLanguage": { + "name": "source_lang", + "in": "query", + "schema": { + "$ref": "#/components/schemas/SourceLanguage" + } + }, + "TargetLanguage": { + "name": "target_lang", + "in": "query", + "required": true, + "schema": { + "$ref": "#/components/schemas/TargetLanguage" + } + } + }, + "responses": { + "BadRequest": { + "description": "Bad request. Please check error message and your parameters." + }, + "BadRequestGlossaries": { + "description": "Bad request. Please check error message and your parameters.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "description": "Generic description of the error.", + "type": "string" + }, + "detail": { + "description": "More specific description of the error.", + "type": "string" + } + } + }, + "example": { + "message": "Invalid glossary entries provided", + "detail": "Key with the index 1 (starting at position 13) duplicates key with the index 0 (starting at position 0)" + } + } + } + }, + "Unauthorized": { + "description": "Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header." + }, + "Forbidden": { + "description": "Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header." + }, + "ForbiddenGlossaries": { + "description": "Forbidden. The access to the requested resource is denied, because of insufficient access rights." + }, + "NotFound": { + "description": "The requested resource could not be found." + }, + "NotFound404DocTransDownload": { + "description": "Trying to download a document using a non-existing document ID or the wrong document key will result in a 404 error. As stated above, documents can only be downloaded once before they are deleted from the server and their document ID is invalidated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentTranslationError" + }, + "examples": { + "NotFound": { + "summary": "Not Found", + "value": { + "message": "Document not found" + } + } + } + } + } + }, + "PayloadTooLarge": { + "description": "The request size exceeds the limit." + }, + "URITooLong": { + "description": "The request URL is too long. You can avoid this error by using a POST request instead of a GET request, and sending the parameters in the HTTP body." + }, + "UnsupportedMediaTypeGlossaries": { + "description": "The requested entries format specified in the `Accept` header is not supported." + }, + "TooManyRequests": { + "description": "Too many requests. Please wait and resend your request." + }, + "QuotaExceeded": { + "description": "Quota exceeded. The character limit has been reached." + }, + "InternalServerError": { + "description": "Internal error." + }, + "ServiceUnavailable": { + "description": "Resource currently unavailable. Try again later." + }, + "ServiceUnavailable503DocTransDownload": { + "description": "A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download.\nPlease make sure to check that the document status is 'done' before trying to send a download request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentTranslationError" + }, + "examples": { + "AlreadyDownloaded": { + "summary": "Already downloaded", + "value": { + "message": "Document already downloaded" + } + } + } + } + } + } + }, + "securitySchemes": { + "auth_header": { + "type": "apiKey", + "description": "Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme", + "name": "Authorization", + "in": "header" + } + }, + "requestBodies": { + "DocumentKey": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "required": [ + "document_key" + ], + "properties": { + "document_key": { + "description": "The document encryption key that was sent to the client when the document was uploaded to the API.", + "type": "string", + "example": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A" + } + } + } + } + } + } + }, + "schemas": { + "DocumentTranslationError": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "detailed error message" + } + } + }, + "Formality": { + "description": "Sets whether the translated text should lean towards formal or informal language.\nThis feature currently only works for target languages\n`DE` (German),\n`FR` (French),\n`IT` (Italian),\n`ES` (Spanish),\n`NL` (Dutch),\n`PL` (Polish),\n`PT-PT`,\n`PT-BR` (Portuguese)\nand `RU` (Russian).\nPossible options are:\n * `default`\n * `more` - for a more formal language\n * `less` - for a more informal language", + "type": "string", + "enum": [ + "default", + "more", + "less" + ], + "default": "default" + }, + "GlossaryId": { + "type": "string", + "description": "A unique ID assigned to a glossary.", + "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7" + }, + "Glossary": { + "type": "object", + "properties": { + "glossary_id": { + "$ref": "#/components/schemas/GlossaryId" + }, + "name": { + "description": "Name associated with the glossary.", + "type": "string" + }, + "ready": { + "description": "Indicates if the newly created glossary can already be used in `translate` requests.\nIf the created glossary is not yet ready, you have to wait and check the `ready` status\nof the glossary before using it in a `translate` request.", + "type": "boolean" + }, + "source_lang": { + "$ref": "#/components/schemas/GlossarySourceLanguage" + }, + "target_lang": { + "$ref": "#/components/schemas/GlossaryTargetLanguage" + }, + "creation_time": { + "description": "The creation time of the glossary in the ISO 8601-1:2019 format (e.g.: `2021-08-03T14:16:18.329Z`).", + "type": "string", + "format": "date-time" + }, + "entry_count": { + "description": "The number of entries in the glossary.", + "type": "integer" + } + }, + "example": { + "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7", + "ready": true, + "name": "My Glossary", + "source_lang": "en", + "target_lang": "de", + "creation_time": "2021-08-03T14:16:18.329Z", + "entry_count": 1 + } + }, + "GlossarySourceLanguage": { + "type": "string", + "description": "The language in which the source texts in the glossary are specified.", + "enum": [ + "de", + "en", + "es", + "fr", + "ja" + ], + "example": "de" + }, + "GlossaryTargetLanguage": { + "type": "string", + "description": "The language in which the target texts in the glossary are specified.", + "enum": [ + "de", + "en", + "es", + "fr", + "ja" + ], + "example": "en" + }, + "SourceLanguage": { + "type": "string", + "description": "Language of the text to be translated. Options currently available:\n * `BG` - Bulgarian\n * `CS` - Czech\n * `DA` - Danish\n * `DE` - German\n * `EL` - Greek\n * `EN` - English\n * `ES` - Spanish\n * `ET` - Estonian\n * `FI` - Finnish\n * `FR` - French\n * `HU` - Hungarian\n * `ID` - Indonesian\n * `IT` - Italian\n * `JA` - Japanese\n * `LT` - Lithuanian\n * `LV` - Latvian\n * `NL` - Dutch\n * `PL` - Polish\n * `PT` - Portuguese (all Portuguese varieties mixed)\n * `RO` - Romanian\n * `RU` - Russian\n * `SK` - Slovak\n * `SL` - Slovenian\n * `SV` - Swedish\n * `TR` - Turkish\n * `ZH` - Chinese\n\nIf this parameter is omitted, the API will attempt to detect the language of the text and translate it.", + "enum": [ + "BG", + "CS", + "DA", + "DE", + "EL", + "EN", + "ES", + "ET", + "FI", + "FR", + "HU", + "ID", + "IT", + "JA", + "LT", + "LV", + "NL", + "PL", + "PT", + "RO", + "RU", + "SK", + "SL", + "SV", + "TR", + "ZH" + ] + }, + "TargetLanguage": { + "type": "string", + "description": "The language into which the text should be translated. Options currently available:\n * `BG` - Bulgarian\n * `CS` - Czech\n * `DA` - Danish\n * `DE` - German\n * `EL` - Greek\n * `EN` - English (unspecified variant for backward compatibility; please select `EN-GB` or `EN-US` instead)\n * `EN-GB` - English (British)\n * `EN-US` - English (American)\n * `ES` - Spanish\n * `ET` - Estonian\n * `FI` - Finnish\n * `FR` - French\n * `HU` - Hungarian\n * `ID` - Indonesian\n * `IT` - Italian\n * `JA` - Japanese\n * `LT` - Lithuanian\n * `LV` - Latvian\n * `NL` - Dutch\n * `PL` - Polish\n * `PT` - Portuguese (unspecified variant for backward compatibility; please select `PT-BR` or `PT-PT` instead)\n * `PT-BR` - Portuguese (Brazilian)\n * `PT-PT` - Portuguese (all Portuguese varieties excluding Brazilian Portuguese)\n * `RO` - Romanian\n * `RU` - Russian\n * `SK` - Slovak\n * `SL` - Slovenian\n * `SV` - Swedish\n * `TR` - Turkish\n * `ZH` - Chinese", + "enum": [ + "BG", + "CS", + "DA", + "DE", + "EL", + "EN-GB", + "EN-US", + "ES", + "ET", + "FI", + "FR", + "HU", + "ID", + "IT", + "JA", + "LT", + "LV", + "NL", + "PL", + "PT-BR", + "PT-PT", + "RO", + "RU", + "SK", + "SL", + "SV", + "TR", + "ZH" + ] + } + } + } +} \ No newline at end of file diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..cd57ff0 --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,1525 @@ +openapi: 3.0.3 +info: + title: DeepL API + description: The DeepL API provides programmatic access to DeepL’s machine translation + technology. + termsOfService: https://www.deepl.com/pro-license/ + contact: + name: DeepL - Contact us + url: https://www.deepl.com/contact-us + version: 2.0.0 +externalDocs: + description: DeepL Pro - Plans and pricing + url: https://www.deepl.com/pro?cta=header-prices/ +servers: +- url: https://api.deepl.com/v2 + description: DeepL API Pro +- url: https://api-free.deepl.com/v2 + description: DeepL API Free +tags: +- name: TranslatingText + description: The text-translation API currently consists of a single endpoint, `translate`, + which is described below. +- name: HandlingXML + description: "By default, the translation engine does not take tags into account.\nBy + setting the `tag_handling` parameter to `xml`, the API will process XML input + by extracting text out of the structure,\nsplitting it into individual sentences, + translating them, and placing them back into the XML structure.\n\nFor the translation + of HTML content please see [Handling HTML (Beta)](https://www.deepl.com/docs-api/html) + \n\nWe will look at the XML handling engine in the following cases:\n\n- Sentences + with markup\n- Structured content\n- Restricting splitting\n- Disabling automatic + outline detection\n- Splitting on newlines\n- Ignored text" +- name: HandlingHTML + description: |- + By default, the translation engine does not take HTML tags into account. + By setting the `tag_handling` parameter to `html`, the API will process HTML input by extracting text + out of the structure, splitting it into individual sentences, translating them, and placing them back + into the HTML structure. + This functionality is in beta. If you encounter issues, please let us know at support@DeepL.com. + + For the translation of generic XML content please see [Handling XML](https://www.deepl.com/docs-api/xml) +- name: TranslatingDocuments + description: |- + The document translation API allows you to translate whole documents. + Translating a document usually involves three types of HTTP requests: + - [upload](https://www.deepl.com/docs-api/documents/translate-document) the document to be translated, + - periodically [check the status](https://www.deepl.com/docs-api/documents/get-document-status) of the document translation, + - once the status call reports `done`, [download](https://www.deepl.com/docs-api/documents/download-document) the translated document. + + Please note that with every submitted document of type .pptx, .docx, or .pdf, + you are billed a minimum of 50,000 characters with the DeepL API plan, + no matter how many characters are included in the document. +- name: ManagingGlossaries + description: |- + The *glossary* functions allow you to create, inspect, and delete glossaries. + Glossaries created with the glossary function can be used in translate requests by specifying the + `glossary_id` parameter. + If you encounter issues, please let us know at support@DeepL.com. + + Currently, glossaries for the following language combinations are supported: + + - EN (English) → DE (German) + - DE (German) → EN (English) + - EN (English) → FR (French) + - FR (French) → EN (English) + - EN (English) → ES (Spanish) + - ES (Spanish) → EN (English) + - EN (English) → JA (Japanese) + - JA (Japanese) → EN (English) + - DE (German) → FR (French) + - FR (French) → DE (German) + + The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text, + as well as the name of the glossary, is limited to 1024 UTF-8 bytes. + A total of 1000 glossaries are allowed per account. + + + Glossaries created via the DeepL API are distinct from glossaries created via the DeepL website and DeepL apps. + This means API glossaries cannot be used on the website and vice versa. +- name: MetaInformation + description: Information about API usage and value ranges +paths: + /translate: + post: + tags: + - TranslatingText + summary: Request Translation + operationId: translateText + description: The translate function. + requestBody: + required: true + content: + application/x-www-form-urlencoded: + examples: + Basic: + summary: Basic Example + value: + text: + - Hello, world + target_lang: DE + Glossary: + summary: Using a Glossary + value: + text: + - Hello, world + target_lang: DE + source_lang: EN + glossary_id: '[yourGlossaryId]' + MultipleSentences: + summary: Multiple Sentences + value: + text: + - The table is green. The chair is black. + target_lang: DE + LargeVolumes: + summary: Large Volumes of Text + value: + text: + - This is the first sentence. + - This is the second sentence. + - This is the third sentence. + target_lang: DE + schema: + type: object + required: + - text + - target_lang + properties: + text: + description: Text to be translated. Only UTF-8-encoded plain text + is supported. The parameter may be specified multiple times and + translations are returned in the same order as they are requested. + Each of the parameter values may contain multiple sentences. Up + to 50 texts can be sent for translation in one request. + type: array + maxItems: 50 + items: + type: string + source_lang: + $ref: '#/components/schemas/SourceLanguage' + target_lang: + $ref: '#/components/schemas/TargetLanguage' + split_sentences: + description: |- + Sets whether the translation engine should first split the input into sentences. This is enabled by default. Possible values are: + * `0` - no splitting at all, whole input is treated as one sentence + * `1` - splits on punctuation and on newlines + * `nonewlines` - splits on punctuation only, ignoring newlines + + For applications that send one sentence per text parameter, it is advisable to set `split_sentences` to `0`, in order to prevent the engine from splitting the sentence unintentionally. + + + Please note that newlines will split sentences. You should therefore clean files to avoid breaking sentences or set the parameter `split_sentences` to `nonewlines`. In the example below, the two parts of the sentence have been translated separately and this has caused an error: The word "the" has been incorrectly translated as "die" (the feminine definite article in German), though the German word for "sentence", "Satz", is masculine (der Satz). + * Example request: + ``` +
This is the first + sentence.
+ ``` + * Example response: + ``` +
Dies ist die erste + Satz.
+ ``` + type: string + enum: + - '0' + - '1' + - nonewlines + default: '1' + preserve_formatting: + description: |- + Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. Possible values are: + * `0` + * `1` + + The formatting aspects affected by this setting include: + * Punctuation at the beginning and end of the sentence + * Upper/lower case at the beginning of the sentence + type: string + enum: + - '0' + - '1' + default: '0' + formality: + $ref: '#/components/schemas/Formality' + glossary_id: + description: Specify the glossary to use for the translation. **Important:** + This requires the `source_lang` parameter to be set and the language + pair of the glossary has to match the language pair of the request. + type: string + tag_handling: + description: |- + Sets which kind of tags should be handled. Options currently available: + * `xml`: Enable XML tag handling; see [Handling XML](https://www.deepl.com/docs-api/xml). + * `html`: Enable HTML tag handling; see [Handling HTML (Beta)](https://www.deepl.com/docs-api/html). + type: string + enum: + - xml + - html + non_splitting_tags: + description: |- + Comma-separated list of XML tags which never split sentences. + + + For some XML files, finding tags with textual content and splitting sentences using those tags won't yield the best results. The following example shows the engine splitting sentences on `par` tags and proceeding to translate the parts separately, resulting in an incorrect translation: + * Example request: + ``` + The firm said it had been conducting an internal investigation. + ``` + * Example response: + ``` + Die Firma sagte, es sei eine gute Idee gewesen. Durchführung einer internen Untersuchung. + ``` + + + As this can lead to bad translations, this type of structure should either be avoided, or the `non_splitting_tags` parameter should be set. The following example shows the same call, with the parameter set to `par`: + * Example request: + ``` + The firm said it had been conducting an internal investigation. + ``` + * Example response: + ``` + Die Firma sagte, dass sie eine interne Untersuchung durchgeführt habe. + ``` + + + This time, the sentence is translated as a whole. The XML tags are now considered markup and copied into the translated sentence. As the translation of the words "had been" has moved to another position in the German sentence, the two par tags are duplicated (which is expected here). + type: string + outline_detection: + description: |- + The automatic detection of the XML structure won't yield best results in all XML files. You can disable this automatic mechanism altogether by setting the `outline_detection` parameter to `0` and selecting the tags that should be considered structure tags. This will split sentences using the `splitting_tags` parameter. + + + In the example below, we achieve the same results as the automatic engine by disabling automatic detection with `outline_detection=0` and setting the parameters manually to `tag_handling=xml`, `split_sentences=nonewlines`, and `splitting_tags=par,title`. + * Example request: + + + + + A document's title + + + This is the first sentence. Followed by a second one. + This is the third sentence. + + + + * Example response: + + + + + Der Titel eines Dokuments + + + Das ist der erste Satz. Gefolgt von einem zweiten. + Dies ist der dritte Satz. + + + + + While this approach is slightly more complicated, it allows for greater control over the structure of the translation output. + type: string + enum: + - '0' + splitting_tags: + description: |- + Comma-separated list of XML tags which always cause splits. + + + See the example in the `outline_detection` parameter's description. + type: string + ignore_tags: + description: |- + Comma-separated list of XML tags that indicate text not to be translated. + + + Use this paramter to ensure that elements in the original text are not altered in the translation (e.g., trademarks, product names) and insert tags into your original text. In the following example, the `ignore_tags` parameter is set to `keep`: + * Example request: + ``` + Please open the page Settings to configure your system. + ``` + * Example response: + ``` + Bitte öffnen Sie die Seite Settings um Ihr System zu konfigurieren. + ``` + type: string + encoding: + text: + style: form + explode: true + responses: + 200: + description: The translate function returns a JSON representation of the + translations in the order the text parameters have been specified. + content: + application/json: + schema: + type: object + properties: + translations: + type: array + minItems: 1 + items: + type: object + properties: + detected_source_language: + allOf: + - $ref: '#/components/schemas/SourceLanguage' + - description: The language detected in the source text. + It reflects the value of the `source_lang` parameter, + when specified. + text: + description: The translated text. + type: string + examples: + Basic: + value: + translations: + - detected_source_language: EN + text: Hallo, Welt! + Glossary: + value: + translations: + - text: Hallo, Welt! + MultipleSentences: + value: + translations: + - detected_source_language: EN + text: Der Tisch ist grün. Der Stuhl ist schwarz. + LargeVolumes: + value: + translations: + - detected_source_language: EN + text: Das ist der erste Satz. + - detected_source_language: EN + text: Das ist der zweite Satz. + - detected_source_language: EN + text: Dies ist der dritte Satz. + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 414: + $ref: '#/components/responses/URITooLong' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /document: + post: + tags: + - TranslatingDocuments + summary: Upload and Translate a Document + operationId: translateDocument + description: |- + This call uploads a document and queues it for translation. + The call returns once the upload is complete, returning a document ID and key which can be used to + [query the translation status](https://www.deepl.com/docs-api/documents/get-document-status) + and to [download the translated document](https://www.deepl.com/docs-api/documents/download-document) once translation is complete. + + + + Because the request includes a file upload, it must be an HTTP POST request with content type `multipart/form-data`. + + + Please be aware that the uploaded document is automatically removed from the server once the translated document has been downloaded. + You have to upload the document again in order to restart the translation. + + + The maximum upload limit for any document is 10 MiB and 1.000.000 characters. + + + You may specify the glossary to use for the document translation using the `glossary_id` parameter. + **Important:** This requires the `source_lang` parameter to be set and the language pair of the glossary has to match the language pair of the request. + requestBody: + required: true + content: + multipart/form-data: + example: + target_lang: DE + schema: + type: object + required: + - target_lang + - file + properties: + source_lang: + $ref: '#/components/schemas/SourceLanguage' + target_lang: + $ref: '#/components/schemas/TargetLanguage' + file: + type: string + format: binary + description: |- + The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported: + * `docx` - Microsoft Word Document + * `pptx` - Microsoft PowerPoint Document + * `pdf` - Portable Document Format + * `htm / html` - HTML Document + * `txt` - Plain Text Document + + Please note that in order to translate PDF documents you need to give one-time consent to using the Adobe API via the account interface. + filename: + type: string + description: The name of the uploaded file. Can be used as an alternative + to including the file name in the file part's content disposition. + formality: + $ref: '#/components/schemas/Formality' + glossary_id: + $ref: '#/components/schemas/GlossaryId' + responses: + 200: + description: The document function returns a JSON object containing the + ID and encryption key assigned to the uploaded document. Once received + by the server, uploaded documents are immediately encrypted using a uniquely + generated encryption key. This key is not persistently stored on the server. + Therefore, it must be stored by the client and sent back to the server + with every subsequent request that refers to this particular document. + content: + application/json: + schema: + type: object + properties: + document_id: + description: A unique ID assigned to the uploaded document and + the translation process. Must be used when referring to this + particular document in subsequent API requests. + type: string + document_key: + description: A unique key that is used to encrypt the uploaded + document as well as the resulting translation on the server + side. Must be provided with every subsequent API request regarding + this particular document. + type: string + example: + document_id: 04DE5AD98A02647D83285A36021911C6 + document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /document/{document_id}: + post: + tags: + - TranslatingDocuments + summary: Check Document Status + description: |- + Retrieve the current status of a document translation process. + If the translation is still in progress, the estimated time remaining is also included in the response. + operationId: getDocumentStatus + parameters: + - $ref: '#/components/parameters/DocumentID' + requestBody: + $ref: '#/components/requestBodies/DocumentKey' + responses: + 200: + description: The document status request returns a JSON object containing + the document ID that was used in the request as well as string indicating + the current status of the translation process. While the translation is + running, the estimated number of seconds remaining until the process is + done is also included in the response. + content: + application/json: + schema: + type: object + required: + - document_id + - status + properties: + document_id: + description: A unique ID assigned to the uploaded document and + the requested translation process. The same ID that was used + when requesting the translation status. + type: string + status: + description: |- + A short description of the state the document translation process is currently in. Possible values are: + * `queued` - the translation job is waiting in line to be processed + * `translating` - the translation is currently ongoing + * `done` - the translation is done and the translated document is ready for download + * `error` - an irrecoverable error occurred while translating the document + type: string + enum: + - queued + - translating + - done + - error + seconds_remaining: + description: |- + Estimated number of seconds until the translation is done. + This parameter is only included while `status` is `"translating"`. + type: integer + billed_characters: + description: The number of characters billed to your account. + type: integer + error_message: + description: |- + A short description of the error, if available. + Note that the content is subject to change. + This parameter may be included if an error occurred during translation. + type: string + examples: + translating: + summary: Translating + value: + document_id: 04DE5AD98A02647D83285A36021911C6 + status: translating + seconds_remaining: 20 + done: + summary: Done + value: + document_id: 04DE5AD98A02647D83285A36021911C6 + status: done + billed_characters: 1337 + queued: + summary: Queued + value: + document_id: 04DE5AD98A02647D83285A36021911C6 + status: queued + error: + summary: Error + value: + document_id: 04DE5AD98A02647D83285A36021911C6 + status: error + message: Source and target language are equal. + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /document/{document_id}/result: + post: + tags: + - TranslatingDocuments + summary: Download Translated Document + operationId: downloadDocument + description: |- + Once the status of the document translation process is `done`, the result can be downloaded. + + + For privacy reasons the translated document is automatically removed from the server once it was downloaded and cannot be downloaded again. + parameters: + - $ref: '#/components/parameters/DocumentID' + requestBody: + $ref: '#/components/requestBodies/DocumentKey' + responses: + 200: + description: The document is provided as a download. There is no other data + included in the response besides the document data. The content type used + in the response corresponds to the document type. + content: + application/octet-stream: + schema: + type: string + format: binary + examples: + OK: + summary: OK + description: binary document data + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound404DocTransDownload' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable503DocTransDownload' + 504: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /glossary-language-pairs: + get: + tags: + - ManagingGlossaries + summary: List Language Pairs Supported by Glossaries + description: Retrieve the list of language pairs supported by the glossary feature. + operationId: listGlossaryLanguages + responses: + 200: + description: A JSON object containing the language pairs in its `supported_languages` + property. + content: + application/json: + schema: + type: object + properties: + supported_languages: + type: array + description: The list of supported languages + items: + type: object + required: + - source_lang + - target_lang + properties: + source_lang: + description: The language in which the source texts in the + glossary are specified. + type: string + target_lang: + description: The language in which the target texts in the + glossary are specified. + type: string + example: + supported_languages: + - source_lang: de + target_lang: en + - source_lang: en + target_lang: de + 400: + $ref: '#/components/responses/BadRequestGlossaries' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenGlossaries' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /glossaries: + post: + tags: + - ManagingGlossaries + summary: Create a Glossary + operationId: createGlossary + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - name + - source_lang + - target_lang + - entries + - entries_format + properties: + name: + description: Name to be associated with the glossary. + type: string + example: My Glossary + source_lang: + $ref: '#/components/schemas/GlossarySourceLanguage' + target_lang: + $ref: '#/components/schemas/GlossaryTargetLanguage' + entries: + description: The entries of the glossary. The entries have to be + specified in the format provided by the `entries_format` parameter. + type: string + example: "Hello!\tGuten Tag!" + entries_format: + description: |- + The format in which the glossary entries are provided. Formats currently available: + * `tsv` - Tab-separated values. Entries have to be specified as tab-separated values with the "source entry" being the text in the source language of the glossary and the "target entry" being the text in the target language of the glossary. + + In addition the following restrictions apply: + * Duplicate source entries are not allowed. + * Source-target entry pairs are separated by a newline. + * Source entries and target entries are separated by a tab. + * Source entries and target entries are not empty. + * Source and target entries must not contain any [C0 or C1 control characters](https://en.wikipedia.org/wiki/C0_and_C1_control_codes) (including e.g. `"\t"` or `"\n"`) or any [Unicode newline](https://en.wikipedia.org/wiki/Newline#Unicode). + * Source and target entries must not contain any leading or trailing Unicode whitespace. + + Valid glossary entries in the TSV format could be created in a programming language with backslash escape sequences (e.g. Python, JavaScript, etc.) like this: + + `"sourceEntry1\ttargetEntry1\nsourceEntry2\targetEntry2"` + type: string + enum: + - tsv + example: tsv + responses: + 201: + description: The function for creating a glossary returns a JSON object + containing the ID of the newly created glossary and a boolean flag that + indicates if the created glossary can already be used in translate requests. + content: + application/json: + schema: + $ref: '#/components/schemas/Glossary' + 400: + $ref: '#/components/responses/BadRequestGlossaries' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenGlossaries' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + get: + tags: + - ManagingGlossaries + summary: List all Glossaries + operationId: listGlossaries + description: List all glossaries and their meta-information, but not the glossary + entries. + responses: + 200: + description: JSON object containing a the glossaries. + content: + application/json: + schema: + type: object + properties: + glossaries: + type: array + items: + $ref: '#/components/schemas/Glossary' + example: + glossaries: + - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + name: My Glossary + ready: true + source_lang: EN + target_lang: DE + creation_time: '2021-08-03T14:16:18.329Z' + entry_count: 1 + 400: + $ref: '#/components/responses/BadRequestGlossaries' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenGlossaries' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /glossaries/{glossary_id}: + get: + tags: + - ManagingGlossaries + summary: Retrieve Glossary Details + description: Retrieve meta information for a single glossary, omitting the glossary + entries. + operationId: getGlossary + parameters: + - $ref: '#/components/parameters/GlossaryID' + responses: + 200: + description: JSON object containing the glossary meta-information. + content: + application/json: + schema: + $ref: '#/components/schemas/Glossary' + example: + id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + name: My Glossary + ready: true + source_lang: EN + target_lang: DE + creation_time: '2021-08-03T14:16:18.329Z' + entry_count: 1 + 400: + $ref: '#/components/responses/BadRequestGlossaries' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenGlossaries' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + delete: + tags: + - ManagingGlossaries + summary: Delete a Glossary + description: Deletes the specified glossary. + operationId: deleteGlossary + parameters: + - $ref: '#/components/parameters/GlossaryID' + responses: + 204: + description: Returns no content upon success. + 400: + $ref: '#/components/responses/BadRequestGlossaries' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenGlossaries' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /glossaries/{glossary_id}/entries: + get: + tags: + - ManagingGlossaries + summary: Retrieve Glossary Entries + operationId: getGlossaryEntries + description: List the entries of a single glossary in the format specified by + the `Accept` header. + parameters: + - $ref: '#/components/parameters/GlossaryID' + - name: Accept + in: header + schema: + type: string + enum: + - text/tab-separated-values + default: text/tab-separated-values + description: The requested format of the returned glossary entries. Currently, + supports only `text/tab-separated-values`. + example: text/tab-separated-values + responses: + 200: + description: The entries in the requested format. + content: + text/tab-separated-values: + example: "Hello!\tGuten Tag!" + 400: + $ref: '#/components/responses/BadRequestGlossaries' + 401: + $ref: '#/components/responses/Unauthorized' + 403: + $ref: '#/components/responses/ForbiddenGlossaries' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + $ref: '#/components/responses/UnsupportedMediaTypeGlossaries' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 503: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /usage: + get: + tags: + - MetaInformation + summary: Check Usage and Limits + description: |- + Retrieve usage information within the current billing period together with the corresponding account limits. Usage is returned for: + - translated characters + - translated documents + - translated documents, team totals (for team accounts only) + + Character usage includes both text and document translations, and is measured by the source text length in Unicode code points, + so for example "A", "Δ", "あ", and "深" are each counted as a single character. + + Document usage only includes document translations, and is measured in individual documents. + + Depending on the user account type, some usage types will be omitted. + Character usage is only included for developer accounts. + Document usage is only included for non-developer accounts, and team-combined document usage is only included for non-developer team accounts. + operationId: getUsage + responses: + 200: + description: The account's usage and limits. + content: + application/json: + schema: + type: object + properties: + character_count: + description: Characters translated so far in the current billing + period. + type: integer + format: int64 + character_limit: + description: Current maximum number of characters that can be + translated per billing period. + type: integer + format: int64 + document_limit: + description: Documents translated so far in the current billing + period. + type: integer + format: int64 + document_count: + description: Current maximum number of documents that can be translated + per billing period. + type: integer + format: int64 + team_document_limit: + description: Documents translated by all users in the team so + far in the current billing period. + type: integer + format: int64 + team_document_count: + description: Current maximum number of documents that can be translated + by the team per billing period. + type: integer + format: int64 + example: + character_count: 180118 + character_limit: 1250000 + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] + /languages: + get: + tags: + - MetaInformation + summary: Retrieve Supported Languages + description: Retrieve the list of languages that are currently supported for + translation, either as source or target language, respectively. + operationId: getLanguages + parameters: + - name: type + in: query + description: |- + Sets whether source or target languages should be listed. Possible options are: + * `source` (default): For languages that can be used in the `source_lang` parameter of [translate](https://www.deepl.com/docs-api/translating-text/translate-text) requests. + * `target`: For languages that can be used in the `target_lang` parameter of [translate](https://www.deepl.com/docs-api/translating-text/translate-text) requests. + schema: + type: string + enum: + - source + - target + default: source + example: target + responses: + 200: + description: JSON array where each item represents a supported language. + content: + application/json: + schema: + type: array + items: + type: object + required: + - language + - name + properties: + language: + description: The language code of the given language. + type: string + name: + description: Name of the language in English. + type: string + supports_formality: + description: Denotes formality support in case of a target language + listing. + type: boolean + example: + - language: BG + name: Bulgarian + supports_formality: false + - language: CS + name: Czech + supports_formality: false + - language: DA + name: Danish + supports_formality: false + - language: DE + name: German + supports_formality: true + - language: EL + name: Greek + supports_formality: false + - language: EN-GB + name: English (British) + supports_formality: false + - language: EN-US + name: English (American) + supports_formality: false + - language: ES + name: Spanish + supports_formality: true + - language: ET + name: Estonian + supports_formality: false + - language: FI + name: Finnish + supports_formality: false + - language: FR + name: French + supports_formality: true + - language: HU + name: Hungarian + supports_formality: false + - language: ID + name: Indonesian + supports_formality: false + - language: IT + name: Italian + supports_formality: true + - language: JA + name: Japanese + supports_formality: false + - language: LT + name: Lithuanian + supports_formality: false + - language: LV + name: Latvian + supports_formality: false + - language: NL + name: Dutch + supports_formality: true + - language: PL + name: Polish + supports_formality: true + - language: PT-BR + name: Portuguese (Brazilian) + supports_formality: true + - language: PT-PT + name: Portuguese (European) + supports_formality: true + - language: RO + name: Romanian + supports_formality: false + - language: RU + name: Russian + supports_formality: true + - language: SK + name: Slovak + supports_formality: false + - language: SL + name: Slovenian + supports_formality: false + - language: SV + name: Swedish + supports_formality: false + - language: TR + name: Turkish + supports_formality: false + - language: ZH + name: Chinese + supports_formality: false + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 404: + $ref: '#/components/responses/NotFound' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + 529: + $ref: '#/components/responses/TooManyRequests' + security: + - auth_header: [] +components: + parameters: + DocumentID: + name: document_id + description: The document ID that was sent to the client when the document was + uploaded to the API. + in: path + required: true + schema: + type: string + example: 04DE5AD98A02647D83285A36021911C6 + GlossaryID: + name: glossary_id + description: A unique ID assigned to the glossary. + in: path + required: true + schema: + type: string + SourceLanguage: + name: source_lang + in: query + schema: + $ref: '#/components/schemas/SourceLanguage' + TargetLanguage: + name: target_lang + in: query + required: true + schema: + $ref: '#/components/schemas/TargetLanguage' + responses: + BadRequest: + description: Bad request. Please check error message and your parameters. + BadRequestGlossaries: + description: Bad request. Please check error message and your parameters. + content: + application/json: + schema: + type: object + properties: + message: + description: Generic description of the error. + type: string + detail: + description: More specific description of the error. + type: string + example: + message: Invalid glossary entries provided + detail: Key with the index 1 (starting at position 13) duplicates key + with the index 0 (starting at position 0) + Unauthorized: + description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via + the `Authorization` header. + Forbidden: + description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via + the `Authorization` header. + ForbiddenGlossaries: + description: Forbidden. The access to the requested resource is denied, because + of insufficient access rights. + NotFound: + description: The requested resource could not be found. + NotFound404DocTransDownload: + description: Trying to download a document using a non-existing document ID + or the wrong document key will result in a 404 error. As stated above, documents + can only be downloaded once before they are deleted from the server and their + document ID is invalidated. + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentTranslationError' + examples: + NotFound: + summary: Not Found + value: + message: Document not found + PayloadTooLarge: + description: The request size exceeds the limit. + URITooLong: + description: The request URL is too long. You can avoid this error by using + a POST request instead of a GET request, and sending the parameters in the + HTTP body. + UnsupportedMediaTypeGlossaries: + description: The requested entries format specified in the `Accept` header is + not supported. + TooManyRequests: + description: Too many requests. Please wait and resend your request. + QuotaExceeded: + description: Quota exceeded. The character limit has been reached. + InternalServerError: + description: Internal error. + ServiceUnavailable: + description: Resource currently unavailable. Try again later. + ServiceUnavailable503DocTransDownload: + description: |- + A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download. + Please make sure to check that the document status is 'done' before trying to send a download request. + content: + application/json: + schema: + $ref: '#/components/schemas/DocumentTranslationError' + examples: + AlreadyDownloaded: + summary: Already downloaded + value: + message: Document already downloaded + securitySchemes: + auth_header: + type: apiKey + description: Authentication with `Authorization` header and `DeepL-Auth-Key` + authentication scheme + name: Authorization + in: header + requestBodies: + DocumentKey: + required: true + content: + application/x-www-form-urlencoded: + schema: + type: object + required: + - document_key + properties: + document_key: + description: The document encryption key that was sent to the client + when the document was uploaded to the API. + type: string + example: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A + schemas: + DocumentTranslationError: + type: object + properties: + message: + type: string + description: detailed error message + Formality: + description: |- + Sets whether the translated text should lean towards formal or informal language. + This feature currently only works for target languages + `DE` (German), + `FR` (French), + `IT` (Italian), + `ES` (Spanish), + `NL` (Dutch), + `PL` (Polish), + `PT-PT`, + `PT-BR` (Portuguese) + and `RU` (Russian). + Possible options are: + * `default` + * `more` - for a more formal language + * `less` - for a more informal language + type: string + enum: + - default + - more + - less + default: default + GlossaryId: + type: string + description: A unique ID assigned to a glossary. + example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + Glossary: + type: object + properties: + glossary_id: + $ref: '#/components/schemas/GlossaryId' + name: + description: Name associated with the glossary. + type: string + ready: + description: |- + Indicates if the newly created glossary can already be used in `translate` requests. + If the created glossary is not yet ready, you have to wait and check the `ready` status + of the glossary before using it in a `translate` request. + type: boolean + source_lang: + $ref: '#/components/schemas/GlossarySourceLanguage' + target_lang: + $ref: '#/components/schemas/GlossaryTargetLanguage' + creation_time: + description: 'The creation time of the glossary in the ISO 8601-1:2019 format + (e.g.: `2021-08-03T14:16:18.329Z`).' + type: string + format: date-time + entry_count: + description: The number of entries in the glossary. + type: integer + example: + glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 + ready: true + name: My Glossary + source_lang: en + target_lang: de + creation_time: '2021-08-03T14:16:18.329Z' + entry_count: 1 + GlossarySourceLanguage: + type: string + description: The language in which the source texts in the glossary are specified. + enum: + - de + - en + - es + - fr + - ja + example: de + GlossaryTargetLanguage: + type: string + description: The language in which the target texts in the glossary are specified. + enum: + - de + - en + - es + - fr + - ja + example: en + SourceLanguage: + type: string + description: |- + Language of the text to be translated. Options currently available: + * `BG` - Bulgarian + * `CS` - Czech + * `DA` - Danish + * `DE` - German + * `EL` - Greek + * `EN` - English + * `ES` - Spanish + * `ET` - Estonian + * `FI` - Finnish + * `FR` - French + * `HU` - Hungarian + * `ID` - Indonesian + * `IT` - Italian + * `JA` - Japanese + * `LT` - Lithuanian + * `LV` - Latvian + * `NL` - Dutch + * `PL` - Polish + * `PT` - Portuguese (all Portuguese varieties mixed) + * `RO` - Romanian + * `RU` - Russian + * `SK` - Slovak + * `SL` - Slovenian + * `SV` - Swedish + * `TR` - Turkish + * `ZH` - Chinese + + If this parameter is omitted, the API will attempt to detect the language of the text and translate it. + enum: + - BG + - CS + - DA + - DE + - EL + - EN + - ES + - ET + - FI + - FR + - HU + - ID + - IT + - JA + - LT + - LV + - NL + - PL + - PT + - RO + - RU + - SK + - SL + - SV + - TR + - ZH + TargetLanguage: + type: string + description: |- + The language into which the text should be translated. Options currently available: + * `BG` - Bulgarian + * `CS` - Czech + * `DA` - Danish + * `DE` - German + * `EL` - Greek + * `EN` - English (unspecified variant for backward compatibility; please select `EN-GB` or `EN-US` instead) + * `EN-GB` - English (British) + * `EN-US` - English (American) + * `ES` - Spanish + * `ET` - Estonian + * `FI` - Finnish + * `FR` - French + * `HU` - Hungarian + * `ID` - Indonesian + * `IT` - Italian + * `JA` - Japanese + * `LT` - Lithuanian + * `LV` - Latvian + * `NL` - Dutch + * `PL` - Polish + * `PT` - Portuguese (unspecified variant for backward compatibility; please select `PT-BR` or `PT-PT` instead) + * `PT-BR` - Portuguese (Brazilian) + * `PT-PT` - Portuguese (all Portuguese varieties excluding Brazilian Portuguese) + * `RO` - Romanian + * `RU` - Russian + * `SK` - Slovak + * `SL` - Slovenian + * `SV` - Swedish + * `TR` - Turkish + * `ZH` - Chinese + enum: + - BG + - CS + - DA + - DE + - EL + - EN-GB + - EN-US + - ES + - ET + - FI + - FR + - HU + - ID + - IT + - JA + - LT + - LV + - NL + - PL + - PT-BR + - PT-PT + - RO + - RU + - SK + - SL + - SV + - TR + - ZH