> ## Documentation Index > Fetch the complete documentation index at: https://developers.deepl.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints. > Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication). > Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key `. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart. > Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid. # Poll for the evaluation result > Poll a document's quality evaluation for its status and retrieve the per-segment report of translation issues once it completes. Quality evaluation is in [beta](/docs/resources/alpha-and-beta-features) and available to select DeepL customers only. To request access, contact your customer success manager. Evaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document), which returns a `quality_evaluation_job_id`. That is the unique ID of the evaluation, and the value this endpoint takes. There is no public endpoint for starting an evaluation. For the end-to-end flow, see [Requesting a quality evaluation](/docs/best-practices/document-translations#requesting-a-quality-evaluation). Evaluations resolve only within the account that requested them. A job ID belonging to another account returns `404`, the same response as an unknown ID. ## Status values | **Value** | **HTTP status** | **Response body** | | ------------ | --------------- | ------------------------------------------------------------------------------------------------------------------ | | `processing` | `202` | `job_id` and `status` only. The `Retry-After` header carries the suggested number of seconds before the next poll. | | `done` | `200` | The full report in `segments`. | | `error` | `200` | An `error` object. The evaluation produced no report and will not produce one later. | A completed evaluation and a failed one both return `200`, so `status` rather than the HTTP status code distinguishes them. A malformed `job_id` returns `400` without reaching an evaluation. `error.code` is currently always `evaluation_failed`, so the response does not distinguish one cause of failure from another. ## Segment text A report carries one entry in `segments` per evaluated segment of the document, in reading order, including segments where no issue was found. On those, `errors` is an empty array. `segment_index` is that reading-order position. It is not a durable handle: re-translating the same document can produce a different segmentation. `segment_score` rates the translation quality of that segment from 0 (lowest) to 100 (highest). It is always present in a completed report. `source` and `target` hold the segment text as the evaluation read it, which is DeepL's own segmentation of the document with inline formatting tags removed. This text does not byte-match the text in the uploaded or translated file, and segment boundaries do not necessarily correspond to the paragraphs or sentences in the document. Span offsets index these two strings, not the uploaded or translated file. Both fields are omitted when the text is unavailable for a segment. An issue on such a segment still carries its spans, but there is no text in the response to resolve them against. `applied_glossary_term_pairs` lists the glossary term pairs applied to a segment when the document was translated. It is omitted for segments where no glossary term pair was applied. Each item gives the `source_term`, `target_term`, and the spans in `target` where the target term was applied. ## Span ranges Each span describes a half-open interval over the segment's source or target text. `start` is the index of the first Unicode code point in the span; `end` is one past the last. The span covers the substring `text[start:end]` in Python-style slicing, and its length is `end - start`. For example: ```text theme={null} target: Unser Q3-Umsatz lag 5 % unter der Prognose. ``` A target span of `{ "start": 20, "end": 29 }` covers `target[20:29]`, the 9 code points `"5 % unter"`. Offsets count code points, not UTF-16 code units, so a language whose characters fall outside the Basic Multilingual Plane indexes differently than a UTF-16 string length would suggest. * `source_spans` and `target_spans` are always present on an issue. If no span applies to that side, the value is an empty array * Within a single issue, the ranges in `source_spans` (and in `target_spans`) are sorted by `start` and do not overlap * Different issues may cover the same part of a segment * `ranges` on an applied glossary term pair follows the same convention and indexes into `target` ## Severity values The `severity` field on an issue takes one of three values. | **Value** | **Description** | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Critical` | Renders the content unusable or significantly changes its meaning. For example, the meaning is reversed, important information is missing, or the content is unsuitable for the intended audience. | | `Major` | Misleads the reader or significantly alters the meaning. The general idea is clear, but specific details are wrong, terminology is incorrect, or grammar issues make the text hard to understand. | | `Minor` | Does not make the text unreadable, but can make it harder to understand and less appealing. | ## Type and sub-type values Every issue carries a `type`, the top-level category, and a `sub_type`, which narrows it within that type. The five types and their sub-types are listed below. New values for `type`, `sub_type`, and `severity` may be added without warning. | **type** | **sub\_type** | **Description** | | ------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Accuracy` | `Addition` | The target includes text that was not part of the source. | | `Accuracy` | `Omission` | Content from the source is missing from the target. | | `Accuracy` | `Mistranslation` | The content from the target doesn't match the content of the source. | | `Accuracy` | `Over-translation` | The target is more specific than the source. | | `Accuracy` | `Under-translation` | The target is less specific than the source. | | `Accuracy` | `Untranslated text` | Content that should have been translated has been left untranslated. | | `Fluency` | `Punctuation` | Punctuation is used incorrectly. | | `Fluency` | `Spelling` | Incorrect spelling in the target text. | | `Fluency` | `Grammar` | Issues with the grammar or syntax of the text, other than spelling and orthography. | | `Fluency` | `Grammatical register` | The text uses the wrong grammatical register, such as informal forms where formal is required. | | `Fluency` | `Inconsistency` | The text is not internally consistent. For example, using two different abbreviations for the same term. | | `Fluency` | `Character encoding` | Characters are garbled due to incorrect application of an encoding. | | `Style` | `Awkward` | The text is written in an awkward style. | | `Style` | `Inconsistent style` | The text uses inconsistent stylistic conventions across sections. | | `Miscellaneous` | Not enumerated | An error that does not fall into the other categories but is nonetheless clearly identifiable as a mistake. The sub-types of this type are not a fixed set, so read `sub_type` as free text. | | `InternalTQEError` | `SegmentTooLarge` | The segment's source and target exceed 10,000 characters combined, so it was not analyzed. Reported with severity `Critical`. | An issue of this type reports that a segment could not be evaluated rather than a defect in the translation. The rest of the document is evaluated normally. ## Supported language pairs | **Source language** | **Target languages** | | ------------------- | ---------------------------------------------------------------------------------------------------------- | | German (`DE`) | English (`EN-GB`, `EN-US`) | | English (`EN`) | German (`DE`), Spanish (`ES`, `ES-419`), French (`FR`), Italian (`IT`), Japanese (`JA`), Korean (`KO`) | | Spanish (`ES`) | English (`EN-GB`, `EN-US`) | | French (`FR`) | English (`EN-GB`, `EN-US`) | | Italian (`IT`) | English (`EN-GB`, `EN-US`) | | Japanese (`JA`) | English (`EN-GB`, `EN-US`), Korean (`KO`), Chinese Simplified (`ZH-HANS`), Chinese Traditional (`ZH-HANT`) | | Korean (`KO`) | English (`EN-GB`, `EN-US`), Japanese (`JA`) | | Chinese (`ZH`) | Japanese (`JA`) | Requesting an evaluation for a pair that is not listed is rejected with `400` when the document is uploaded, so an evaluation only ever exists for a supported pair. See [`enable_quality_evaluation`](/api-reference/document/upload-and-translate-a-document). ## Rate limit This endpoint accepts 1,000 requests per minute per API key. Exceeding it returns `429 Too Many Requests`. ## Report retention A report is retained for 24 hours after its evaluation reaches `done` or `error`. After that, this endpoint returns `404 Not Found` for that job ID. ## OpenAPI ````yaml get /v1/quality-evaluations/{job_id} openapi: 3.0.3 info: title: DeepL API Documentation description: >- The DeepL API provides programmatic access to DeepL’s language AI technology. Note: this OpenAPI spec is embedded into our API documentation and has shortened descriptions. termsOfService: https://www.deepl.com/pro-license contact: name: DeepL - Contact us url: https://www.deepl.com/contact-us version: 3.13.0 servers: - url: https://api.deepl.com description: DeepL API Pro - url: https://api-free.deepl.com description: DeepL API Free security: [] tags: - name: beta description: >- Experimental features that are under testing and not yet intended for production use. - name: TranslateText description: >- The text-translation API currently consists of a single endpoint, `translate`, which is described below. - name: TranslateDocuments description: >- The document translation API allows you to translate whole documents and supports the following file types and extensions: * `docx` - Microsoft Word Document * `pptx` - Microsoft PowerPoint Document * `xlsx` - Microsoft Excel Document * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format * `jpeg` / `jpg` / `png` - Image (currently in beta) - name: RephraseText description: >- The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone. - name: CorrectText description: >- The `correct` endpoint fixes spelling and grammar errors without broader rephrasing. Use it when you want a minimal-change correction pass rather than the broader rewriting performed by `rephrase`. - name: ManageSpokenTerms description: >- The *Spoken Terms* functions allow you to create, inspect, edit and delete Spoken Terms collections. Spoken Terms improve speech recognition in the Voice API: they ensure specific words and phrases, such as company names, acronyms, and product names, are transcribed correctly. A collection contains one or more term lists, each holding terms for a single language, and is applied to a voice session via the `spoken_terms_id` parameter. - 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 (with the exception of Thai). 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 (with the exception of Thai). - name: MetaInformation description: Information about API usage and value ranges - name: TranslationMemories description: >- The translation memory endpoints allow you to manage your account's translation memories, used to store and reuse previously created translations. You can list and retrieve translation memories, page through their stored segments, create one by importing a TMX file, export one back to TMX, and delete one. Editing the contents of an existing translation memory is not supported; import a new one instead. Importing and exporting run as background jobs. Create the job, then poll `GET /v3/translation_memories/jobs/{job_id}` until it reports `completed`. Translation memories can be used in text translation requests by specifying the `translation_memory_id` parameter to denote a specific translation memory and the `translation_memory_threshold` which defines the minimum matching percentage required for a translation memory segment to be applied (recommended to be 75% or higher). A translation request fails with `404` if the translation memory does not exist or does not cover the requested language pair. - 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. - name: VoiceTranslateJob description: >- **Alpha.** Async voice translation jobs. This API may change without notice. - name: AdminApi description: >- Endpoints for organization administrators to manage API keys and retrieve usage analytics. - name: QualityEvaluation description: >- **Beta.** Retrieve a quality evaluation report for a document DeepL has translated. Reports are requested with `enable_quality_evaluation` on `POST /v2/document` and polled here. A report lists per-segment quality issues categorized by error type and severity, with character spans pointing to where each issue occurs. externalDocs: description: DeepL Pro - Plans and pricing url: https://www.deepl.com/pro#developer paths: /v1/quality-evaluations/{job_id}: get: tags: - QualityEvaluation summary: Poll for the evaluation result description: >- Returns the current state of a quality evaluation. While the evaluation is in progress the response carries only status information; once it completes, the response carries the full report. Evaluations are requested with `enable_quality_evaluation` on [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). There is no public endpoint for starting one. operationId: pollQualityEvaluation parameters: - name: job_id in: path required: true description: >- The unique ID of the quality evaluation, returned as `quality_evaluation_job_id` when the document was [uploaded for translation](/api-reference/document/upload-and-translate-a-document). schema: type: string example: 04DE5AD98A02647D83285A36021911C6 responses: '200': description: >- Polling result. The response shape depends on the `status` field. `done` carries the full report; `error` carries error details. content: application/json: schema: oneOf: - $ref: '#/components/schemas/QualityEvaluationDone' - $ref: '#/components/schemas/QualityEvaluationFailed' example: job_id: 04DE5AD98A02647D83285A36021911C6 status: done segments: - segment_index: 0 segment_score: 38.5 source: Our Q3 revenue came in 5% above forecast. target: Unser Q3-Umsatz lag 5 % unter der Prognose. applied_glossary_term_pairs: - source_term: forecast target_term: Prognose ranges: - start: 34 end: 42 errors: - type: Accuracy sub_type: Mistranslation severity: Critical explanation: >- The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This completely reverses the meaning and has financial implications. source_spans: - start: 23 end: 31 target_spans: - start: 20 end: 29 - segment_index: 1 segment_score: 62 source: Please share these results with your teams by Friday. target: Bitte teilen Sie diese Ergebnisse mit Ihrem Team. errors: - type: Accuracy sub_type: Omission severity: Major explanation: >- The source specifies the deadline 'by Friday' but the translation omits this temporal information entirely. source_spans: - start: 43 end: 52 target_spans: [] - type: Accuracy sub_type: Mistranslation severity: Minor explanation: >- The source says 'your teams' (plural) but the translation says 'Ihrem Team' (singular). This changes the scope of the instruction. source_spans: - start: 32 end: 42 target_spans: - start: 38 end: 48 '202': description: >- The evaluation is still running. Continue polling after the time suggested by the `Retry-After` header. headers: Retry-After: description: Suggested number of seconds to wait before polling again. schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationProcessing' example: job_id: 04DE5AD98A02647D83285A36021911C6 status: processing '400': description: The `job_id` is not a well-formed identifier. content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationApiError' example: message: job_id must be a valid UUID. '404': description: >- No evaluation exists for this `job_id`, it belongs to another account, or it has expired. See [Report retention](/api-reference/quality-evaluations/poll#report-retention). content: application/json: schema: $ref: '#/components/schemas/QualityEvaluationApiError' example: message: Quality estimation job not found. '429': $ref: '#/components/responses/TooManyRequests' security: - auth_header: [] components: schemas: QualityEvaluationDone: title: Done type: object required: - job_id - status - segments properties: job_id: type: string example: 04DE5AD98A02647D83285A36021911C6 status: type: string enum: - done example: done segments: type: array description: One entry per evaluated segment of the document, in reading order. items: $ref: '#/components/schemas/QualityEvaluationSegment' QualityEvaluationFailed: title: Error type: object required: - job_id - status - error properties: job_id: type: string example: 04DE5AD98A02647D83285A36021911C6 status: type: string enum: - error example: error error: type: object required: - code - message properties: code: type: string description: >- Machine-readable error code. Currently always `evaluation_failed`. example: evaluation_failed message: type: string description: Error message. example: The evaluation pipeline encountered an unexpected error. QualityEvaluationProcessing: type: object required: - job_id - status properties: job_id: type: string example: 04DE5AD98A02647D83285A36021911C6 status: type: string enum: - processing example: processing QualityEvaluationApiError: type: object required: - message properties: message: type: string description: Error message. QualityEvaluationSegment: type: object required: - segment_index - segment_score - errors properties: segment_index: type: integer description: >- Zero-based index of this segment within the document, in reading order. example: 0 segment_score: type: number format: float minimum: 0 maximum: 100 description: >- Quality score for this segment, where 0 is lowest and 100 is highest. example: 38.5 source: type: string description: >- The segment's source text as the evaluation read it. `source_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text). example: Our Q3 revenue came in 5% above forecast. target: type: string description: >- The segment's translated text as the evaluation read it. `target_spans` are offsets into this text. Omitted when the text is unavailable. See [Segment text](/api-reference/quality-evaluations/poll#segment-text). example: Unser Q3-Umsatz lag 5 % unter der Prognose. applied_glossary_term_pairs: type: array description: >- Glossary term pairs applied to this segment when the document was translated, so you can tell which customizations were in play where an issue was reported. Omitted when no term pair was applied. items: $ref: '#/components/schemas/QualityEvaluationAppliedGlossaryTermPair' errors: type: array description: >- Quality issues identified in this segment. Empty if no issues were found. items: $ref: '#/components/schemas/QualityEvaluationIssue' ErrorResponse: type: object required: - message properties: message: type: string description: A human-readable description of the error. code: type: string description: >- A machine-readable identifier for the error, when available. Clients should match on this value rather than on `message` when branching on error types. example: invalid_content_type QualityEvaluationAppliedGlossaryTermPair: type: object description: A glossary term pair that was applied to the segment's translation. required: - source_term - target_term - ranges properties: source_term: type: string description: The source term, as defined in the glossary. example: forecast target_term: type: string description: The target term, as applied to the translation. example: Prognose ranges: type: array description: >- Spans in `target` where the target term was applied, using the same convention as `source_spans` and `target_spans`. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationIssue: type: object required: - type - sub_type - severity - explanation - source_spans - target_spans properties: type: type: string description: >- Top-level category of the issue. See [Type and sub-type values](/api-reference/quality-evaluations/poll#type-and-sub-type-values). enum: - Accuracy - Fluency - Style - Miscellaneous - InternalTQEError example: Accuracy sub_type: type: string description: >- Finer-grained category within `type`. See [Type and sub-type values](/api-reference/quality-evaluations/poll#type-and-sub-type-values). enum: - Addition - Omission - Mistranslation - Over-translation - Under-translation - Untranslated text - Punctuation - Spelling - Grammar - Grammatical register - Inconsistency - Character encoding - Awkward - Inconsistent style - SegmentTooLarge example: Mistranslation severity: type: string description: >- How serious the issue is. See [Severity values](/api-reference/quality-evaluations/poll#severity-values). enum: - Critical - Major - Minor example: Critical explanation: type: string description: Description of the issue. May span multiple sentences. example: >- The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This completely reverses the meaning and has financial implications. source_spans: type: array description: >- Spans on the segment's source text where this issue applies. Empty if no source-side highlight. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' target_spans: type: array description: >- Spans on the segment's target text where this issue applies. Empty if no target-side highlight. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). items: $ref: '#/components/schemas/QualityEvaluationSpan' QualityEvaluationSpan: type: object required: - start - end description: >- A half-open `[start, end)` range of Unicode code points within a segment's source or target text. See [Span ranges](/api-reference/quality-evaluations/poll#span-ranges). properties: start: type: integer description: Inclusive start index. A 0-based Unicode code-point offset. example: 23 end: type: integer description: Exclusive end index. A 0-based Unicode code-point offset. example: 31 responses: TooManyRequests: description: Too many requests. Please wait and resend your request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: auth_header: type: apiKey description: > Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key ` name: Authorization in: header x-default: 'DeepL-Auth-Key ' ````