From 26f0b730f4d1f74fe5ab5bb0c9ba1089848b46e3 Mon Sep 17 00:00:00 2001 From: Nikolay Yashin Date: Thu, 14 May 2026 08:06:04 +0200 Subject: [PATCH 1/7] docs(write): add /v2/write/correct corrections-only endpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the new corrections-only mode on the Write API: - New `/v2/write/correct` path and `CorrectText` tag in the OpenAPI spec. - New `api-reference/improve-text/correct-text.mdx` page driven by the spec. - Updated `improve-text.mdx` overview to describe both endpoints and link to the new one. - Updated the FAQ entry that previously said Corrections Only mode was UI-only — it is now also available via `/write/correct`. - Registered the new page in `docs.json` navigation. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/improve-text.mdx | 15 ++-- api-reference/improve-text/correct-text.mdx | 3 + api-reference/openapi.yaml | 93 +++++++++++++++++++++ docs.json | 3 +- 4 files changed, 108 insertions(+), 6 deletions(-) create mode 100644 api-reference/improve-text/correct-text.mdx diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx index 159628fe..544280aa 100644 --- a/api-reference/improve-text.mdx +++ b/api-reference/improve-text.mdx @@ -14,10 +14,15 @@ sidebarTitle: "Overview" ### DeepL API for Write overview -DeepL API for Write is accessible through an HTTP interface and currently consists of a single endpoint for text improvement, `/write/rephrase`, which is described below. The endpoint: +DeepL API for Write is accessible through an HTTP interface and consists of two endpoints: -* Accepts both form-encoded (`Content-Type: application/x-www-form-urlencoded`) and JSON-encoded (`Content-Type: application/json`) request bodies -* Returns JSON-encoded responses +* [`/write/rephrase`](/api-reference/improve-text/request-text-improvement) — broad text improvement. Fixes spelling and grammar and may also rewrite sentences for clarity, style, or tone. +* [`/write/correct`](/api-reference/improve-text/correct-text) — corrections-only mode. Fixes spelling and grammar errors with minimal changes to wording. Use this when you want the model to leave the author's voice intact. + +Both endpoints: + +* Accept both form-encoded (`Content-Type: application/x-www-form-urlencoded`) and JSON-encoded (`Content-Type: application/json`) request bodies +* Return JSON-encoded responses The client libraries support all features of the text improvement endpoint. The text improvement feature is currently only available to DeepL API Pro customers and is not yet available in DeepL API Free. @@ -179,6 +184,6 @@ We've added a new column to the [API key-level usage report](/docs/getting-start #### Is "Corrections Only" mode available in the API? -No. "Corrections Only" is a mode that fixes spelling and grammatical errors only without broader rephrasing. It is currently only available in the DeepL Translator UI. +Yes. Send your request to [`/write/correct`](/api-reference/improve-text/correct-text). This endpoint fixes spelling and grammar errors with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI. -If you make an API request to `/write/rephrase` and omit both `writing_style` and `tone`, the API uses its default improvement mode. This corrects grammar and spelling but may also make broader changes than the "Corrections Only" mode in the UI. +If you instead send a request to `/write/rephrase` and omit both `writing_style` and `tone`, the API uses its default improvement mode. This corrects grammar and spelling but may also make broader changes than `/write/correct`. diff --git a/api-reference/improve-text/correct-text.mdx b/api-reference/improve-text/correct-text.mdx new file mode 100644 index 00000000..8cec8cd2 --- /dev/null +++ b/api-reference/improve-text/correct-text.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/write/correct +--- diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 79f66ac1..9591b128 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -39,6 +39,10 @@ tags: - 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: ManageMultilingualGlossaries description: |- The *glossary* functions allow you to create, inspect, edit and delete glossaries. @@ -1756,6 +1760,95 @@ paths: example: This is a sample sentence to improve. security: - auth_header: [ ] + /v2/write/correct: + post: + tags: + - CorrectText + summary: Correct text + description: |- + Fix spelling and grammar errors in one or more texts. Unlike `/v2/write/rephrase`, this endpoint applies + a minimal-change correction pass and does not rewrite the text for style or tone. + operationId: correctText + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - text + properties: + text: + description: Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections 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' + application/x-www-form-urlencoded: + schema: + type: object + required: + - text + properties: + text: + description: Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections 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' + responses: + 200: + description: Successful text correction. + 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 + target_language: + description: The target language specified by the request. + type: string + example: en-US + text: + description: The corrected text. + type: string + example: This is a sample sentence to improve. + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + description: Unsupported Content-Type. Use `application/json` or `application/x-www-form-urlencoded`. + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [ ] /v2/usage: get: tags: diff --git a/docs.json b/docs.json index 94771ad2..23717225 100644 --- a/docs.json +++ b/docs.json @@ -251,7 +251,8 @@ "group": "Write", "pages": [ "api-reference/improve-text", - "api-reference/improve-text/request-text-improvement" + "api-reference/improve-text/request-text-improvement", + "api-reference/improve-text/correct-text" ] }, { From 0ce058d908261cfd5d2e64f84252d7e2e9ebcfc8 Mon Sep 17 00:00:00 2001 From: healqq <4745481+healqq@users.noreply.github.com> Date: Thu, 14 May 2026 06:06:37 +0000 Subject: [PATCH 2/7] chore: update OpenAPI JSON files from YAML sources --- api-reference/openapi.json | 133 +++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index fa88d772..f3081e97 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -41,6 +41,10 @@ "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\na minimal-change correction pass rather than the broader rewriting performed by `rephrase`." + }, { "name": "ManageMultilingualGlossaries", "description": "The *glossary* functions allow you to create, inspect, edit and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter. A glossary contains (several) dictionaries.\nA dictionary is a mapping of source phrases to target phrases for a single language pair.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently you can create glossaries with any of the languages DeepL supports (with the exception of Thai).\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a dictionary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant\n(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).\nDictionaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.\n(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.)\n\nGlossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.\nPlease only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website." @@ -2515,6 +2519,135 @@ ] } }, + "/v2/write/correct": { + "post": { + "tags": [ + "CorrectText" + ], + "summary": "Correct text", + "description": "Fix spelling and grammar errors in one or more texts. Unlike `/v2/write/rephrase`, this endpoint applies\na minimal-change correction pass and does not rewrite the text for style or tone.", + "operationId": "correctText", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "description": "Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections 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" + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "description": "Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections 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" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful text correction.", + "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" + }, + "target_language": { + "description": "The target language specified by the request.", + "type": "string", + "example": "en-US" + }, + "text": { + "description": "The corrected text.", + "type": "string", + "example": "This is a sample sentence to improve." + } + } + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "description": "Unsupported Content-Type. Use `application/json` or `application/x-www-form-urlencoded`." + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, "/v2/usage": { "get": { "tags": [ From 03b03271fa14baa908527c087a56a997c89760ab Mon Sep 17 00:00:00 2001 From: Nikolay Yashin Date: Thu, 14 May 2026 08:10:37 +0200 Subject: [PATCH 3/7] docs(write): add target_language to rephrase response schema The /v2/write/rephrase endpoint returns target_language in each improvements item, and the narrative MDX (improve-text.mdx) already documents it as a required ResponseField. The OpenAPI spec's response schema was missing it. Bring the spec in line with both the actual API behavior and the narrative docs. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/openapi.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 9591b128..1cfc9a06 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1754,6 +1754,10 @@ paths: description: The language detected in the source text. type: string example: en + target_language: + description: The target language specified by the request. + type: string + example: en-US text: description: The improved text. type: string From 38b0c895814e17132c3a5ef747d6d07d28355828 Mon Sep 17 00:00:00 2001 From: healqq <4745481+healqq@users.noreply.github.com> Date: Thu, 14 May 2026 06:11:11 +0000 Subject: [PATCH 4/7] chore: update OpenAPI JSON files from YAML sources --- api-reference/openapi.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index f3081e97..6dbc25cd 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2498,6 +2498,11 @@ "type": "string", "example": "en" }, + "target_language": { + "description": "The target language specified by the request.", + "type": "string", + "example": "en-US" + }, "text": { "description": "The improved text.", "type": "string", From 2c29aff844e1100e0175188e34a94fb3a541021f Mon Sep 17 00:00:00 2001 From: Nikolay Yashin Date: Thu, 14 May 2026 08:20:29 +0200 Subject: [PATCH 5/7] docs(write): add intros to rephrase and correct endpoint pages The rephrase and correct endpoint pages previously had only an `openapi:` frontmatter directive, so the rendered pages opened straight into the auto-generated request schema with no orientation. Add: - A short paragraph at the top of each page explaining what the endpoint does, when to choose it over the sibling endpoint, and a link to the overview for shared details (supported languages, size limits). - Frontmatter `title` and `description` so the page titles read naturally in the nav and in search results. - Rename the rephrase endpoint's OpenAPI summary from "Request text improvement" to "Improve text" to match the new page title and read more naturally. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/improve-text/correct-text.mdx | 6 ++++++ api-reference/improve-text/request-text-improvement.mdx | 8 +++++++- api-reference/openapi.yaml | 2 +- 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/api-reference/improve-text/correct-text.mdx b/api-reference/improve-text/correct-text.mdx index 8cec8cd2..020ec1f0 100644 --- a/api-reference/improve-text/correct-text.mdx +++ b/api-reference/improve-text/correct-text.mdx @@ -1,3 +1,9 @@ --- openapi: post /v2/write/correct +title: "Correct text" +description: "Learn how to fix spelling and grammar errors without rewriting text for style or tone." --- + +Send one or more texts to `/v2/write/correct` to fix spelling and grammar with minimal changes to wording. This matches the "Corrections Only" mode in the DeepL Translator UI. Unlike [`/v2/write/rephrase`](/api-reference/improve-text/request-text-improvement), this endpoint does not accept `writing_style` or `tone` and does not rewrite sentences for clarity. + +See the [Improve text overview](/api-reference/improve-text) for the list of supported target languages and request-size limits. diff --git a/api-reference/improve-text/request-text-improvement.mdx b/api-reference/improve-text/request-text-improvement.mdx index bd123ba1..da9b0410 100644 --- a/api-reference/improve-text/request-text-improvement.mdx +++ b/api-reference/improve-text/request-text-improvement.mdx @@ -1,3 +1,9 @@ --- openapi: post /v2/write/rephrase ---- \ No newline at end of file +title: "Improve text" +description: "Learn how to improve text by correcting spelling and grammar or rewriting for a target writing style or tone." +--- + +Send one or more texts to `/v2/write/rephrase` to get them rewritten for clarity, style, or tone. The endpoint corrects spelling and grammar and may rephrase sentences to match the requested `writing_style` or `tone`. If you only want to fix mistakes without changing wording, use [`/v2/write/correct`](/api-reference/improve-text/correct-text) instead. + +See the [Improve text overview](/api-reference/improve-text) for the list of supported target languages, supported styles and tones, and request-size limits. diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 1cfc9a06..7a1610d9 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1690,7 +1690,7 @@ paths: post: tags: - RephraseText - summary: Request text improvement + summary: Improve text operationId: rephraseText requestBody: required: true From b99a7dac2a99c88106a5f776f9ff07cf6ddd1c13 Mon Sep 17 00:00:00 2001 From: healqq <4745481+healqq@users.noreply.github.com> Date: Thu, 14 May 2026 06:20:56 +0000 Subject: [PATCH 6/7] chore: update OpenAPI JSON files from YAML sources --- api-reference/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 6dbc25cd..4638b317 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2413,7 +2413,7 @@ "tags": [ "RephraseText" ], - "summary": "Request text improvement", + "summary": "Improve text", "operationId": "rephraseText", "requestBody": { "required": true, From 857358660fa1df88dd8871b27949e6991bb69c4d Mon Sep 17 00:00:00 2001 From: Nikolay Yashin Date: Thu, 14 May 2026 08:22:55 +0200 Subject: [PATCH 7/7] docs(write): rewrite endpoint intros in third person Drop the imperative second-person framing ("Send ... to", "use X instead", "See the overview for...") on the rephrase and correct endpoint pages. The intros and frontmatter descriptions now describe what each endpoint does rather than instructing the reader. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/improve-text/correct-text.mdx | 6 ++---- api-reference/improve-text/request-text-improvement.mdx | 6 ++---- 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/api-reference/improve-text/correct-text.mdx b/api-reference/improve-text/correct-text.mdx index 020ec1f0..ba0a3dd2 100644 --- a/api-reference/improve-text/correct-text.mdx +++ b/api-reference/improve-text/correct-text.mdx @@ -1,9 +1,7 @@ --- openapi: post /v2/write/correct title: "Correct text" -description: "Learn how to fix spelling and grammar errors without rewriting text for style or tone." +description: "Fixes spelling and grammar errors with minimal changes to wording." --- -Send one or more texts to `/v2/write/correct` to fix spelling and grammar with minimal changes to wording. This matches the "Corrections Only" mode in the DeepL Translator UI. Unlike [`/v2/write/rephrase`](/api-reference/improve-text/request-text-improvement), this endpoint does not accept `writing_style` or `tone` and does not rewrite sentences for clarity. - -See the [Improve text overview](/api-reference/improve-text) for the list of supported target languages and request-size limits. +The `/v2/write/correct` endpoint fixes spelling and grammar errors in one or more texts with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI. It does not accept `writing_style` or `tone` and does not rephrase sentences for clarity. The broader [`/v2/write/rephrase`](/api-reference/improve-text/request-text-improvement) endpoint supports those parameters. diff --git a/api-reference/improve-text/request-text-improvement.mdx b/api-reference/improve-text/request-text-improvement.mdx index da9b0410..9d7dcc1d 100644 --- a/api-reference/improve-text/request-text-improvement.mdx +++ b/api-reference/improve-text/request-text-improvement.mdx @@ -1,9 +1,7 @@ --- openapi: post /v2/write/rephrase title: "Improve text" -description: "Learn how to improve text by correcting spelling and grammar or rewriting for a target writing style or tone." +description: "Improves text by correcting spelling and grammar and rewriting for a target writing style or tone." --- -Send one or more texts to `/v2/write/rephrase` to get them rewritten for clarity, style, or tone. The endpoint corrects spelling and grammar and may rephrase sentences to match the requested `writing_style` or `tone`. If you only want to fix mistakes without changing wording, use [`/v2/write/correct`](/api-reference/improve-text/correct-text) instead. - -See the [Improve text overview](/api-reference/improve-text) for the list of supported target languages, supported styles and tones, and request-size limits. +The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording.