diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml deleted file mode 100644 index 306618b..0000000 --- a/api-reference/openapi.yaml +++ /dev/null @@ -1,2557 +0,0 @@ -openapi: 3.0.3 -info: - title: DeepL API Documentation - description: |- - The DeepL API provides programmatic access to DeepL’s language AI technology. - - Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions. - termsOfService: https://www.deepl.com/pro-license - contact: - name: DeepL - Contact us - url: https://www.deepl.com/contact-us - version: 3.2.0 -externalDocs: - description: DeepL Pro - Plans and pricing - url: https://www.deepl.com/pro#developer -servers: -- url: https://api.deepl.com - description: DeepL API Pro -- url: https://api-free.deepl.com - description: DeepL API Free -tags: -- name: TranslateText - description: |- - The text-translation API currently consists of a single endpoint, `translate`, which is described below. -- name: TranslateDocuments - description: |- - The document translation API allows you to translate whole documents and supports the following file types and extensions: - * `docx` - Microsoft Word Document - * `pptx` - Microsoft PowerPoint Document - * `xlsx` - Microsoft Excel Document - * `pdf` - Portable Document Format - * `htm / html` - HTML Document - * `txt` - Plain Text Document - * `xlf / xliff` - XLIFF Document, version 2.1 - * `srt` - SRT Document -- name: RephraseText - description: |- - The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone. -- name: ManageMultilingualGlossaries - description: |- - The *glossary* functions allow you to create, inspect, edit and delete glossaries. - Glossaries created with the glossary function can be used in translate requests by specifying the - `glossary_id` parameter. A glossary contains (several) dictionaries. - A dictionary is a mapping of source phrases to target phrases for a single language pair. - If you encounter issues, please let us know at support@DeepL.com. - - Currently you can create glossaries with any of the languages DeepL supports. - - 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. - - When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant - (e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`). - Dictionaries with target language `EN` can be used in translations with either English variant. - Similarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants. - (When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.) - - Glossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps. - Please only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website. -- name: ManageGlossaries - description: |- - Please note that this is the spec for the (old) v2 glossary endpoint. - We recommend users switch to the newer v3 glossary endpoints, which support editability and multilinguality. - - 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 you can create glossaries with any of the languages DeepL supports. -- name: MetaInformation - description: Information about API usage and value ranges -x-hideTryItPanel: true -x-codeSamples: false -paths: - /v2/admin/developer-keys: - post: - tags: - - AdminApi - summary: Create a developer key as an admin - operationId: adminCreateDeveloperKey - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - label: - $ref: '#/components/schemas/ApiKeyLabel' - responses: - 200: - description: The create function returns a JSON representation of the created API key. - content: - application/json: - schema: - $ref: '#/components/schemas/ApiKey' - 400: - $ref: '#/components/responses/BadRequest' - 403: - $ref: '#/components/responses/Forbidden' - 404: - $ref: '#/components/responses/NotFound' - 500: - $ref: '#/components/responses/InternalServerError' - security: - - auth_header: [ ] - get: - tags: - - AdminApi - summary: Get all developer keys as an admin - operationId: adminGetDeveloperKeys - responses: - 200: - description: The get function returns a JSON representation of all developer API keys in the organization. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ApiKey' - 400: - $ref: '#/components/responses/BadRequest' - 403: - $ref: '#/components/responses/Forbidden' - 404: - $ref: '#/components/responses/NotFound' - 500: - $ref: '#/components/responses/InternalServerError' - security: - - auth_header: [ ] - /v2/admin/developer-keys/deactivate: - put: - tags: - - AdminApi - summary: Deactivate a developer key as an admin - operationId: adminDeactivateDeveloperKey - requestBody: - required: true - content: - application/json: - schema: - type: object - required: - - key_id - properties: - key_id: - $ref: '#/components/schemas/ApiKeyId' - responses: - 200: - description: The deactivate function returns a JSON representation of the deactivated API key. - content: - application/json: - schema: - $ref: '#/components/schemas/ApiKey' - 400: - $ref: '#/components/responses/BadRequest' - 403: - $ref: '#/components/responses/Forbidden' - 404: - $ref: '#/components/responses/NotFound' - 500: - $ref: '#/components/responses/InternalServerError' - security: - - auth_header: [ ] - /v2/admin/developer-keys/label: - put: - tags: - - AdminApi - summary: Rename a developer key as an admin - operationId: adminRenameDeveloperKey - requestBody: - required: true - content: - application/json: - schema: - type: object - required: - - key_id - - label - properties: - key_id: - $ref: '#/components/schemas/ApiKeyId' - label: - type: string - description: API key label. - example: developer key prod - responses: - 200: - description: The set label function returns a JSON representation of the renamed API key. - content: - application/json: - schema: - $ref: '#/components/schemas/ApiKey' - 400: - $ref: '#/components/responses/BadRequest' - 403: - $ref: '#/components/responses/Forbidden' - 404: - $ref: '#/components/responses/NotFound' - 500: - $ref: '#/components/responses/InternalServerError' - security: - - auth_header: [ ] - /v2/admin/developer-keys/limits: - put: - tags: - - AdminApi - summary: Set developer key usage limits as an admin - operationId: adminSetDeveloperKeyUsageLimits - requestBody: - required: true - content: - application/json: - schema: - type: object - required: - - key_id - properties: - key_id: - $ref: '#/components/schemas/ApiKeyId' - characters: - $ref: '#/components/schemas/ApiKeyUsageCharacters' - responses: - 200: - description: The set usage limits function returns a JSON representation of the modified API key. - content: - application/json: - schema: - $ref: '#/components/schemas/ApiKey' - 400: - $ref: '#/components/responses/BadRequest' - 403: - $ref: '#/components/responses/Forbidden' - 404: - $ref: '#/components/responses/NotFound' - 500: - $ref: '#/components/responses/InternalServerError' - security: - - auth_header: [ ] - /v2/translate: - post: - tags: - - TranslateText - summary: Request Translation - operationId: translateText - requestBody: - required: true - content: - application/json: - 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 - many times in a single request, within the request size limit (128KiB). Translations are returned - in the same order as they are requested. - type: array - items: - type: string - example: Hello, World! - source_lang: - $ref: '#/components/schemas/SourceLanguage' - target_lang: - $ref: '#/components/schemas/TargetLanguageText' - context: - $ref: '#/components/schemas/Context' - show_billed_characters: - $ref: '#/components/schemas/ShowBilledCharacters' - split_sentences: - $ref: '#/components/schemas/SplitSentencesOption' - preserve_formatting: - $ref: '#/components/schemas/PreserveFormattingOption' - formality: - $ref: '#/components/schemas/Formality' - model_type: - $ref: '#/components/schemas/ModelType' - glossary_id: - description: |- - Specify the glossary to use for the translation. **Important:** This requires the `source_lang` - parameter to be set. The language pair of the glossary has to match the language pair of the - request. - type: string - example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - tag_handling: - $ref: '#/components/schemas/TagHandlingOption' - outline_detection: - $ref: '#/components/schemas/OutlineDetectionOption' - non_splitting_tags: - description: Comma-separated list of XML tags which never split sentences. - type: array - items: - type: string - example: non_splitting_tag - splitting_tags: - description: Comma-separated list of XML tags which always cause splits. - type: array - items: - type: string - example: splitting_tag - ignore_tags: - description: Comma-separated list of XML tags that indicate text not to be translated. - type: array - items: - type: string - example: ignore_tag - application/x-www-form-urlencoded: - 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 many times in a single request, within the request size limit (128KiB). Translations are - returned in the same order as they are requested. - type: array - items: - type: string - example: Hello, World! - source_lang: - $ref: '#/components/schemas/SourceLanguage' - target_lang: - $ref: '#/components/schemas/TargetLanguageText' - context: - $ref: '#/components/schemas/Context' - show_billed_characters: - $ref: '#/components/schemas/ShowBilledCharacters' - split_sentences: - $ref: '#/components/schemas/SplitSentencesOption' - preserve_formatting: - $ref: '#/components/schemas/PreserveFormattingOptionStr' - formality: - $ref: '#/components/schemas/Formality' - model_type: - $ref: '#/components/schemas/ModelType' - glossary_id: - description: |- - Specify the glossary to use for the translation. **Important:** This requires the `source_lang` - parameter to be set. The language pair of the glossary has to match the language pair of the - request. - type: string - example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - tag_handling: - $ref: '#/components/schemas/TagHandlingOption' - outline_detection: - $ref: '#/components/schemas/OutlineDetectionOptionStr' - non_splitting_tags: - description: Comma-separated list of XML tags which never split sentences. - type: array - items: - type: string - example: non_splitting_tag - splitting_tags: - description: Comma-separated list of XML tags which always cause splits. - type: array - items: - type: string - example: splitting_tag - ignore_tags: - description: Comma-separated list of XML tags that indicate text not to be translated. - type: array - items: - type: string - example: ignore_tag - 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: - description: The language detected in the source text. It - reflects the value of the `source_lang` parameter, when - specified. - type: string - example: EN - text: - description: The translated text. - type: string - example: Hallo, Welt! - billed_characters: - description: Number of characters counted by DeepL for billing purposes. - Only present if the show_billed_characters parameter is set to true. - type: integer - example: 42 - model_type_used: - description: Indicates the translation model used. Only present if model_type parameter - is included in the request. - type: string - example: quality_optimized - - 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: [ ] - /v2/document: - post: - tags: - - TranslateDocuments - summary: Upload and Translate a Document - operationId: translateDocument - requestBody: - required: true - content: - multipart/form-data: - examples: - Basic: - summary: Basic Document Translation - value: - target_lang: DE - file: '@document.docx' - Glossary: - summary: Using a Glossary - value: - source_lang: EN - target_lang: DE - file: '@document.docx' - glossary_id: '[yourGlossaryId]' - 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 - * `xlsx` - Microsoft Excel Document - * `pdf` - Portable Document Format - * `htm / html` - HTML Document - * `txt` - Plain Text Document - * `xlf / xliff` - XLIFF Document, version 2.1 - * `srt` - SRT Document - 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. - output_format: - type: string - description: | - File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file. - 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 - example: 04DE5AD98A02647D83285A36021911C6 - 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: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A - 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: [ ] - /v2/document/{document_id}: - post: - tags: - - TranslateDocuments - summary: Check Document Status - operationId: getDocumentStatus - parameters: - - $ref: '#/components/parameters/DocumentID' - requestBody: - required: true - content: - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/DocumentKey' - examples: - basic: - summary: Basic - value: - document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A - application/json: - schema: - $ref: '#/components/schemas/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 - example: 04DE5AD98A02647D83285A36021911C6 - 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 - example: done - 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. - The characters will only be billed after a successful download - request. - type: integer - example: 1337 - 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 - example: Only available if document status is error - 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: [ ] - /v2/document/{document_id}/result: - post: - tags: - - TranslateDocuments - summary: Download Translated Document - operationId: downloadDocument - parameters: - - $ref: '#/components/parameters/DocumentID' - requestBody: - required: true - content: - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/DocumentKey' - examples: - basic: - summary: Basic - value: - document_key: 0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A - application/json: - schema: - $ref: '#/components/schemas/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: [ ] - /v2/glossary-language-pairs: - get: - tags: - - ManageGlossaries - 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 - example: en - target_lang: - description: The language in which the target texts in the - glossary are specified. - type: string - example: de - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - /v3/glossaries: - post: - tags: - - ManageMultilingualGlossaries - summary: Create a Glossary - operationId: createMultilingualGlossary - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateMultilingualGlossaryParameters' - examples: - Basic: - value: - name: My Glossary - dictionaries: - - source_lang: en - target_lang: de - entries: "Hello\tGuten Tag" - entries_format: tsv - - source_lang: de - target_lang: en - entries: "Guten Tag\tHello" - entries_format: tsv - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/CreateMultilingualGlossaryParameters' - 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/MultilingualGlossary' - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - get: - tags: - - ManageMultilingualGlossaries - summary: List all Glossaries - operationId: listMultilingualGlossaries - 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/MultilingualGlossary' - example: - glossaries: - - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - name: My Glossary - dictionaries: - - source_lang: EN - target_lang: DE - entry_count: 1 - - source_lang: DE - target_lang: EN - entry_count: 2 - creation_time: '2021-08-03T14:16:18.329Z' - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - /v3/glossaries/{glossary_id}: - get: - tags: - - ManageMultilingualGlossaries - summary: Retrieve Glossary Details - description: Retrieve meta information for a single glossary, omitting the glossary - entries. - operationId: getMultilingualGlossary - parameters: - - $ref: '#/components/parameters/GlossaryID' - responses: - 200: - description: JSON object containing the glossary meta-information. - content: - application/json: - schema: - $ref: '#/components/schemas/MultilingualGlossary' - example: - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - name: My Glossary - dictionaries: - - source_lang: EN - target_lang: DE - entry_count: 1 - - source_lang: DE - target_lang: EN - entry_count: 2 - creation_time: '2021-08-03T14:16:18.429Z' - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - patch: - tags: - - ManageMultilingualGlossaries - summary: Edit glossary details - description: Edit glossary details, such as name or a dictionary for a source and target language. - operationId: patchMultilingualGlossary - parameters: - - $ref: '#/components/parameters/GlossaryID' - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/PatchMultilingualGlossaryParameters' - examples: - Basic: - value: - name: My Glossary - dictionaries: - - source_lang: en - target_lang: de - entries: "Hello\tGuten Tag" - entries_format: tsv - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/PatchMultilingualGlossaryParameters' - responses: - 200: - description: JSON object containing the glossary meta-information. - content: - application/json: - schema: - $ref: '#/components/schemas/MultilingualGlossary' - example: - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - name: My Glossary - dictionaries: - - source_lang: EN - target_lang: DE - creation_time: '2021-08-03T14:16:18.329Z' - entry_count: 1 - - source_lang: DE - target_lang: EN - creation_time: '2021-08-03T14:16:18.429Z' - entry_count: 2 - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - delete: - tags: - - ManageMultilingualGlossaries - summary: Delete a Glossary - description: Deletes the specified glossary. - operationId: deleteMultilingualGlossary - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - /v3/glossaries/{glossary_id}/entries: - get: - tags: - - ManageMultilingualGlossaries - summary: Retrieve Glossary Entries - operationId: getMultilingualGlossaryEntries - description: List the entries of a single glossary in tsv format. - parameters: - - $ref: '#/components/parameters/GlossaryID' - - name: source_lang - in: query - required: true - schema: - $ref: '#/components/schemas/GlossarySourceLanguage' - - name: target_lang - in: query - required: true - schema: - $ref: '#/components/schemas/GlossaryTargetLanguage' - responses: - 200: - description: The entries in tsv, wrapped in a JSON object. - content: - application/json: - schema: - $ref: '#/components/schemas/GlossaryDictionary' - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - /v3/glossaries/{glossary_id}/dictionaries: - delete: - tags: - - ManageMultilingualGlossaries - summary: Deletes the dictionary associated with the given language pair with the given glossary ID. - operationId: deleteDictionary - parameters: - - $ref: '#/components/parameters/GlossaryID' - - name: source_lang - in: query - required: true - schema: - $ref: '#/components/schemas/GlossarySourceLanguage' - - name: target_lang - in: query - required: true - schema: - $ref: '#/components/schemas/GlossaryTargetLanguage' - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - put: - tags: - - ManageMultilingualGlossaries - summary: "Replaces or creates a dictionary in the glossary with the specified entries." - operationId: replaceDictionary - parameters: - - $ref: '#/components/parameters/GlossaryID' - requestBody: - description: "The dictionary to insert into (or overwrite in) the multilingual glossary." - content: - application/json: - schema: - $ref: '#/components/schemas/MultilingualGlossaryEntries' - responses: - 200: - description: JSON object containing the dictionary meta-information. - content: - application/json: - schema: - $ref: '#/components/schemas/MultilingualGlossaryEntriesInformation' - example: - source_lang: EN - target_lang: DE - 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/QuotaExceededGlossaries' - 500: - $ref: '#/components/responses/InternalServerError' - 503: - $ref: '#/components/responses/ServiceUnavailable' - 529: - $ref: '#/components/responses/TooManyRequests' - security: - - auth_header: [ ] - /v2/glossaries: - post: - tags: - - ManageGlossaries - summary: Create a Glossary - operationId: createGlossary - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateGlossaryParameters' - examples: - Basic: - value: - name: My Glossary - source_lang: en - target_lang: de - entries: "Hello\tGuten Tag" - entries_format: tsv - application/x-www-form-urlencoded: - schema: - $ref: '#/components/schemas/CreateGlossaryParameters' - 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/MonolingualGlossary' - 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: - - ManageGlossaries - 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/MonolingualGlossary' - 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: [ ] - /v2/glossaries/{glossary_id}: - get: - tags: - - ManageGlossaries - 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/MonolingualGlossary' - example: - 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: [ ] - delete: - tags: - - ManageGlossaries - 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: [ ] - /v2/glossaries/{glossary_id}/entries: - get: - tags: - - ManageGlossaries - 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`. - examples: - tsv: - summary: Tab-separated Values - value: - in: header - Accept: 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: [ ] - /v2/write/rephrase: - post: - tags: - - RephraseText - summary: Request text improvement - operationId: rephraseText - requestBody: - required: true - content: - application/json: - schema: - type: object - required: - - text - properties: - text: - description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are - returned in the same order as they are requested. - type: array - items: - type: string - example: this is a example sentence to imprve - target_lang: - $ref: '#/components/schemas/TargetLanguageWrite' - writing_style: - $ref: '#/components/schemas/WritingStyle' - tone: - $ref: '#/components/schemas/WritingTone' - application/x-www-form-urlencoded: - schema: - type: object - required: - - text - properties: - text: - description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are - returned in the same order as they are requested. - type: array - items: - type: string - example: this is a example sentence to imprve - target_lang: - $ref: '#/components/schemas/TargetLanguageWrite' - writing_style: - $ref: '#/components/schemas/WritingStyle' - tone: - $ref: '#/components/schemas/WritingTone' - responses: - 200: - description: Successful text improvement. - content: - application/json: - schema: - type: object - properties: - improvements: - type: array - minItems: 1 - items: - type: object - properties: - detected_source_language: - description: The language detected in the source text. - type: string - example: en - text: - description: The improved text. - type: string - example: This is a sample sentence to improve. - security: - - auth_header: [ ] - /v2/usage: - get: - tags: - - MetaInformation - summary: Check Usage and Limits - operationId: getUsage - responses: - 200: - description: The account's usage and limits. - content: - application/json: - schema: - $ref: '#/components/schemas/UsageResponse' - examples: - free: - summary: Response for API users not on the Pro plan - value: - character_count: 180118 - character_limit: 1250000 - pro: - summary: Response for API Pro users - value: - character_count: 5947223 - character_limit: 1000000000000 - products: - - product_type: write - api_key_character_count: 0 - character_count: 5643 - - product_type: translate - api_key_character_count: 636 - character_count: 5941580 - api_key_character_count: 636 - api_key_character_limit: 1000000000000 - start_time: '2025-05-13T09:18:42Z' - end_time: '2025-06-13T09:18:42Z' - 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: [ ] - /v2/languages: - get: - tags: - - MetaInformation - summary: Retrieve Supported Languages - operationId: getLanguages - parameters: - - name: type - in: query - schema: - type: string - enum: - - source - - target - default: source - description: Supported values are "source" or "target". If type parameter is not included, defaults to "source". - examples: - target: - summary: Target Languages - value: - in: query - type: 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 - example: DE - name: - description: Name of the language in English. - type: string - example: German - supports_formality: - description: Denotes formality support in case of a target language - listing. - type: boolean - example: true - example: - - language: AR - name: Arabic - supports_formality: false - - 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: true - - language: KO - name: Korean - supports_formality: false - - language: LT - name: Lithuanian - supports_formality: false - - language: LV - name: Latvian - supports_formality: false - - language: NB - name: Norwegian (Bokmål) - 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: UK - name: Ukrainian - supports_formality: false - - language: ZH - name: Chinese (simplified) - supports_formality: false - - language: ZH-HANS - name: Chinese (simplified) - supports_formality: false - - language: ZH-HANT - name: Chinese (traditional) - 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. - QuotaExceededGlossaries: - description: Quota exceeded. Too many requests were made to the glossary endpoints recently. - 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. Example: - `DeepL-Auth-Key ` - name: Authorization - in: header - schemas: - ApiKeyId: - description: API key ID. Consists of two valid GUIDs separated by a colon. - type: string - example: ca7d5694-96eb-4263-a9a4-7f7e4211529e:20c2abcf-4c3c-4cd6-8ae8-8bd2a7d4da38 - ApiKeyLabel: - description: API key label. The default value is `DeepL API Key`. - type: string - example: "developer key prod" - ApiKeyUsageCharacters: - description: | - Restricts the number of total characters (across text translation, document translation, and text improvement) that can be consumed by an API key in a one-month usage period. - - Setting the limit to `0` means the API key will not be able to consume characters. - Setting the limit to `null` disables the limit, effectively allowing unlimited usage. - type: number - example: 5000 - ApiKey: - description: The API key. - type: object - properties: - key_id: - $ref: '#/components/schemas/ApiKeyId' - label: - $ref: '#/components/schemas/ApiKeyLabel' - creation_time: - description: Timestamp when the key was created (ISO 8601 format) - type: string - example: "2025-07-08T08:15:29.362Z" - deactivated_time: - description: Timestamp when the key was deactivated (ISO 8601 format). The default value is `null`. - type: string - example: "2025-07-09T08:15:29.362Z" - is_deactivated: - description: Flag indicating whether the API key is deactivated. The default value is `false`. - type: boolean - example: true - usage_limits: - description: Usage limits for the API key. - type: object - properties: - characters: - $ref: '#/components/schemas/ApiKeyUsageCharacters' - Context: - description: |- - Additional context that can influence a translation but is not translated itself. - - Characters included in the `context` parameter will not be counted toward billing. - type: string - example: This is context. - CreateGlossaryParameters: - 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` (default) - tab-separated values - - `csv` - comma-separated values - - See [Supported Glossary Formats](https://developers.deepl.com/api-reference/glossaries#formats) for details about each format. - type: string - enum: - - tsv - - csv - example: tsv - default: tsv - CreateMultilingualGlossaryParameters: - type: object - required: - - name - - dictionaries - properties: - name: - description: Name to be associated with the glossary. - type: string - example: My Glossary - dictionaries: - description: Dictionaries to populate the glossary with. - type: array - items: - $ref: '#/components/schemas/GlossaryDictionary' - DocumentTranslationError: - type: object - properties: - message: - type: string - description: detailed error message - DocumentKey: - 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 - Formality: - description: |- - Sets whether the translated text should lean towards formal or informal language. - This feature is only available for certain target languages. Setting this parameter - with a target language that does not support formality will fail, unless one of the - `prefer_...` options are used. - Possible options are: - * `default` (default) - * `more` - for a more formal language - * `less` - for a more informal language - * `prefer_more` - for a more formal language if available, otherwise fallback to default formality - * `prefer_less` - for a more informal language if available, otherwise fallback to default formality - type: string - enum: - - default - - more - - less - - prefer_more - - prefer_less - default: default - example: prefer_more - GlossaryDictionary: - type: object - description: A dictionary contained in a multilingual glossary. Each dictionary contains the mapping of source terms to target language terms. - properties: - source_lang: - $ref: '#/components/schemas/GlossarySourceLanguage' - target_lang: - $ref: '#/components/schemas/GlossaryTargetLanguage' - entries: - $ref: '#/components/schemas/GlossaryEntries' - entries_format: - $ref: '#/components/schemas/GlossaryEntriesFormat' - GlossaryEntries: - type: string - description: The entries of the glossary. The entries have to be specified - in the format provided by the `entries_format` parameter. - example: "Hello\tGuten Tag" - GlossaryEntriesFormat: - description: |- - The format in which the glossary entries are provided. Formats currently available: - - `tsv` (default) - tab-separated values - - `csv` - comma-separated values - - See [Supported Glossary Formats](https://www.deepl.com/docs-api/glossaries/formats) for details about each format. - type: string - enum: - - tsv - - csv - example: tsv - default: tsv - GlossaryEntryCount: - description: The number of entries in the glossary. - type: integer - GlossaryId: - type: string - description: A unique ID assigned to a glossary. - example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - GlossaryName: - description: Name associated with the glossary. - type: string - GlossarySourceLanguage: - type: string - description: The language in which the source texts in the glossary are specified. - enum: - - ar - - bg - - cs - - da - - de - - el - - en - - es - - et - - fi - - fr - - he - - hu - - id - - it - - ja - - ko - - lt - - lv - - nb - - nl - - pl - - pt - - ro - - ru - - sk - - sl - - sv - - th - - tr - - uk - - vi - - zh - example: en - GlossaryTargetLanguage: - type: string - description: The language in which the target texts in the glossary are specified. - enum: - - ar - - bg - - cs - - da - - de - - el - - en - - es - - et - - fi - - fr - - he - - hu - - id - - it - - ja - - ko - - lt - - lv - - nb - - nl - - pl - - pt - - ro - - ru - - sk - - sl - - sv - - th - - tr - - uk - - vi - - zh - example: de - ModelType: - type: string - description: Specifies which DeepL model should be used for translation. - enum: - - quality_optimized - - prefer_quality_optimized - - latency_optimized - MonolingualGlossary: - 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 - MultilingualGlossary: - type: object - properties: - glossary_id: - $ref: '#/components/schemas/GlossaryId' - name: - $ref: '#/components/schemas/GlossaryName' - dictionaries: - description: |- - List of dictionaries contained in this glossary. - Each dictionary contains a source and target language, as well as pairs of source and target entries. - type: array - items: - $ref: '#/components/schemas/GlossaryDictionary' - 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 - example: - glossary_id: def3a26b-3e84-45b3-84ae-0c0aaf3525f7 - name: My Glossary - dictionaries: - - source_lang: en - target_lang: de - entry_count: 1 - creation_time: '2021-08-03T14:16:18.329Z' - MultilingualGlossaryEntries: - type: object - properties: - source_lang: - $ref: '#/components/schemas/GlossarySourceLanguage' - target_lang: - $ref: '#/components/schemas/GlossaryTargetLanguage' - entries: - $ref: '#/components/schemas/GlossaryEntries' - entries_format: - $ref: '#/components/schemas/GlossaryEntriesFormat' - MultilingualGlossaryEntriesResponse: - type: object - properties: - dictionaries: - type: array - items: - $ref: '#/components/schemas/MultilingualGlossaryEntriesInformation' - MultilingualGlossaryEntriesInformation: - type: object - properties: - source_lang: - $ref: '#/components/schemas/GlossarySourceLanguage' - target_lang: - $ref: '#/components/schemas/GlossaryTargetLanguage' - entry_count: - $ref: '#/components/schemas/GlossaryEntryCount' - OutlineDetectionOption: - description: |- - Disable the automatic detection of XML structure by setting the `outline_detection` parameter - to `false` and selecting the tags that should be considered structure tags. This will split sentences - using the `splitting_tags` parameter. - type: boolean - default: true - OutlineDetectionOptionStr: - description: |- - Disable the automatic detection of XML structure by setting the `outline_detection` parameter - to `false` and selecting the tags that should be considered structure tags. This will split sentences - using the `splitting_tags` parameter. - type: string - default: '1' - enum: - - '0' - PatchMultilingualGlossaryParameters: - type: object - properties: - name: - $ref: '#/components/schemas/GlossaryId' - dictionaries: - description: Dictionaries to edit the glossary with. Currently only supports 0 or 1 dictionaries in the array. - type: array - items: - $ref: '#/components/schemas/GlossaryDictionary' - PreserveFormattingOption: - description: |- - Sets whether the translation engine should respect the original formatting, even if it would usually - correct some aspects. - type: boolean - default: false - PreserveFormattingOptionStr: - description: |- - Sets whether the translation engine should respect the original formatting, even if it would usually - correct some aspects. - type: string - enum: - - '0' - - '1' - default: '0' - ShowBilledCharacters: - description: |- - When true, the response will include the billed_characters parameter, giving the - number of characters from the request that will be counted by DeepL for billing purposes. - type: boolean - SplitSentencesOption: - description: |- - Sets whether the translation engine should first split the input into sentences. - - Possible values are: - * 0 - no splitting at all, whole input is treated as one sentence - * 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines - * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines - type: string - enum: - - '0' - - '1' - - nonewlines - default: '1' - example: '1' - SourceLanguage: - type: string - description: |- - Language of the text to be translated. If this parameter is omitted, the API will attempt to - detect the language of the text and translate it. - enum: - - AR - - BG - - CS - - DA - - DE - - EL - - EN - - ES - - ET - - FI - - FR - - HU - - ID - - IT - - JA - - KO - - LT - - LV - - NB - - NL - - PL - - PT - - RO - - RU - - SK - - SL - - SV - - TR - - UK - - ZH - example: EN - TagHandlingOption: - description: |- - Sets which kind of tags should be handled. Options currently available: - * `xml` - * `html` - type: string - enum: - - xml - - html - example: html - NonSplittingTagCommaSeparatedList: - allOf: - - $ref: '#/components/schemas/TagCommaSeparatedList' - description: Comma-separated list of XML tags which never split sentences. - NonSplittingTagList: - allOf: - - $ref: '#/components/schemas/TagList' - description: |- - 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). - SplittingTagCommaSeparatedList: - allOf: - - $ref: '#/components/schemas/TagCommaSeparatedList' - description: |- - Comma-separated list of XML tags which always cause splits. - - - See the example in the `outline_detection` parameter's description. - SplittingTagList: - allOf: - - $ref: '#/components/schemas/TagList' - description: |- - List of XML tags which always cause splits. - - - See the example in the `outline_detection` parameter's description. - IgnoreTagCommaSeparatedList: - allOf: - - $ref: '#/components/schemas/TagCommaSeparatedList' - description: Comma-separated list of XML tags that indicate text not to be translated. - IgnoreTagList: - allOf: - - $ref: '#/components/schemas/TagList' - description: List of XML tags that indicate text not to be translated. - TagCommaSeparatedList: - description: Comma-separated list of XML tags. - type: string - example: a,p,span - TagList: - description: List of XML tags. - type: array - items: - type: string - example: - - a - - p - - span - TargetLanguage: - type: string - description: The language into which the text should be translated. - enum: - - AR - - BG - - CS - - DA - - DE - - EL - - EN-GB - - EN-US - - ES - - ET - - FI - - FR - - HU - - ID - - IT - - JA - - KO - - LT - - LV - - NB - - NL - - PL - - PT-BR - - PT-PT - - RO - - RU - - SK - - SL - - SV - - TR - - UK - - ZH - - ZH-HANS - - ZH-HANT - example: DE - TargetLanguageText: - type: string - description: |- - The language into which the text should be translated. - enum: - - AR - - BG - - CS - - DA - - DE - - EL - - EN-GB - - EN-US - - ES - - ES-419 - - ET - - FI - - FR - - HE - - HU - - ID - - IT - - JA - - KO - - LT - - LV - - NB - - NL - - PL - - PT-BR - - PT-PT - - RO - - RU - - SK - - SL - - SV - - TH - - TR - - UK - - VI - - ZH - - ZH-HANS - - ZH-HANT - example: DE - TargetLanguageWrite: - type: string - description: |- - The language for the text improvement. - enum: - - de - - en - - en-GB - - en-US - - es - - fr - - it - - pt - - pt-BR - - pt-PT - example: de - WritingStyle: - type: string - description: |- - Specify a style to rephrase your text in a way that fits your audience and goals. - The `prefer_` prefix allows falling back to the default style if the language does not yet support styles. - enum: - - academic - - business - - casual - - default - - simple - - prefer_academic - - prefer_business - - prefer_casual - - prefer_simple - WritingTone: - type: string - description: |- - Specify the desired tone for your text. - The `prefer_` prefix allows falling back to the default tone if the language does not yet support tones. - enum: - - confident - - default - - diplomatic - - enthusiastic - - friendly - - prefer_confident - - prefer_diplomatic - - prefer_enthusiastic - - prefer_friendly - UsageResponse: - type: object - properties: - character_count: - description: Characters translated so far in the current billing period. - type: integer - format: int64 - example: 180118 - character_limit: - description: Current maximum number of characters that can be translated per billing period. If cost control is set, the cost control limit will be returned in this field. - type: integer - format: int64 - example: 1250000 - products: - type: array - description: Only present for API Pro users. Per-product usage details. - items: - type: object - properties: - product_type: - type: string - description: The type of product (e.g., 'write', 'translate'). - example: write - api_key_character_count: - type: integer - description: Characters used for this product by this API key in the current period. - example: 0 - character_count: - type: integer - description: Total characters used for this product in the current period. - example: 5643 - api_key_character_count: - type: integer - description: Only present for API Pro users. Total characters used by this API key in the current period. - example: 636 - api_key_character_limit: - type: integer - description: Only present for API Pro users. Character limit for this API key in the current period. - example: 1000000000000 - start_time: - type: string - format: date-time - description: Only present for API Pro users. Start time of the current billing period (ISO 8601). - example: '2025-05-13T09:18:42Z' - end_time: - type: string - format: date-time - description: Only present for API Pro users. End time of the current billing period (ISO 8601). - example: '2025-06-13T09:18:42Z' diff --git a/docs.json b/docs.json index 498bb97..d4501a7 100644 --- a/docs.json +++ b/docs.json @@ -238,7 +238,8 @@ }, "playground": { "proxy": false - } + }, + "openapi": "https://raw.githubusercontent.com/DeepLcom/openapi/main/openapi_gitbook.yaml" }, "errors": { "404": {