openapi: 3.0.3
info:
title: DeepL API Documentation
description: The DeepL API provides programmatic access to DeepL’s language AI
technology.
termsOfService: https://www.deepl.com/pro-license
contact:
name: DeepL - Contact us
url: https://www.deepl.com/contact-us
version: 3.9.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.
To learn more about context in DeepL API translations, we recommend [this article](https://www.deepl.com/docs-api/general/working-with-context).
- 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
* `jpeg / jpg / png` - Image
Please note that with every submitted document of type .pptx, .docx, .xlsx, 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.
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.
To learn more about context in DeepL API translations, we recommend [this article](https://www.deepl.com/docs-api/general/working-with-context).
- name: RephraseText
description: |-
The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone.
For more details, visit [this documentation page](https://developers.deepl.com/docs/api-reference/improve-text)
- 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.
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 glossary 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`).
Glossaries with target language `EN` can be used in translations with either English variant.
Similarly `PT`, and `ZH` glossaries can be used in translations with their corresponding variants.
Note that on the v2 API, glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.
As a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application
and then use the following procedure for modifications:
- [download](https://www.deepl.com/docs-api/glossaries/get-glossary-entries) and store the current glossary's entries,
- locally modify the glossary entries,
- [delete](https://www.deepl.com/docs-api/glossaries/delete-glossary) the existing glossary,
- [create a new glossary](https://www.deepl.com/docs-api/glossaries/create-glossary) with the same name.
- name: MetaInformation
description: Information about API usage and value ranges
- name: VoiceAPI
description: |-
The Voice API provides real-time voice transcription and translation services.
Use a two-step flow: first request a streaming URL via REST, then establish a WebSocket connection for streaming audio and receiving transcriptions.
paths:
/v2/translate:
post:
tags:
- TranslateText
summary: Request Translation
operationId: translateText
description: |-
The translate function.
The total request body size must not exceed 128 KiB (128 · 1024 bytes). Please split up your text into multiple
calls if it exceeds this limit.
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
multiple times and translations are returned in the same order as they are requested. Each of the
parameter values may contain multiple sentences.
type: array
items:
type: string
example: Hello, World!
source_lang:
$ref: '#/components/schemas/SourceLanguage'
target_lang:
$ref: '#/components/schemas/TargetLanguage'
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:
allOf:
- $ref: '#/components/schemas/GlossaryId'
- 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
custom_instructions:
description: |-
Specify a list of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
**Important:** The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
**Note:** Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected.
type: array
items:
type: string
example: "Use a friendly, diplomatic tone"
enable_beta_languages:
description: |-
Enables 81 additional beta languages. See the full list at https://developers.deepl.com/docs/getting-started/supported-languages#beta-languages. **Note:** Any request with the `enable_beta_languages` parameter enabled will use `quality_optimized` models. Requests combining `enable_beta_languages: true` and `model_type: latency_optimized` will be rejected. Beta languages do not support formality or glossaries.
type: boolean
default: false
tag_handling:
$ref: '#/components/schemas/TagHandlingOption'
outline_detection:
$ref: '#/components/schemas/OutlineDetectionOption'
non_splitting_tags:
$ref: '#/components/schemas/NonSplittingTagList'
splitting_tags:
$ref: '#/components/schemas/SplittingTagList'
ignore_tags:
$ref: '#/components/schemas/IgnoreTagList'
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.
type: array
items:
type: string
source_lang:
$ref: '#/components/schemas/SourceLanguage'
target_lang:
$ref: '#/components/schemas/TargetLanguage'
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:
allOf:
- $ref: '#/components/schemas/GlossaryId'
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.
tag_handling:
$ref: '#/components/schemas/TagHandlingOption'
tag_handling_version:
$ref: '#/components/schemas/TagHandlingVersionOption'
outline_detection:
$ref: '#/components/schemas/OutlineDetectionOptionStr'
non_splitting_tags:
$ref: '#/components/schemas/NonSplittingTagCommaSeparatedList'
splitting_tags:
$ref: '#/components/schemas/SplittingTagCommaSeparatedList'
ignore_tags:
$ref: '#/components/schemas/IgnoreTagCommaSeparatedList'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
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
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
examples:
Basic:
value:
translations:
- detected_source_language: EN
text: Hallo, Welt!
billed_characters: 42
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: []
/v2/document:
post:
tags:
- TranslateDocuments
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 documents is [available here](https://support.deepl.com/hc/articles/360020582359-Document-formats)
and may vary based on API plan and document type.
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:
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
* `jpeg / jpg / png` - Image
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.
Note: Not all combinations of input file and translation file extensions are permitted. See [Document Format Conversions](https://www.deepl.com/docs-api/documents/format-conversions) for the permitted combinations.
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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: []
/v2/document/{document_id}:
post:
tags:
- TranslateDocuments
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:
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
The characters will only be billed after a successful download
request.
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: []
/v2/document/{document_id}/result:
post:
tags:
- TranslateDocuments
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:
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/MultilingualGlossary'
400:
$ref: '#/components/responses/BadRequestGlossaries'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
413:
$ref: '#/components/responses/PayloadTooLarge'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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/Forbidden'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/ForbiddenGlossaries'
404:
$ref: '#/components/responses/NotFound'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
400:
$ref: '#/components/responses/BadRequestGlossaries'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/ForbiddenGlossaries'
404:
$ref: '#/components/responses/NotFound'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
400:
$ref: '#/components/responses/BadRequestGlossaries'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/ForbiddenGlossaries'
404:
$ref: '#/components/responses/NotFound'
429:
$ref: '#/components/responses/TooManyRequests'
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'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PutMultilingualGlossaryParameters'
responses:
200:
description: JSON object containing the dictionary meta-information.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/MonolingualGlossary'
400:
$ref: '#/components/responses/BadRequestGlossaries'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
413:
$ref: '#/components/responses/PayloadTooLarge'
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:
- 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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
400:
$ref: '#/components/responses/BadRequestGlossaries'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/ForbiddenGlossaries'
404:
$ref: '#/components/responses/NotFound'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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'
415:
$ref: '#/components/responses/UnsupportedMediaTypeGlossaries'
429:
$ref: '#/components/responses/TooManyRequests'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
billing_unit: characters
api_key_unit_count: 0
account_unit_count: 5643
api_key_character_count: 0
character_count: 5643
- product_type: translate
billing_unit: characters
api_key_unit_count: 636
account_unit_count: 5941580
api_key_character_count: 636
character_count: 5941580
- product_type: speech_to_text
billing_unit: milliseconds
api_key_unit_count: 1800000
account_unit_count: 1800000
api_key_character_count: 0
character_count: 0
api_key_character_count: 636
api_key_character_limit: 1000000000000
speech_to_text_milliseconds_count: 1800000
speech_to_text_milliseconds_limit: 36000000
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
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/translate-text/translate-text) requests.
* `target`: For languages that can be used in the `target_lang` parameter of [translate](https://www.deepl.com/docs-api/translate-text/translate-text) requests.
schema:
type: string
enum:
- source
- target
default: source
examples:
target:
summary: Target Languages
value:
in: query
type: target
responses:
200:
description: JSON array where each item represents a supported language.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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: 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: ES-419
name: Spanish (Latin American)
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: HE
name: Hebrew
supports_formality: false
- 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: TH
name: Thai
supports_formality: false
- language: TR
name: Turkish
supports_formality: false
- language: UK
name: Ukrainian
supports_formality: false
- language: VI
name: Vietnamese
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: []
/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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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'
speech_to_text_milliseconds:
$ref: '#/components/schemas/ApiKeyUsageSpeechToTextMilliseconds'
responses:
200:
description: The set usage limits function returns a JSON representation of the modified API key.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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/analytics:
get:
tags:
- AdminApi
summary: Get usage statistics as an admin
operationId: adminGetAnalytics
description: |-
Retrieve usage statistics for the organization within a specified date range.
Optionally group the results by API key or by API key and day.
parameters:
- name: start_date
in: query
required: true
description: Start date for the usage report (ISO 8601 date format).
schema:
type: string
format: date
example: "2025-09-29"
- name: end_date
in: query
required: true
description: End date for the usage report (ISO 8601 date format).
schema:
type: string
format: date
example: "2025-10-01"
- name: group_by
in: query
required: false
description: |-
Optional parameter to group usage statistics. Possible values:
* `key` - Group by API key
* `key_and_day` - Group by API key and usage date
schema:
type: string
enum:
- key
- key_and_day
example: "key_and_day"
responses:
200:
description: The usage statistics for the specified date range.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUsageReport'
examples:
withGrouping:
summary: Usage report grouped by key and day
value:
usage_report:
total_usage:
total_characters: 9619
text_translation_characters: 4892
document_translation_characters: 0
text_improvement_characters: 4727
speech_to_text_milliseconds: 1800000
group_by: "key_and_day"
start_date: "2025-09-29T00:00:00"
end_date: "2025-10-01T00:00:00"
key_and_day_usages:
- api_key: "dc88****3a2c"
api_key_label: "Staging API Key"
usage_date: "2025-09-29T00:00:00Z"
usage:
total_characters: 315
text_translation_characters: 159
document_translation_characters: 0
text_improvement_characters: 156
speech_to_text_milliseconds: 1800000
withoutGrouping:
summary: Usage report without grouping
value:
usage_report:
total_usage:
total_characters: 9619
text_translation_characters: 4892
document_translation_characters: 0
text_improvement_characters: 4727
speech_to_text_milliseconds: 1800000
start_date: "2025-09-29T00:00:00"
end_date: "2025-10-01T00:00:00"
400:
description: Bad request. Please check error message and your parameters.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message describing the issue.
examples:
dateRangeExceeded:
summary: Date range exceeds maximum allowed
value:
message: "Bad request. Reason: Date range cannot exceed 366 days"
invalidGroupBy:
summary: Invalid group_by parameter value
value:
message: "Value for 'group_by' not supported. Allowed: '', 'key', 'key_and_day'."
403:
$ref: '#/components/responses/Forbidden'
404:
$ref: '#/components/responses/NotFound'
500:
$ref: '#/components/responses/InternalServerError'
security:
- auth_header: [ ]
/v3/style_rules:
get:
summary: Retrieve style rule lists
operationId: getStyleRuleLists
parameters:
- name: page
in: query
schema:
type: integer
default: 0
description: The index of the first page to return. Use with `page_size` to get the next page of rule lists
- name: page_size
in: query
schema:
type: integer
default: 10
minimum: 1
maximum: 25
description: The maximum number of style rule lists to return.
- name: detailed
in: query
schema:
type: boolean
default: false
description: Determines if the rule list's `configured_rules` and `custom_instructions` should be included in the response body.
responses:
200:
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
type: object
properties:
style_rules:
type: array
items:
$ref: '#/components/schemas/StyleRuleList'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
429:
$ref: '#/components/responses/TooManyRequests'
500:
$ref: '#/components/responses/InternalServerError'
503:
$ref: '#/components/responses/ServiceUnavailable'
security:
- auth_header: []
/v3/voice/realtime:
post:
tags:
- VoiceAPI
summary: Get Streaming URL
operationId: getVoiceStreamingUrl
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- source_media_content_type
properties:
source_media_content_type:
$ref: '#/components/schemas/VoiceMediaContentType'
source_language:
$ref: '#/components/schemas/VoiceSourceLanguage'
source_language_mode:
$ref: '#/components/schemas/VoiceSourceLanguageMode'
target_languages:
$ref: '#/components/schemas/VoiceTargetLanguages'
glossary_id:
$ref: '#/components/schemas/GlossaryId'
formality:
$ref: '#/components/schemas/VoiceFormality'
examples:
basic:
summary: Basic configuration
value:
source_media_content_type: 'audio/ogg; codecs=opus'
source_language: 'en'
source_language_mode: 'auto'
target_languages: ['de', 'fr', 'es']
with_glossary:
summary: With glossary and formality
value:
source_media_content_type: 'audio/pcm; encoding=s16le; rate=16000'
source_language: 'en'
source_language_mode: 'fixed'
target_languages: ['de', 'fr']
glossary_id: 'def3a26b-3e84-45b3-84ae-0c0aaf3525f7'
formality: 'formal'
responses:
200:
description: Successfully obtained streaming URL and token
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceStreamingResponse'
example:
streaming_url: 'wss://api.deepl.com/v3/voice/realtime/connect'
token: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
429:
$ref: '#/components/responses/TooManyRequests'
456:
$ref: '#/components/responses/QuotaExceeded'
500:
$ref: '#/components/responses/InternalServerError'
503:
$ref: '#/components/responses/ServiceUnavailable'
security:
- auth_header: []
get:
tags:
- VoiceAPI
summary: Request Reconnection
operationId: requestReconnection
parameters:
- name: token
in: query
required: true
description: The latest ephemeral token obtained for the stream.
schema:
type: string
example: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K'
responses:
200:
description: Successfully obtained streaming URL and reconnection token.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceStreamingResponse'
example:
streaming_url: 'wss://api.deepl.com/v3/voice/realtime/connect'
token: 'VGhpcyBpcyBhIGZha2UgdG9rZW4K'
session_id: '4f911080-cfe2-41d4-8269-0e6ec15a0354'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Forbidden'
429:
$ref: '#/components/responses/TooManyRequests'
456:
$ref: '#/components/responses/QuotaExceeded'
500:
$ref: '#/components/responses/InternalServerError'
503:
$ref: '#/components/responses/ServiceUnavailable'
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'
headers:
X-Trace-ID:
description: A unique identifier for the request that can be included in bug reports to DeepL support.
schema:
type: string
example: 501c3d93cc0c4f11ae2f60a226c2f0f0
ConfiguredRules:
description: The enabled rules for the style rule list including what option
was selected for each rule. This schema combines rules from all supported
languages.
type: object
properties:
dates_and_times:
type: object
properties:
calendar_era:
type: string
description: Formatting options for Calendar Era
enum:
- use_bc_and_ad
- use_bce_and_ce
centuries:
type: string
description: Formatting options for Centuries
enum:
- spell_out
- use_arabic_numerals
- use_numerals
- use_roman_numerals
date_format:
type: string
description: Formatting options for Date Format
enum:
- use_dd_period_mm_period_yy_with_leading_zeros_for_single_digit_days_and_months
- use_dd_period_mm_period_yyyy
- use_dd_period_mm_period_yyyy_with_leading_zeros_for_single_digit_days_and_months
- use_dd_period_space_abbreviated_month_yyyy_with_abbreviations_jan_period_feb_period_mrz_period_apr_period_mai_jun_period_jul_period_aug_period_sep_period_okt_period_nov_period_dez_period_without_leading_zeros_for_single_digit_days
- use_dd_period_space_abbreviated_month_yyyy_with_abbreviations_jan_period_febr_period_maerz_apr_period_mai_juni_juli_aug_period_sept_period_okt_period_nov_period_dez_period_without_leading_zeros_for_single_digit_days
- use_dd_period_space_month_yyyy_without_leading_zeros_for_single_digit_days
- use_dd_slash_mm_slash_yyyy
- use_dd_slash_mm_slash_yyyy_with_leading_zeros_for_single_digit_days_and_months
- use_dd_space_spelled_out_month_space_yyyy
- use_dd_space_spelled_out_month_space_yyyy_and_use_spanish_word_septiembre_for_ninth_month
- use_dd_space_spelled_out_month_space_yyyy_and_use_spanish_word_setiembre_for_ninth_month
- use_dd_space_spelled_out_month_space_yyyy_without_leading_zeros_for_single_digit_days
- use_historical_eras_and_write_numbers_in_chinese_followed_by_chinese_word_公元前_or_公元后_with_arabic_numerals_in_parentheses
- use_mm_slash_dd_slash_yyyy_with_leading_zeros_for_single_digit_days_and_months
- use_numerals_only_with_leading_zero_for_single_digits
- use_numerals_only_without_leading_zero_for_single_digits
- use_spelled_out_month_space_dd_comma_space_yyyy_and_use_spanish_word_septiembre_for_ninth_month
- use_spelled_out_month_space_dd_comma_space_yyyy_without_leading_zeros_for_single_digit_days
- use_traditional_calendar_system_with_chinese_numbers
- use_yyyy_chinese_word_年_mm_chinese_word_月_dd_chinese_word_日_with_chinese_numbers
- use_yyyy_chinese_word_年_mm_chinese_word_月_dd_chinese_word_日_without_leading_zero_for_single_digit_months_and_days
- use_yyyy_hyphen_mm_hyphen_dd_with_leading_zero_for_single_digit_days_and_months
- use_yyyy_hyphen_mm_hyphen_dd_with_leading_zeros_for_single_digit_days_and_months
- use_yyyy_korean word_년_space_mm_korean word_월_space_dd_korean word_일_without_leading_zero_for_single_digit_days_and_months
- use_yyyy_period_mm_period_dd
- use_yyyy_period_space_mm_period_space_dd_period_space_without_leading_zero_for_single_digit_days_and_months
- use_yyyy_slash_mm_slash_dd
- use_yyyy_slash_mm_slash_dd_with_leading_zero_for_single_digit_days_and_months
dates_in_numerical_form:
type: string
description: Formatting options for Dates In Numerical Form
enum:
- use_dd_hyphen_mm_hyphen_yyyy
- use_dd_period_mm_period_yyyy
- use_dd_slash_mm_slash_yyyy
decades:
type: string
description: Formatting options for Decades
enum:
- spell_out
- use_apostrophe_yy
- use_yy_for_20th_century_but_yyyy_for_other_centuries
- use_yy_without_apostrophe
- use_yyyy
hours_minutes_seconds_separator:
type: string
description: Formatting options for Hours Minutes Seconds Separator
enum:
- use_colon
- use_period
hours_minutes_separator:
type: string
description: Formatting options for Hours Minutes Separator
enum:
- use_colon_without_spaces
- use_letter_h_with_regular_space_on_either_side
- use_letter_h_without_spaces
midnight_in_numerals:
type: string
description: Formatting options for Midnight In Numerals
enum:
- use_00_00
- use_24_00
single_digit_days_and_months:
type: string
description: Formatting options for Single Digit Days And Months
enum:
- do_not_use_leading_zero
- use_leading_zero
single_digit_hours:
type: string
description: Formatting options for Single Digit Hours
enum:
- do_not_use_leading_zero
- use_leading_zero
time_format:
type: string
description: Formatting options for Time Format
enum:
- spell_out_time_in_words
- use_12_hour_clock_and_do_not_specify_morning_or_evening
- use_12_hour_clock_and_lowercase_am_or_pm_with_periods
- use_12_hour_clock_and_lowercase_am_or_pm_with_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm
- use_12_hour_clock_and_lowercase_am_or_pm_without_periods
- use_12_hour_clock_and_lowercase_am_or_pm_without_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm
- use_12_hour_clock_and_specify_morning_or_evening
- use_12_hour_clock_and_uppercase_am_or_pm_with_periods
- use_12_hour_clock_and_uppercase_am_or_pm_with_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm
- use_12_hour_clock_and_uppercase_am_or_pm_without_periods
- use_12_hour_clock_and_uppercase_am_or_pm_without_periods_except_use_noon_and_midnight_instead_of_12_am_and_12_pm
- use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals
- use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals_with_chinese_word_点_for_hours
- use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_arabic_numerals_with_chinese_words_时_and_分_for_hours_and_minutes
- use_12_hour_clock_and_write_chinese_word_上午_or_下午_or_chinese_word_早上_or_晚上_followed_by_chinese_numbers_with_chinese_words_时_and_分_for_hours_and_minutes
- use_12_hour_clock_with_arabic_numerals_and_colon
- use_12_hour_clock_with_korean_words_시_and_분
- use_12_hour_clock_without_leading_zero_or_minutes_for_full_hours_use_colon_as_separator_and_lowercase_am_or_pm_without_periods
- use_12_hour_clock_without_leading_zero_or_minutes_for_full_hours_use_colon_as_separator_and_uppercase_am_or_pm_without_periods
- use_12_hour_clock_without_leading_zero_use_period_as_separator_and_lowercase_am_or_pm_with_periods_and_spaces
- use_24_hour_clock
- use_24_hour_clock_with_arabic_numerals_and_colon
- use_24_hour_clock_with_colon_as_separator
- use_24_hour_clock_with_korean_words_시_and_분
- use_24_hour_clock_with_period_as_separator
- use_hh_colon_mm_german_word_uhr_with_leading_zeros_for_single_digit_hours
- use_hh_colon_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours
- use_hh_period_mm_german_word_uhr_with_leading_zeros_for_single_digit_hours
- use_hh_period_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours
- use_hh_period_mm_german_word_uhr_without_leading_zeros_for_single_digit_hours_and_for_full_hours_state_hour_only
writing_dates:
type: string
description: Formatting options for Writing Dates
enum:
- use_dd_space_spelled_out_month_space_yyyy
- use_numerals
years:
type: string
description: Formatting options for Years
enum:
- use_apostrophe_yy
- use_common_era
- use_japanese_imperial_era
- use_yyyy
formatting:
type: object
properties:
email_address_format:
type: string
description: Formatting options for Email Address Format
enum:
- place_domain_in_parentheses
- replace_at_symbol_with_english_word_at_in_brackets_and_replace_periods_with_english_word_dot_in_brackets
- replace_at_symbol_with_english_word_at_in_brackets_with_space_on_either_side
- replace_at_symbol_with_english_word_at_in_parentheses_with_space_on_either_side
- replace_at_symbol_with_english_word_at_with_space_on_either_side
- use_standard_format
email_address_website_url:
type: string
description: Formatting options for Email Address Website Url
enum:
- use_lowercase_for_email_addresses_and_website_urls_except_when_url_includes_case_sensitive_elements
headings_case_style:
type: string
description: Formatting options for Headings Case Style
enum:
- use_sentence_case_for_titles_and_headings
- use_title_case_for_titles_and_headings
phone_number_country_code_format:
type: string
description: Formatting options for Phone Number Country Code Format
enum:
- use_00_before_country_code
- use_plus_sign_before_country_code
phone_number_format:
type: string
description: Formatting options for Phone Number Format
enum:
- do_not_use_spaces
- do_not_use_spaces_or_special_characters_between_digits_of_phone_number
- keep_original_format
- place_area_code_in_parentheses_followed_by_space
- separate_area_code_and_phone_number_with_slash
- separate_area_code_and_phone_number_with_space
- separate_country_code_area_code_local_prefix_and_last_four_digits_with_hyphens
- separate_country_code_area_code_local_prefix_and_last_four_digits_with_periods
- separate_country_code_area_code_local_prefix_and_last_four_digits_with_spaces
- use_north_american_numbering_plan_format
- use_space_after_country_code
space_between_arabic_numerals_and_unit:
type: string
description: Formatting options for Space Between Arabic Numerals And
Unit
enum:
- do_not_use
space_between_chinese_and_english:
type: string
description: Formatting options for Space Between Chinese And English
enum:
- do_not_use
space_between_chinese_characters_and_arabic_numerals:
type: string
description: Formatting options for Space Between Chinese Characters
And Arabic Numerals
enum:
- do_not_use
titles_headings_punctuation:
type: string
description: Formatting options for Titles Headings Punctuation
enum:
- do_not_use_colon_at_end_of_titles_or_headings
- do_not_use_colons_or_periods_at_end_of_titles_or_headings
numbers:
type: object
properties:
approximate_numbers:
type: string
description: Formatting options for Approximate Numbers
enum:
- use_kanji_numbers
currency_format:
type: string
description: Formatting options for Currency Format
enum:
- spell_out
- spell_out_currency_name_followed_by_amount_in_arabic_numerals_without_space
- spell_out_currency_name_followed_by_amount_in_chinese
- use_amount_followed_by_currency_symbol_without_space
- use_amount_followed_by_space_then_currency_symbol
- use_amount_followed_by_space_then_iso_code
- use_amount_followed_by_space_then_spell_out_currency_name
- use_amount_followed_by_space_then_spell_out_currency_name_in_lowercase
- use_amount_followed_by_spelled_out_currency_name_in_japanese_without_space
- use_amount_followed_by_spelled_out_currency_name_without_space
- use_currency_symbol_but_spell_out_if_no_symbol_exists
- use_currency_symbol_but_use_iso_code_if_no_symbol_exists
- use_currency_symbol_followed_by_amount_in_arabic_numerals_without_space
- use_currency_symbol_followed_by_amount_without_space
- use_currency_symbol_followed_by_space_then_amount
- use_currency_symbol_followed_by_space_then_amount_in_arabic_numerals
- use_full_width_currency_symbol_followed_by_amount_without_space
- use_half_width_currency_symbol_followed_by_amount_without_space
- use_half_width_currency_symbol_followed_by_space_then_amount
- use_iso_code
- use_iso_code_followed_by_space_then_amount
- use_iso_code_followed_by_space_then_amount_in_arabic_numerals
decimal_numbers_less_than_one:
type: string
description: Formatting options for Decimal Numbers Less Than One
enum:
- always_use_0_before_decimal_separator
decimal_separator:
type: string
description: Formatting options for Decimal Separator
enum:
- use_comma_and_do_not_use_thousands_separator
- use_comma_as_decimal_separator
- use_comma_do_not_use_thousands_separator_and_use_period_only_for_radio_stations
- use_period_and_do_not_use_thousands_separator
- use_period_as_decimal_separator
dimensions_separator:
type: string
description: Formatting options for Dimensions Separator
enum:
- use_multiplication_sign_between_dimensions_with_space_on_either_side
- use_multiplication_sign_between_dimensions_without_space_on_either_side
- use_x_between_dimensions_with_space_on_either_side
- use_x_between_dimensions_without_space_on_either_side
equation_formula_reference:
type: string
description: Formatting options for Equation Formula Reference
enum:
- always_use_arabic_numerals_to_number_equations_or_formulas_referenced_in_text
kanji_numbers:
type: string
description: Formatting options for Kanji Numbers
enum:
- use_kanji_numbers_for_numbers_in_phrases_and_counting_method_based_on_native_japanese_readings
large_number_format:
type: string
description: Formatting options for Large Number Format
enum:
- always_use_arabic_numerals
- spell_out_large_numbers
- use_abbreviations_for_large_numbers
- use_chinese_characters_for_ten_thousands_and_hundred_millions
- use_comma_to_separate_large_numbers_into_units_of_three_except_for_calendar_years
- use_kanji_for_trillions_hundred_millions_and_ten_thousands
- use_korean_words_만_억_조_with_space
- use_korean_words_만_억_조_without_space
large_sums_of_money:
type: string
description: Formatting options for Large Sums Of Money
enum:
- spell_out_italian_words_milione_and_miliardo
- use_italian_words_mio_and_mrd_instead_of_italian_words_milione_and_miliardo
large_sums_of_money_format:
type: string
description: Formatting options for Large Sums Of Money Format
enum:
- use_amount_followed_by_abbreviation_for_million_or_billion_without_space
- use_amount_followed_by_space_then_abbreviation_for_million_or_billion
- use_amount_followed_by_space_then_english_word_million_or_billion
list_of_measurements_with_units:
type: string
description: Formatting options for List Of Measurements With Units
enum:
- repeat_unit_for_each_measurement_in_list
mathematical_expression_spacing:
type: string
description: Formatting options for Mathematical Expression Spacing
enum:
- use_space_between_elements_of_mathematical_expression_or_equation
number_format:
type: string
description: Formatting options for Number Format
enum:
- use_half_width_comma_to_separate_large_numbers_into_units_of_three_except_for_calendar_years_and_use_half_width_period_as_decimal_separator
number_separator:
type: string
description: Formatting options for Number Separator
enum:
- do_not_use_chinese_comma_to_separate_numbers_indicating_approximate_value
- use_chinese_comma_to_separate_numbers_in_abbreviations
numbers_of_5_digits_or_more:
type: string
description: Formatting options for Numbers Of 5 Digits Or More
enum:
- use_comma_as_decimal_separator_and_period_as_thousands_separator
- use_comma_as_decimal_separator_and_space_as_thousands_separator
- use_comma_as_decimal_separator_period_as_thousands_separator_and_period_for_radio_stations
- use_comma_as_decimal_separator_space_as_thousands_separator_and_period_for_radio_stations
- use_period_as_decimal_separator_and_comma_as_thousands_separator
- use_period_as_decimal_separator_and_space_as_thousands_separator
numbers_up_to_4_digits:
type: string
description: Formatting options for Numbers Up To 4 Digits
enum:
- use_comma_as_decimal_separator_and_period_as_thousands_separator
- use_comma_as_decimal_separator_and_space_as_thousands_separator
- use_comma_as_decimal_separator_period_as_thousands_separator_and_period_for_radio_stations
- use_comma_as_decimal_separator_space_as_thousands_separator_and_period_for_radio_stations
- use_period_as_decimal_separator_and_comma_as_thousands_separator
- use_period_as_decimal_separator_and_space_as_thousands_separator
percentage_format:
type: string
description: Formatting options for Percentage Format
enum:
- use_arabic_numerals_followed_by_percent_symbol_without_space
- use_chinese_numbers_followed_by_chinese_word_百分之
- use_numerals_followed_by_full_width_percent_symbol_without_space
- use_numerals_followed_by_japanese_word_パーセント_without_space
- use_numerals_followed_by_korean_word_퍼센트
- use_numerals_followed_by_percent_symbol
- use_numerals_followed_by_space_then_german_word_prozent
- use_numerals_followed_by_space_then_half_width_percent_symbol
- use_numerals_followed_by_space_then_italian_word_per_cento
- use_numerals_followed_by_space_then_italian_word_percento
- use_numerals_followed_by_space_then_korean_word_퍼센트
- use_numerals_followed_by_space_then_percent_symbol
- use_numerals_followed_by_space_then_spell_out_per_cent
- use_numerals_followed_by_space_then_spell_out_percent
- use_spanish_word_por_cien
- use_spanish_word_por_ciento
reference_to_symbol:
type: string
description: Formatting options for Reference To Symbol
enum:
- spell_out_symbol_name_followed_by_symbol_in_parentheses
spelling_out_units:
type: string
description: Formatting options for Spelling Out Units
enum:
- abbreviate_units_of_measure_when_used_with_numeral_but_spell_out_when_used_without_numeral
- always_abbreviate_units_of_measure
- always_spell_out_units_of_measure
- spell_out_units_in_korean
- spell_out_units_of_measure_when_used_with_spelled_out_numbers_but_abbreviate_when_used_with_numeral
- spell_out_units_of_measure_with_katakana_or_katakana_and_kanji
- use_si_symbols
- use_unit_symbols
temperature_format:
type: string
description: Formatting options for Temperature Format
enum:
- spell_out_unit
- spell_out_unit_followed_by_numerals_then_korean_word_도
- use_arabic_numerals_followed_by_space_then_spell_out_unit
- use_arabic_numerals_followed_by_unit_symbol_without_space
- use_arabic_numerals_then_spell_out_unit
- use_chinese_numbers_then_spell_out_unit
- use_italian_word_grado_and_do_not_specify_temperature_scale
- use_numerals_followed_by_japanese_word_度_without_space
- use_numerals_followed_by_korean_word_도
- use_numerals_followed_by_space_then_spell_out_unit
- use_numerals_followed_by_space_then_unit_symbol
- use_numerals_followed_by_unit_symbol_without_space
- use_spanish_word_grado_and_do_not_specify_temperature_scale
thousands_separator:
type: string
description: Formatting options for Thousands Separator
enum:
- do_not_use
- do_not_use_thousands_separator
- use_comma
- use_comma_to_separate_large_numbers_into_units_of_three
- use_period
- use_period_as_thousands_separator
- use_space
- use_space_as_thousands_separator
- use_space_to_separate_large_numbers_into_units_of_three
- use_straight_apostrophe_as_thousands_separator
units_of_measure_spacing:
type: string
description: Formatting options for Units Of Measure Spacing
enum:
- do_not_use_space_between_numeral_and_unit_of_measure
- use_space_between_numeral_and_unit_of_measure
use_of_hiragana_and_kanji:
type: string
description: Formatting options for Use Of Hiragana And Kanji
enum:
- use_hiragana_japanese_word_か所_or_か月_when_using_arabic_numerals_in_horizontal_writing_but_use_kanji_japanese_word_箇所_or_箇月_when_using_kanji_numbers
writing_numbers:
type: string
description: Formatting options for Writing Numbers
enum:
- always_use_kanji_numbers
- use_arabic_numerals
- use_full_width_arabic_numerals_and_only_use_kanji_numbers_where_it_would_otherwise_sound_unnatural
- use_half_width_arabic_numerals_and_only_use_kanji_numbers_where_it_would_otherwise_sound_unnatural
zero_format:
type: string
description: Formatting options for Zero Format
enum:
- use_chinese_word_〇_for_numbering
- use_chinese_word_零_for_measurement
punctuation:
type: object
properties:
abbreviations:
type: string
description: Formatting options for Abbreviations
enum:
- do_not_separate_abbreviated_words
- separate_each_abbreviated_word_with_period_and_space
- separate_each_abbreviated_word_with_period_without_space
- separate_each_abbreviated_word_with_space_without_period
acronyms:
type: string
description: Formatting options for Acronyms
enum:
- do_not_use_periods
ampersand_abbreviation_spacing:
type: string
description: Formatting options for Ampersand Abbreviation Spacing
enum:
- do_not_use_spaces_before_and_after_ampersand_as_part_of_abbreviation
- use_spaces_before_and_after_ampersand_as_part_of_abbreviation
ampersand_usage:
type: string
description: Formatting options for Ampersand Usage
enum:
- use_english_word_and_except_in_company_names_common_abbreviations_titles_software_code_and_mathematical_equations
- use_full_width_ampersand
- use_german_word_und_except_in_company_names_common_abbreviations_titles_software_code_and_mathematical_equations
- use_half_width_ampersand
apostrophe:
type: string
description: Formatting options for Apostrophe
enum:
- use_curly_apostrophes
- use_straight_apostrophes
bracket:
type: string
description: Formatting options for Bracket
enum:
- use_hexagonal_brackets
- use_lenticular_brackets
- use_parentheses
- use_square_brackets_for_nationality_and_hexagonal_brackets_for_historical_period
chinese_mixed_with_english:
type: string
description: Formatting options for Chinese Mixed With English
enum:
- do_not_place_english_in_quotation_marks
- place_english_in_quotation_marks
colon:
type: string
description: Formatting options for Colon
enum:
- use_full_width_colon
- use_half_width_colon
colon_between_hours_and_minutes_or_chapters_and_verses:
type: string
description: Formatting options for Colon Between Hours And Minutes
Or Chapters And Verses
enum:
- do_not_use_space_before_or_after_colon
colon_in_heading:
type: string
description: Formatting options for Colon In Heading
enum:
- use_space_after_colon_not_before
colon_to_replace_versus_or_to:
type: string
description: Formatting options for Colon To Replace Versus Or To
enum:
- do_not_use_space_before_or_after_colon
comma_after_conjunctive_adverbs:
type: string
description: Formatting options for Comma After Conjunctive Adverbs
enum:
- do_not_use
- use
comma_after_i_e_and_e_g:
type: string
description: Formatting options for Comma After I E And E G
enum:
- do_not_use
- use
comma_after_short_introductory_phrase:
type: string
description: Formatting options for Comma After Short Introductory Phrase
enum:
- do_not_use
- use
comma_and_semicolon:
type: string
description: Formatting options for Comma And Semicolon
enum:
- use_comma_between_clauses
- use_semicolon_between_clauses
corner_bracket_and_periods:
type: string
description: Formatting options for Corner Bracket And Periods
enum:
- add_period_after_closing_corner_bracket_at_end_of_sentence
corner_brackets_and_periods:
type: string
description: Formatting options for Corner Brackets And Periods
enum:
- do_not_add_period_before_closing_corner_bracket_when_sentence_continues
dash:
type: string
description: Formatting options for Dash
enum:
- use_em_dash
- use_hyphen
- use_tilde
ellipsis:
type: string
description: Formatting options for Ellipsis
enum:
- use_ellipsis_character
- use_one_ellipsis_character
- use_six_dots_at_the_bottom
- use_six_dots_in_the_center
- use_three_dots_at_the_bottom
- use_three_dots_in_the_center
- use_three_ellipsis_characters
- use_three_periods
- use_three_periods_without_spaces
- use_three_spaced_periods
- use_two_ellipsis_characters
em_dash:
type: string
description: Formatting options for Em Dash
enum:
- use_double_em_dash
emphasis:
type: string
description: Formatting options for Emphasis
enum:
- use_double_corner_brackets
exclamation_marks:
type: string
description: Formatting options for Exclamation Marks
enum:
- do_not_use
explanatory_note_indicator:
type: string
description: Formatting options for Explanatory Note Indicator
enum:
- use_double_em_dash
- use_parentheses
full_sentence_in_round_brackets:
type: string
description: Formatting options for Full Sentence In Round Brackets
enum:
- add_period_before_closing_round_bracket
highlighting_specific_expressions:
type: string
description: Formatting options for Highlighting Specific Expressions
enum:
- use_single_curly_quotation_marks
- use_single_straight_quotation_marks
japanese_reference_materials:
type: string
description: Formatting options for Japanese Reference Materials
enum:
- use_double_corner_brackets
parentheses_for_supplementary_information:
type: string
description: Formatting options for Parentheses For Supplementary Information
enum:
- use_parentheses_without_space_on_either_side
passage_of_time_and_movement_between_locations:
type: string
description: Formatting options for Passage Of Time And Movement Between
Locations
enum:
- use_double_em_dash
periods_and_commas:
type: string
description: Formatting options for Periods And Commas
enum:
- use_full_width_japanese_periods_and_full_width_japanese_commas
- use_full_width_japanese_periods_and_full_width_non_japanese_commas
- use_full_width_non_japanese_periods_and_full_width_japanese_commas
- use_full_width_non_japanese_periods_and_full_width_non_japanese_commas
periods_in_academic_degrees:
type: string
description: Formatting options for Periods In Academic Degrees
enum:
- do_not_use
- use
periods_in_direct_quotes:
type: string
description: Formatting options for Periods In Direct Quotes
enum:
- do_not_use
- use
periods_in_uppercase_initialisms_and_acronyms:
type: string
description: Formatting options for Periods In Uppercase Initialisms
And Acronyms
enum:
- do_not_use
plus_sign_usage:
type: string
description: Formatting options for Plus Sign Usage
enum:
- do_not_use_plus_sign_to_symbolize_english_word_and_unless_it_is_part_of_a_proper_noun
possessives_of_proper_names_ending_in_s_style:
type: string
description: Formatting options for Possessives Of Proper Names Ending
In S Style
enum:
- add_apostrophe_only
- add_apostrophe_s
quotation_mark:
type: string
description: Formatting options for Quotation Mark
enum:
- use_curly_quotation_marks
- use_double_curly_quotation_marks
- use_double_straight_quotation_marks
- use_guillemets
- use_straight_quotation_marks
quotation_mark_and_apostrophe:
type: string
description: Formatting options for Quotation Mark And Apostrophe
enum:
- use_curly_quotation_marks_and_apostrophes
- use_double_and_single_curly_quotation_marks_and_curly_apostrophes
- use_double_and_single_straight_quotation_marks_and_straight_apostrophes
- use_guillemets_and_curly_apostrophes
- use_guillemets_and_straight_apostrophes
- use_straight_quotation_marks_and_apostrophes
quotation_style:
type: string
description: Formatting options for Quotation Style
enum:
- use_corner_brackets_for_primary_quotations_and_double_corner_brackets_for_secondary_quotations
- use_double_curly_quotation_marks_for_primary_quotations_and_single_curly_quotation_marks_for_secondary_quotations
- use_double_curly_quotation_marks_for_primary_quotations_then_alternate_with_single_curly_quotation_marks_for_nested_quotations
- use_double_german_quotation_marks_for_primary_quotations_and_single_german_quotation_marks_for_secondary_quotations
- use_double_quotation_marks_for_primary_quotations_and_single_quotation_marks_for_secondary_quotations
- use_double_straight_quotation_marks_for_primary_quotations_and_single_straight_quotation_marks_for_secondary_quotations
- use_double_straight_quotation_marks_for_primary_quotations_then_alternate_with_single_straight_quotation_marks_for_nested_quotations
- use_guillemets_for_primary_quotations_and_double_curly_quotation_marks_for_secondary_quotations
- use_guillemets_for_primary_quotations_and_double_straight_quotation_marks_for_secondary_quotations
- use_guillemets_for_primary_quotations_and_single_guillemets_for_secondary_quotations
- use_guillemets_for_primary_quotations_double_curly_quotation_marks_for_secondary_quotations_and_single_curly_quotation_marks_for_further_nested_quotations
- use_reversed_guillemets_for_primary_quotations_and_single_reversed_guillemets_for_secondary_quotations
- use_single_quotation_marks_for_primary_quotations_and_double_quotation_marks_for_secondary_quotations
range_indicator:
type: string
description: Formatting options for Range Indicator
enum:
- use_en_dash_with_spaces
- use_en_dash_without_space_on_either_side
- use_en_dash_without_spaces
- use_english_word_to
- use_full_width_dash
- use_full_width_wave_dash
- use_german_word_bis
- use_half_width_dash
- use_hyphen
- use_hyphen_with_space_on_either_side
- use_hyphen_with_spaces
- use_hyphen_without_space_on_either_side
- use_hyphen_without_spaces
- use_italian_words_da_a
- use_japanese_word_から
- use_korean_words_부터_까지
- use_spanish_words_de_a
- use_tilde
related_phrases_indicator:
type: string
description: Formatting options for Related Phrases Indicator
enum:
- use_comma
- use_hyphen
- use_middle_dot
round_brackets:
type: string
description: Formatting options for Round Brackets
enum:
- use_full_width_round_brackets
- use_half_width_round_brackets
salutation:
type: string
description: Formatting options for Salutation
enum:
- do_not_use_comma_after_salutation_capitalize_following_word
- use_colon_after_salutation
- use_comma_after_salutation
- use_exclamation_mark_after_salutation
sentence_break_indicator:
type: string
description: Formatting options for Sentence Break Indicator
enum:
- use_em_dash_with_space_on_either_side
- use_em_dash_without_space_on_either_side
- use_en_dash_with_space_on_either_side
serial_comma:
type: string
description: Formatting options for Serial Comma
enum:
- do_not_use
- do_not_use_serial_comma_when_using_chinese_comma
- use
- use_serial_comma_when_using_comma
setting_off_non_quoted_phrases:
type: string
description: Formatting options for Setting Off Non Quoted Phrases
enum:
- use_full_width_quotation_marks
- use_half_width_quotation_marks
slash:
type: string
description: Formatting options for Slash
enum:
- do_not_use_spaces_before_and_after_slashes
- use_spaces_before_and_after_slashes
- use_spaces_before_and_after_slashes_if_there_are_multiple_words_before_and_after_slash
- use_spaces_before_and_after_slashes_if_there_are_multiple_words_before_or_after_slash
slash_usage:
type: string
description: Formatting options for Slash Usage
enum:
- do_not_use_slash_to_symbolize_english_word_or
spacing_and_punctuation:
type: string
description: Formatting options for Spacing And Punctuation
enum:
- do_not_use_space
- use_regular_space
text_in_round_brackets_referring_to_previous_sentence:
type: string
description: Formatting options for Text In Round Brackets Referring
To Previous Sentence
enum:
- add_period_after_closing_round_bracket
- add_period_before_closing_round_bracket
text_in_round_brackets_supplementing_preceding_text:
type: string
description: Formatting options for Text In Round Brackets Supplementing
Preceding Text
enum:
- add_period_after_closing_round_bracket
titles_of_books_and_newspapers:
type: string
description: Formatting options for Titles Of Books And Newspapers
enum:
- use_double_angle_brackets
- use_double_corner_brackets
- use_double_straight_quotation_marks
titles_of_creative_works_trade_names_laws_and_regulations:
type: string
description: Formatting options for Titles Of Creative Works Trade Names
Laws And Regulations
enum:
- use_single_angle_brackets
- use_single_corner_brackets
- use_single_straight_quotation_marks
uppercase_acronyms:
type: string
description: Formatting options for Uppercase Acronyms
enum:
- do_not_use_spaces
- use_spaces
spelling_and_grammar:
type: object
properties:
abbreviating_french_word_numero:
type: string
description: Formatting options for Abbreviating French Word Numero
enum:
- abbreviate_as_n_then_degree_symbol
- abbreviate_as_n_then_o_in_superscript
- abbreviate_as_no
abbreviation_usage:
type: string
description: Formatting options for Abbreviation Usage
enum:
- do_not_use_abbreviations
- do_not_use_abbreviations_unless_necessary
- use_abbreviations
- use_abbreviations_as_needed
accents_and_cedillas:
type: string
description: Formatting options for Accents And Cedillas
enum:
- do_not_use_on_capital_letters
- never_use
- use_even_on_capital_letters
accents_in_verbs_conjugated_like_french_word_céder:
type: string
description: Formatting options for Accents In Verbs Conjugated Like
French Word Céder
enum:
- use_acute_accent
- use_grave_accent
accents_with_subject_verb_inversion:
type: string
description: Formatting options for Accents With Subject Verb Inversion
enum:
- use_acute_accent
- use_grave_accent
active_passive_voice:
type: string
description: Formatting options for Active Passive Voice
enum:
- use_active_voice_if_subject_is_prominent_and_agent_is_clear
- use_active_voice_to_describe_operations_with_user_as_subject
- use_active_voice_unless_agent_is_unknown_or_irrelevant
- use_passive_voice_as_needed
- use_passive_voice_for_automatic_operations_from_user_perspective
- use_passive_voice_if_agent_is_unknown_or_irrelevant
all_caps:
type: string
description: Formatting options for All Caps
enum:
- do_not_use_all_caps_except_for_acronyms_initialisms_or_proper_nouns
- do_not_use_all_caps_except_for_acronyms_or_brand_names
complete_sentences:
type: string
description: Formatting options for Complete Sentences
enum:
- always_write_complete_sentences
compound_nouns:
type: string
description: Formatting options for Compound Nouns
enum:
- write_as_one_word
- write_with_hyphen
conjunctions:
type: string
description: Formatting options for Conjunctions
enum:
- never_start_sentence_with_coordinating_conjunction
contractions:
type: string
description: Formatting options for Contractions
enum:
- do_not_use_contractions
- use_contractions
- use_contractions_but_avoid_negative_contractions
email_address_website_url:
type: string
description: Formatting options for Email Address Website Url
enum:
- use_lowercase_for_email_addresses_and_website_urls_except_when_url_includes_case_sensitive_elements
established_loanwords:
type: string
description: Formatting options for Established Loanwords
enum:
- use_as_is
- use_native_or_sino_korean_equivalents
eszett:
type: string
description: Formatting options for Eszett
enum:
- replace_eszett_with_ss
foreign_word_translation:
type: string
description: Formatting options for Foreign Word Translation
enum:
- use_equivalent_expressions_in_chinese
- use_foreign_forms_or_abbreviations_for_technical_terms_or_brand_names
- use_literal_translation
- use_localized_names_for_brands_with_official_chinese_translations
- use_mixture_of_transliteration_and_translation
- use_transliteration
french_verbs_ending_in_eler_and_eter:
type: string
description: Formatting options for French Verbs Ending In Eler And
Eter
enum:
- transcribe_open_e_sound_by_doubling_next_consonant
- transcribe_open_e_sound_with_grave_accent
i_and_u_with_circumflex_accents:
type: string
description: Formatting options for I And U With Circumflex Accents
enum:
- do_not_use_circumflex_accents_except_in_verbs_and_to_distinguish_homophones
- use_circumflex_accents
informal_address_pronouns:
type: string
description: Formatting options for Informal Address Pronouns
enum:
- capitalize_informal_address_pronouns
- do_not_capitalize_informal_address_pronouns
latin_abbreviations:
type: string
description: Formatting options for Latin Abbreviations
enum:
- do_not_use_latin_abbreviations
passive_voice:
type: string
description: Formatting options for Passive Voice
enum:
- avoid_passive_voice_when_agent_is_known
past_participle_of_french_word_laisser_followed_by_infinitive:
type: string
description: Formatting options for Past Participle Of French Word Laisser
Followed By Infinitive
enum:
- make_french_word_laisser_agree_with_direct_object_complement_if_it_appears_before_verb
- use_invariable_form_french_word_laissé
personal_titles:
type: string
description: Formatting options for Personal Titles
enum:
- abbreviate
- do_not_abbreviate
pluralizing_foreign_words:
type: string
description: Formatting options for Pluralizing Foreign Words
enum:
- use_french_spelling_rules
- use_original_language_spelling
quotation_modification:
type: string
description: Formatting options for Quotation Modification
enum:
- do_not_modify_text_in_quotation_marks
- modify_text_in_quotation_marks_according_to_custom_rules
spanish_word_solo:
type: string
description: Formatting options for Spanish Word Solo
enum:
- never_use_acute_accent
- use_acute_accent_when_used_as_adverb
special_characters:
type: string
description: Formatting options for Special Characters
enum:
- never_use_symbols
spelled_out_numbers:
type: string
description: Formatting options for Spelled Out Numbers
enum:
- use_hyphens
- use_hyphens_between_elements_under_100_and_not_separated_by_french_word_et
umlauts:
type: string
description: Formatting options for Umlauts
enum:
- replace_umlauts_with_ae_oe_ue
unestablished_loanwords:
type: string
description: Formatting options for Unestablished Loanwords
enum:
- paraphrase_in_korean
- use_as_is
- use_as_is_with_explanation_in_parentheses
style_and_tone:
type: object
properties:
abbreviations:
type: string
description: Formatting options for Abbreviations
enum:
- avoid_abbreviations_and_symbols_that_can_be_spelled_out_easily
- use_abbreviations_and_symbols
addressing_non_binary_people:
type: string
description: Formatting options for Addressing Non Binary People
enum:
- use_spanish_word_elle
- use_spanish_word_ellx
addressing_the_reader:
type: string
description: Formatting options for Addressing The Reader
enum:
- use_formal_french_word_vous
- use_formal_italian_word_lei
- use_informal_french_word_tu
- use_informal_italian_word_tu
anglicisms:
type: string
description: Formatting options for Anglicisms
enum:
- avoid_anglicisms_when_there_is_a_french_equivalent
binary_representation_of_gender:
type: string
description: Formatting options for Binary Representation Of Gender
enum:
- avoid_binary_representation_of_gender_when_gender_neutral_language_can_be_used
- replace_binary_representations_of_gender_with_gender_neutral_language
- use_neutral_pronouns
call_to_action:
type: string
description: Formatting options for Call To Action
enum:
- use_calls_to_action
complex_sentences:
type: string
description: Formatting options for Complex Sentences
enum:
- avoid_unnecessarily_complex_sentences
country_names:
type: string
description: Formatting options for Country Names
enum:
- use_long_form
- use_short_form
declarative_endings:
type: string
description: Formatting options for Declarative Endings
enum:
- mix_hapsho_and_haeyo_styles
- use_hae_style
- use_haeyo_style
- use_hapsho_style
- use_hara_style
default_first_person_pronoun:
type: string
description: Formatting options for Default First Person Pronoun
enum:
- do_not_use_first_person_pronouns
- omit_first_person_subject_when_clear_from_context
- use_first_person_pronouns
default_second_person_pronoun:
type: string
description: Formatting options for Default Second Person Pronoun
enum:
- do_not_use_second_person_pronouns
- use_second_person_pronouns
default_third_person_singular_pronoun:
type: string
description: Formatting options for Default Third Person Singular Pronoun
enum:
- use_feminine_pronoun
- use_he_him
- use_he_or_she_him_or_her
- use_masculine_pronoun
- use_masculine_pronoun_german_word_oder_feminine_pronoun
- use_she_her
- use_they_them
directional_language:
type: string
description: Formatting options for Directional Language
enum:
- do_not_use_directional_language
double_negatives:
type: string
description: Formatting options for Double Negatives
enum:
- do_not_use_double_negatives
- use_double_negatives
formality:
type: string
description: Formatting options for Formality
enum:
- use_casual_tone
- use_formal_tone
gender_neutral_language_readability:
type: string
description: Formatting options for Gender Neutral Language Readability
enum:
- use_generic_masculine_for_common_compound_nouns_if_it_increases_readability
gender_unspecified:
type: string
description: Formatting options for Gender Unspecified
enum:
- use_both_masculine_and_feminine_forms
- use_gender_neutral_terms
- use_masculine_form_only
- use_middle_dots
- use_parentheses
- use_periods
gender_unspecified_or_mixed:
type: string
description: Formatting options for Gender Unspecified Or Mixed
enum:
- use_both_feminine_and_masculine_forms
- use_feminine_form_only
- use_inclusive_nouns_and_adjectives
- use_masculine_form_only
- use_neutral_nouns_and_adjectives
idioms_colloquialisms_and_culture_specific_references:
type: string
description: Formatting options for Idioms Colloquialisms And Culture
Specific References
enum:
- do_not_use
inflected_words_masculine_noun_agreement:
type: string
description: Formatting options for Inflected Words Masculine Noun Agreement
enum:
- place_masculine_nouns_closest_to_inflected_words
instructions_style:
type: string
description: Formatting options for Instructions Style
enum:
- use_imperative
- use_indicative
- use_infinitive
- use_modal_verbs
- use_passive_voice
mixing_styles:
type: string
description: Formatting options for Mixing Styles
enum:
- do_not_mix_desu_masu_style_and_dearu_style
modal_verbs:
type: string
description: Formatting options for Modal Verbs
enum:
- avoid_modal_verbs
person_vs_identity_first_language:
type: string
description: Formatting options for Person Vs Identity First Language
enum:
- use_identity_first_language
- use_person_first_language
personal_vs_impersonal_style:
type: string
description: Formatting options for Personal Vs Impersonal Style
enum:
- use_impersonal_style
- use_personal_style
positive_vs_negative_language:
type: string
description: Formatting options for Positive Vs Negative Language
enum:
- use_positive_language
proximity_agreement:
type: string
description: Formatting options for Proximity Agreement
enum:
- use
reader_action_required:
type: string
description: Formatting options for Reader Action Required
enum:
- use_you_must_when_action_is_required_from_reader
redundant_introductory_phrases:
type: string
description: Formatting options for Redundant Introductory Phrases
enum:
- avoid_redundant_introductory_phrases
- do_not_use_redundant_phrases_that_refer_to_current_text
redundant_phrases:
type: string
description: Formatting options for Redundant Phrases
enum:
- avoid_relativizing_and_redundant_phrases
- do_not_use_redundant_phrases
referring_to_non_binary_people:
type: string
description: Formatting options for Referring To Non Binary People
enum:
- use_the_singular_and_plural_schwa
short_vs_long_words:
type: string
description: Formatting options for Short Vs Long Words
enum:
- use_short_words
simple_words_and_sentences:
type: string
description: Formatting options for Simple Words And Sentences
enum:
- use_simple_words_and_sentences_avoid_hard_to_translate_words_and_figures_of_speech
specialized_language:
type: string
description: Formatting options for Specialized Language
enum:
- avoid_specialized_language_unless_text_is_aimed_at_experts
text_position_references:
type: string
description: Formatting options for Text Position References
enum:
- avoid_directional_terms_as_only_reference_to_position_in_text_specify_exact_position_instead
tone:
type: string
description: Formatting options for Tone
enum:
- use_dearu_style_to_give_impression_content_is_accurate_and_rigorous_or_to_convey_sense_of_confidence_and_reliability
- use_desu_masu_style_to_give_impression_content_is_plain_and_straightforward_or_to_give_reader_reassuring_or_soft_impression
verbal_vs_nominal_style:
type: string
description: Formatting options for Verbal Vs Nominal Style
enum:
- use_nominal_style
- use_verbal_style
vocabulary:
type: object
properties:
abbreviations:
type: string
description: Formatting options for Abbreviations
enum:
- write_original_term_then_abbreviation_and_explanation
loanwords:
type: string
description: Formatting options for Loanwords
enum:
- add_explanation_to_loanword_if_difficult_to_rephrase
- rephrase_loanword_in_daily_use_chinese_or_japanese_words_if_possible
- rephrase_loanword_with_another_expression_if_not_established
- use_loanword_as_is_if_well_established
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'
CustomInstruction:
description: All enabled custom instructions for the style rule list
type: object
properties:
label:
type: string
description: Name associated with the custom instruction
example: "Currency custom instruction"
prompt:
type: string
description: Prompt of the custom instruction
example: "Have currency symbols before the numerical value (e.g. $100, €100)"
source_language:
type: string
description: Optional source language of the custom instruction
example: "en"
StyleRuleList:
type: object
required:
- style_id
- name
- creation_time
- updated_time
- language
- version
properties:
style_id:
$ref: '#/components/schemas/StyleId'
name:
$ref: '#/components/schemas/StyleRuleName'
creation_time:
description: 'The creation time of the style rule in the ISO 8601-1:2019 format
(e.g.: `2021-08-03T14:16:18.329Z`).'
type: string
format: date-time
updated_time:
description: 'The time of the style rule when it was last updated in the ISO 8601-1:2019 format
(e.g.: `2022-08-03T14:16:18.329Z`).'
type: string
format: date-time
language:
$ref: '#/components/schemas/StyleRuleLanguage'
version:
description: The version of the style rule. Incremented when the style rule is updated.
type: integer
example: 13
configured_rules:
type: array
description: |-
List of configured rules enabled for the style rule list.
items:
$ref: '#/components/schemas/ConfiguredRules'
custom_instructions:
type: array
description: |-
List of custom instructions enabled for the style rule list.
items:
$ref: '#/components/schemas/CustomInstruction'
StyleId:
type: string
description: A unique ID assigned to a style rule.
example: "bd0a38f3-1831-440b-a8dd-2c702e2325ab"
StyleRuleLanguage:
description: The language that the style rules are applied to.
type: string
enum:
- de
- en
- es
- fr
- it
- ja
- ko
- zh
StyleRuleName:
description: Name associated with the style rule.
type: string
DocumentTranslationError:
responses:
BadRequest:
description: Bad request. Please check error message and your parameters.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
BadRequestGlossaries:
description: Bad request. Please check error message and your parameters.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
Forbidden:
description: Authorization failed. Please supply a valid `DeepL-Auth-Key` via
the `Authorization` header.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
ForbiddenGlossaries:
description: Forbidden. The access to the requested resource is denied, because
of insufficient access rights.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
NotFound:
description: The requested resource could not be found.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
UnsupportedMediaTypeGlossaries:
description: The requested entries format specified in the `Accept` header is
not supported.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
TooManyRequests:
description: Too many requests. Please wait and resend your request.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
QuotaExceeded:
description: Quota exceeded. The character limit has been reached.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
QuotaExceededGlossaries:
description: Quota exceeded. The glossary creation limit has been reached.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
InternalServerError:
description: Internal error.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
ServiceUnavailable:
description: Resource currently unavailable. Try again later.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
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
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
ApiKeyUsageSpeechToTextMilliseconds:
description: |
Restricts the number of milliseconds of speech-to-text 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 speech-to-text milliseconds.
Setting the limit to `null` disables the limit, effectively allowing unlimited usage.
type: number
example: 3600000
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'
speech_to_text_milliseconds:
$ref: '#/components/schemas/ApiKeyUsageSpeechToTextMilliseconds'
Context:
description: |-
The `context` parameter makes it possible to include additional context that can influence a translation but is not translated itself.
This additional context can potentially improve translation quality when translating short, low-context source texts such
as product names on an e-commerce website, article headlines on a news website, or UI elements.
For example...
- When translating a product name, you might pass the product description as context.
- When translating a news article headline, you might pass the first few sentences or a summary of the article as context.
For best results, we recommend sending a few complete sentences of context in the same language as the source text.
There is no size limit for the `context` parameter itself, but the request body size limit of 128 KiB still applies to
all text translation requests.
If you send a request with multiple `text` parameters, the `context` parameter will be applied to each one.
Characters included in the `context` parameter will not be counted toward billing (i.e. there is no additional
cost for using the `context` parameter, and only characters sent in the text parameter(s) will be counted toward
billing for text translation even when the `context` parameter is included in a request).
type: string
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'
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://www.deepl.com/docs-api/glossaries/formats) for details about each format.
type: string
enum:
- tsv
- csv
example: tsv
default: tsv
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 currently only works for target languages
`DE` (German),
`FR` (French),
`IT` (Italian),
`ES` (Spanish),
`ES-419` (Latin American Spanish),
`NL` (Dutch),
`PL` (Polish),
`PT-BR` and `PT-PT` (Portuguese),
`JA` (Japanese),
and `RU` (Russian).
Learn more about the plain/polite feature for Japanese [here](https://support.deepl.com/hc/en-us/articles/6306700061852-About-the-plain-polite-feature-in-Japanese).
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
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.
Possible values are:
* `latency_optimized` (default) - uses lower latency “classic” translation models, which support all language pairs;
default value
* `quality_optimized` - uses higher latency, improved quality “next-gen” translation models, which support only a
subset of language pairs; if a language pair that is not supported by next-gen models is included in the
request, it will fail. Consider using prefer_quality_optimized instead.
* `prefer_quality_optimized` - prioritizes use of higher latency, improved quality “next-gen” translation models,
which support only a subset of DeepL languages; if a request includes a language pair not supported by
next-gen models, the request will fall back to latency_optimized classic models.
enum:
- quality_optimized
- prefer_quality_optimized
- latency_optimized
MonolingualGlossary:
type: object
properties:
glossary_id:
$ref: '#/components/schemas/GlossaryId'
name:
$ref: '#/components/schemas/GlossaryName'
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:
$ref: '#/components/schemas/GlossaryEntryCount'
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: |-
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 `false` 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.
Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
type: boolean
default: true
OutlineDetectionOptionStr:
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'
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.
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
Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
type: boolean
default: false
PreserveFormattingOptionStr:
description: |-
Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. Possible values are:
* `0` (default)
* `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'
PutMultilingualGlossaryParameters:
$ref: '#/components/schemas/MultilingualGlossaryEntries'
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.
Note: for requests sent as URL-encoded forms, boolean values should be specified as "1" or "0".
type: boolean
SplitSentencesOption:
description: |-
Sets whether the translation engine should first split the input into sentences. For text translations where
`tag_handling` is not set to `html`, the default value is `1`, meaning the engine splits on punctuation and on newlines.
For text translations where `tag_handling=html`, the default value is `nonewlines`, meaning the engine splits on punctuation only, ignoring newlines.
The use of `nonewlines` as the default value for text translations where `tag_handling=html` is new behavior that was implemented in November 2022,
when HTML handling was moved out of beta.
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
For applications that send one sentence per text parameter, we recommend setting `split_sentences` to `0`, in order to prevent the engine from splitting the sentence unintentionally.
Please note that newlines will split sentences when `split_sentences=1`. We recommend cleaning files so they don't contain breaking sentences or setting the parameter `split_sentences` to `nonewlines`.
type: string
enum:
- '0'
- '1'
- nonewlines
default: '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.
**Note:** Some languages only work with `model_type` set to `quality_optimized`. See [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for more details.
enum:
- ACE
- AF
- AN
- AR
- AS
- AY
- AZ
- BA
- BE
- BG
- BHO
- BN
- BR
- BS
- CA
- CEB
- CKB
- CS
- CY
- DA
- DE
- EL
- EN
- EO
- ES
- ET
- EU
- FA
- FI
- FR
- GA
- GL
- GN
- GOM
- GU
- HA
- HE
- HI
- HR
- HT
- HU
- HY
- ID
- IG
- IS
- IT
- JA
- JV
- KA
- KK
- KMR
- KO
- KY
- LA
- LB
- LMO
- LN
- LT
- LV
- MAI
- MG
- MI
- MK
- ML
- MN
- MR
- MS
- MT
- MY
- NB
- NE
- NL
- OC
- OM
- PA
- PAG
- PAM
- PL
- PRS
- PS
- PT
- QU
- RO
- RU
- SA
- SCN
- SK
- SL
- SQ
- SR
- ST
- SU
- SV
- SW
- TA
- TE
- TG
- TH
- TK
- TL
- TN
- TR
- TS
- TT
- UK
- UR
- UZ
- VI
- WO
- XH
- YI
- YUE
- ZH
- ZU
example: EN
TagHandlingOption:
description: |-
Sets which kind of tags should be handled. Options currently available:
* `xml`: Enable XML tag handling; see [XML Handling](https://www.deepl.com/docs-api/xml).
* `html`: Enable HTML tag handling; see [HTML Handling](https://www.deepl.com/docs-api/html).
type: string
enum:
- xml
- html
TagHandlingVersionOption:
description: |-
Sets which version of the tag handling algorithm should be used. Options currently available:
* `v2`: Improved algorithm released in October 2025 (default as of December 2025).
* `v1`: Traditional algorithm (default until December 2025).
type: string
enum:
- v1
- v2
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
billing_unit:
type: string
enum:
- characters
- milliseconds
description: The billing unit for this product type.
example: characters
api_key_unit_count:
type: integer
description: Units used for this product by this API key in the current period.
example: 0
account_unit_count:
type: integer
description: Total units used for this product by the account in the current period.
example: 5643
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
speech_to_text_milliseconds_count:
type: integer
description: Only present for API Pro users. Milliseconds of speech-to-text used in the current period.
example: 1800000
speech_to_text_milliseconds_limit:
type: integer
description: Only present for API Pro users. Milliseconds of speech-to-text limit in the current period.
example: 36000000
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'
NonSplittingTagCommaSeparatedList:
allOf:
- $ref: '#/components/schemas/TagCommaSeparatedList'
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).
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.
Use this parameter 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.
```
IgnoreTagList:
allOf:
- $ref: '#/components/schemas/TagList'
description: |-
List of XML tags that indicate text not to be translated.
Use this parameter 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.
```
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.
**Note:** Some languages only work with `model_type` set to `quality_optimized`. See [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for more details.
enum:
- ACE
- AF
- AN
- AR
- AS
- AY
- AZ
- BA
- BE
- BG
- BHO
- BN
- BR
- BS
- CA
- CEB
- CKB
- CS
- CY
- DA
- DE
- EL
- EN
- EN-GB
- EN-US
- EO
- ES
- ES-419
- ET
- EU
- FA
- FI
- FR
- GA
- GL
- GN
- GOM
- GU
- HA
- HE
- HI
- HR
- HT
- HU
- HY
- ID
- IG
- IS
- IT
- JA
- JV
- KA
- KK
- KMR
- KO
- KY
- LA
- LB
- LMO
- LN
- LT
- LV
- MAI
- MG
- MI
- MK
- ML
- MN
- MR
- MS
- MT
- MY
- NB
- NE
- NL
- OC
- OM
- PA
- PAG
- PAM
- PL
- PRS
- PS
- PT
- PT-BR
- PT-PT
- QU
- RO
- RU
- SA
- SCN
- SK
- SL
- SQ
- SR
- ST
- SU
- SV
- SW
- TA
- TE
- TG
- TH
- TK
- TL
- TN
- TR
- TS
- TT
- UK
- UR
- UZ
- VI
- WO
- XH
- YI
- YUE
- ZH
- ZH-HANS
- ZH-HANT
- ZU
example: DE
TargetLanguageWrite:
type: string
description: |-
The language for the text improvement. Options currently available:
* `de` - German
* `en` - English (unspecified variant, defaults to `en-US`)
* `en-GB` - English (British)
* `en-US` - English (American)
* `es` - Spanish
* `fr` - French
* `it` - Italian
* `pt` - Portuguese (unspecified variant, defaults to `pt-PT`)
* `pt-BR` - Portuguese (Brazilian)
* `pt-PT` - Portuguese (all Portuguese variants excluding Brazilian Portuguese)
enum:
- de
- en
- en-GB
- en-US
- fr
- it
- pt
- pt-BR
- pt-PT
example: de
VoiceFormality:
description: |-
Sets whether the translated text should lean towards formal or informal language.
Possible options are:
* `default` - use the default formality for the target language
* `formal`/`more` - for a more formal language
* `informal`/`less` - for a more informal language
type: string
enum:
- default
- formal
- more
- informal
- less
default: default
example: formal
VoiceMediaContentType:
type: string
description: |-
The audio format for streaming. Specifies container, codec, and encoding parameters.
Supported formats include PCM (recommended), OPUS (recommended for low bandwidth), FLAC, MP3, and AAC.
PCM formats require explicit sample rate. Mono audio only.
enum:
- audio/auto
- audio/flac
- audio/mpeg
- audio/ogg
- audio/webm
- audio/x-matroska
- audio/ogg; codecs=flac
- audio/ogg; codecs=opus
- audio/pcm; encoding=s16le; rate=8000
- audio/pcm; encoding=s16le; rate=16000
- audio/pcm; encoding=s16le; rate=44100
- audio/pcm; encoding=s16le; rate=48000
- audio/webm; codecs=opus
- audio/x-matroska; codecs=aac
- audio/x-matroska; codecs=flac
- audio/x-matroska; codecs=mp3
- audio/x-matroska; codecs=opus
example: audio/ogg; codecs=opus
VoiceSourceLanguage:
type: string
description: |-
Source language of the audio stream. Must be one of the supported Voice API source languages.
Language identifier must comply with IETF BCP 47 language tags.
enum:
- zh
- nl
- en
- fr
- de
- id
- it
- ja
- ko
- pl
- pt
- ro
- ru
- es
- sv
- tr
- uk
example: en
VoiceSourceLanguageMode:
type: string
description: |-
Controls how the source_language value is used.
- `auto`: Treats source language as a hint; server can override
- `fixed`: Treats source language as mandatory; server must use this language
enum:
- auto
- fixed
default: auto
example: auto
VoiceStreamingResponse:
type: object
required:
- streaming_url
- token
properties:
streaming_url:
type: string
description: The WebSocket URL to use for establishing the streaming connection. This URL is ephemeral and valid for one-time use only.
example: wss://api.deepl.com/v3/voice/realtime/connect
token:
type: string
description: A unique ephemeral token for authentication with the streaming endpoint. Pass this as a query parameter when connecting to the WebSocket URL.
example: VGhpcyBpcyBhIGZha2UgdG9rZW4K
session_id:
type: string
description: Internal use only. A unique identifier for the requested stream.
example: 4f911080-cfe2-41d4-8269-0e6ec15a0354
VoiceTargetLanguages:
type: array
description: |-
List of target languages for translation. The stream will emit translations for each language.
Maximum 5 target languages per stream. Language identifiers must comply with IETF BCP 47.
items:
type: string
maxItems: 5
example: ['de', 'fr', 'es']
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
AdminUsageReport:
type: object
description: The response for admin usage statistics.
properties:
usage_report:
$ref: '#/components/schemas/AdminUsageReportData'
AdminUsageReportData:
type: object
description: Contains the detailed usage statistics for the specified date range.
properties:
total_usage:
$ref: '#/components/schemas/UsageBreakdown'
start_date:
type: string
format: date-time
description: Start date of the usage report period.
example: "2025-09-29T00:00:00"
end_date:
type: string
format: date-time
description: End date of the usage report period.
example: "2025-10-01T00:00:00"
group_by:
type: string
description: The grouping method used, if any.
enum:
- key
- key_and_day
example: "key_and_day"
key_usages:
type: array
description: Usage statistics grouped by key. Present when group_by='key'.
items:
$ref: '#/components/schemas/KeyUsageItem'
key_and_day_usages:
type: array
description: Usage statistics grouped by key and day. Present when group_by='key_and_day'.
items:
$ref: '#/components/schemas/KeyAndDayUsageItem'
UsageBreakdown:
type: object
description: Breakdown of character usage by category.
properties:
total_characters:
type: integer
description: Total number of characters used.
example: 9619
text_translation_characters:
type: integer
description: Number of characters used for text translation.
example: 4892
document_translation_characters:
type: integer
description: Number of characters used for document translation.
example: 0
text_improvement_characters:
type: integer
description: Number of characters used for text improvement.
example: 4727
speech_to_text_milliseconds:
type: integer
description: Duration of speech-to-text usage in milliseconds.
example: 1800000
KeyUsageItem:
type: object
description: Usage statistics for a specific API key (without date grouping).
properties:
api_key:
type: string
description: Masked API key identifier.
example: "db96****cb2c"
api_key_label:
type: string
description: Label associated with the API key.
example: "DeepL API Key Prod"
usage:
$ref: '#/components/schemas/UsageBreakdown'
KeyAndDayUsageItem:
type: object
description: Usage statistics for a specific API key and specific date.
properties:
api_key:
type: string
description: Masked API key identifier.
example: "db96****cb2c"
api_key_label:
type: string
description: Label associated with the API key.
example: "DeepL API Key Prod"
usage_date:
type: string
format: date-time
description: The usage date when group_by is "key_and_day".
example: "2025-09-29T00:00:00Z"
usage:
$ref: '#/components/schemas/UsageBreakdown'