From 4c37c63c24cf8d3ac3d9898eb92725d013cc9b8e Mon Sep 17 00:00:00 2001 From: Tatjana Damdinshaw Date: Thu, 19 Feb 2026 14:40:03 +0100 Subject: [PATCH 1/6] Add Agent API endpoints --- api-reference/agent-api.mdx | 138 ++++++++++++ api-reference/agent-api/agent-api.yaml | 224 +++++++++++++++++++ api-reference/agent-api/get-task-result.mdx | 4 + api-reference/agent-api/trigger-workflow.mdx | 4 + docs.json | 8 + 5 files changed, 378 insertions(+) create mode 100644 api-reference/agent-api.mdx create mode 100644 api-reference/agent-api/agent-api.yaml create mode 100644 api-reference/agent-api/get-task-result.mdx create mode 100644 api-reference/agent-api/trigger-workflow.mdx diff --git a/api-reference/agent-api.mdx b/api-reference/agent-api.mdx new file mode 100644 index 0000000..3a857e9 --- /dev/null +++ b/api-reference/agent-api.mdx @@ -0,0 +1,138 @@ +--- +title: "DeepL Agent API" +public: true +sidebarTitle: "Overview" +description: "Explore the DeepL Agent API for workflows" +--- + +### Get started + + + The DeepL Agent API is only available to a limited set of DeepL Agent subscribers. Contact your DeepL customer success manager or our support team to enable access for your account. + + +Once enabled, follow the instructions in [Managing API keys](/docs/getting-started/managing-api-keys#basic-api-key-management) +to create an API key. +With the API key, you can trigger a DeepL Agent workflow and retrieve the results. +For more information on the DeepL Agent, visit the [HelpCenter](https://support.deepl.com/hc/en-us/categories/22974438575516-DeepL-Agent). + +### Trigger a workflow +Workflows are triggered with the help of the workflow ID. For more information on how to obtain a workflow ID, see the [HelpCenter](https://support.deepl.com/hc/en-us/articles/25472835912348). If your workflow contains a variable, you need to add an input to your request. +Once triggered the workflow runs in a task. + + + + ```sh Example request: Trigger a workflow + curl -X POST 'https://api.deepl.com/v1/unstable/agent/workflows/e1d78ccb-22e0-4a42-90e4-61884cf10af2/trigger' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ + --form 'workflow_request={"input":{"Airline Link": "https://lufthansa.com","Departure Airport": "FRA","Destination Airport": "HND","Outbound Date": "2026-01-09 15:30:00","Inbound Date": "2026-01-17 17:30:00","Cabin Class": "economy","Number of passengers": "1"}}' + ``` + ```json Example response + { + "task_id":"edb5e896-bf21-424e-9ae0-2429ebd53a1e", + "ui_url":"https://agent.deepl.dev/static/chat/edb5e896-bf21-424e-9ae0-2429ebd53a1e", + "polling_url":null, + "last_modified_date":"2025-12-05T12:32:02.191089+00:00" + } + ``` + + + ```http Example request: Trigger a workflow + POST /v1/unstable/agent/workflows/e1d78ccb-22e0-4a42-90e4-61884cf10af2/trigger HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + Content-Type: multipart/form-data; boundary=----WebKitFormBoundary + + ------WebKitFormBoundary + Content-Disposition: form-data; name="workflow_request" + + {"input":{"Airline Link": "https://lufthansa.com","Departure Airport": "FRA","Destination Airport": "HND","Outbound Date": "2026-01-09 15:30:00","Inbound Date": "2026-01-17 17:30:00","Cabin Class": "economy","Number of passengers": "1"}} + ------WebKitFormBoundary-- + ``` + ```json Example response + { + "task_id":"edb5e896-bf21-424e-9ae0-2429ebd53a1e", + "ui_url":"https://agent.deepl.dev/static/chat/edb5e896-bf21-424e-9ae0-2429ebd53a1e", + "polling_url":null, + "last_modified_date":"2025-12-05T12:32:02.191089+00:00" + } + ``` + + + +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable. + +### Get the task status and result +Check the status of the task in which the workflow is running, as well as the results once the workflow is completed. If the task isn’t finished, the result will be null. +The agent’s response to the completed workflow is available via a presigned URL, which is valid for five minutes. +The maximum number of requests allowed per minute is 12. + + + + ```sh Example request: Get task status and results + curl -X GET 'https://api.deepl.com/v1/unstable/agent/tasks/[yourTaskId]' \ + --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' + ``` + ```json Example response + { + "status":"completed", + "last_modified_date":"2025-12-05T12:54:05.711296+00:00", + "ui_url":null, + "result": { + "response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023" + } + } + ``` + + + ```http Example request: Get task status and results + GET /v1/unstable/agent/tasks/[yourTaskId] HTTP/2 + Host: api.deepl.com + Authorization: DeepL-Auth-Key [yourAuthKey] + User-Agent: YourApp/1.2.3 + ``` + ```json Example response + { + "status":"completed", + "last_modified_date":"2025-12-05T12:54:05.711296+00:00", + "ui_url":null, + "result": { + "response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023" + } + } + ``` + + + + + + ```sh Example request: Get content from the presigned URL + # Replace with your presigned URL + curl 'https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023' + ``` + ```json Example response + { + "message": "I've successfully completed the flight price research for your Frankfurt (FRA) to Tokyo Haneda (HND) trip.\n\n**Flight Details:**\n- Route: Frankfurt (FRA) \u2192 Tokyo Haneda (HND)\n- Dates: January 9-17, 2026\n- Passengers: 1\n- Class: Economy\n\n**Best Price Found:**\n- **EUR 514.43** for Economy class\n- Flight: 11:35 FRA \u2192 08:45+1 HND (next day arrival)\n- Direct flight (0 stops)\n- Operated by All Nippon Airways\n- Duration: 13h 10m\n\n**Other Options:**\n- Premium Economy: from EUR 1,464.43\n- Business Class: from EUR 2,189.43\n\n**Results Document:** [results.json](artifact://4c31b6a4-d9f0-43e7-9f0c-dd851334d5b8)\n\n**Screenshot:** [Flight Search Results](artifact://24a01ad9-c64e-4a27-9d2c-6246fb341be2)\n\nThe pricing is displayed in Euros and includes all available cabin classes for your selected dates.", + "content_type": "text", + "language": "en" + } + ``` + + + ```http Example request: Get content from the presigned URL + # Replace with your presigned URL + GET /api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023 HTTP/2 + Host: agent.deepl.com + ``` + ```json Example response + { + "message": "I've successfully completed the flight price research for your Frankfurt (FRA) to Tokyo Haneda (HND) trip.\n\n**Flight Details:**\n- Route: Frankfurt (FRA) \u2192 Tokyo Haneda (HND)\n- Dates: January 9-17, 2026\n- Passengers: 1\n- Class: Economy\n\n**Best Price Found:**\n- **EUR 514.43** for Economy class\n- Flight: 11:35 FRA \u2192 08:45+1 HND (next day arrival)\n- Direct flight (0 stops)\n- Operated by All Nippon Airways\n- Duration: 13h 10m\n\n**Other Options:**\n- Premium Economy: from EUR 1,464.43\n- Business Class: from EUR 2,189.43\n\n**Results Document:** [results.json](artifact://4c31b6a4-d9f0-43e7-9f0c-dd851334d5b8)\n\n**Screenshot:** [Flight Search Results](artifact://24a01ad9-c64e-4a27-9d2c-6246fb341be2)\n\nThe pricing is displayed in Euros and includes all available cabin classes for your selected dates.", + "content_type": "text", + "language": "en" + } + ``` + + + +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable. \ No newline at end of file diff --git a/api-reference/agent-api/agent-api.yaml b/api-reference/agent-api/agent-api.yaml new file mode 100644 index 0000000..4639ec1 --- /dev/null +++ b/api-reference/agent-api/agent-api.yaml @@ -0,0 +1,224 @@ +openapi: 3.0.3 +info: + title: DeepL Agent API + description: > + API for triggering and monitoring agentic workflows. These endpoints allow users to trigger + workflows with custom inputs and poll for task completion status. + version: 1.0.0 +servers: + - url: https://api.deepl.com + description: Production server +tags: + - name: agent + description: DeepL Agent workflow operations + +paths: + /v1/unstable/agent/workflows/{workflowId}/trigger: + post: + summary: Trigger a workflow + description: > + Triggers an agentic workflow with the specified ID. The workflow will be executed + asynchronously, and a task ID will be returned to poll for status updates. + operationId: trigger_workflow + tags: + - agent + security: + - auth_header: [] + parameters: + - name: workflowId + in: path + description: Unique identifier of the workflow to trigger + required: true + schema: + type: string + example: "workflow-123" + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + required: + - workflow_request + properties: + workflow_request: + type: string + description: JSON string containing the workflow input parameters + example: '{"input": {"language": "American English"}}' + responses: + 200: + description: Successfully triggered the workflow + content: + application/json: + schema: + $ref: '#/components/schemas/TriggerWorkflowResponse' + example: + task_id: "task-456" + ui_url: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + polling_url: "/v1/unstable/agent/tasks/task-456" + last_modified_date: "2025-12-04T10:30:00Z" + 400: + description: Bad request - invalid workflow_request JSON or missing required fields + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + message: "Invalid JSON in workflow_request field" + 401: + description: Unauthorized - invalid or missing API key, or account is not configured for agentic API use + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 404: + description: Workflow not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + message: "Workflow with ID 'workflow-123' not found" + + /v1/unstable/agent/tasks/{taskId}: + get: + summary: Get task status + description: > + Retrieves the current status and result of a previously triggered workflow task. + Use this endpoint to poll for task completion after triggering a workflow. + operationId: get_task_status + tags: + - agent + security: + - auth_header: [] + parameters: + - name: taskId + in: path + description: Unique identifier of the task to retrieve + required: true + schema: + type: string + example: "task-456" + responses: + 200: + description: Successfully retrieved task status + content: + application/json: + schema: + $ref: '#/components/schemas/GetTaskResponse' + examples: + in_progress: + summary: Task in progress + value: + status: "InProgress" + last_modified_date: "2025-12-04T10:30:00Z" + ui_url: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + result: {} + completed: + summary: Task completed + value: + status: "Completed" + last_modified_date: "2025-12-04T10:35:00Z" + ui_url: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + result: + output: "Translated text result" + 401: + description: Unauthorized - invalid or missing API key, or account is not configured for agentic API use + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + 404: + description: Task not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + message: "Task with ID 'task-456' not found" + +components: + schemas: + TriggerWorkflowResponse: + type: object + required: + - task_id + - last_modified_date + properties: + task_id: + type: string + description: Unique identifier for the triggered workflow task + example: "task-456" + ui_url: + type: string + nullable: true + description: URL to view the task in the agentic system user interface + example: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + polling_url: + type: string + nullable: true + description: Relative URL endpoint to poll for task status updates + example: "/v1/unstable/agent/tasks/task-456" + last_modified_date: + type: string + format: date-time + description: Timestamp of when the task was last modified (ISO 8601 format) + example: "2025-12-04T10:30:00Z" + + GetTaskResponse: + type: object + required: + - status + - last_modified_date + - result + properties: + status: + $ref: '#/components/schemas/TaskStatus' + last_modified_date: + type: string + format: date-time + description: Timestamp of when the task was last modified (ISO 8601 format) + example: "2025-12-04T10:35:00Z" + ui_url: + type: string + nullable: true + description: URL to view the task in the agentic UI + example: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + result: + type: object + description: Workflow-specific result data (structure varies by workflow type) + additionalProperties: true + example: + output: "Translated text result" + + TaskStatus: + type: string + description: Current status of the task + enum: + - Archived + - InProgress + - Completed + - Canceled + - Error + - FeedbackNeeded + example: "Completed" + + ErrorResponse: + type: object + required: + - message + properties: + message: + type: string + description: Human-readable error message + example: "Workflow with ID 'workflow-123' not found" + + securitySchemes: + auth_header: + type: apiKey + description: > + Authentication with `Authorization` header and + `DeepL-Auth-Key` authentication scheme. Example: + `DeepL-Auth-Key ` + name: Authorization + in: header \ No newline at end of file diff --git a/api-reference/agent-api/get-task-result.mdx b/api-reference/agent-api/get-task-result.mdx new file mode 100644 index 0000000..f25718b --- /dev/null +++ b/api-reference/agent-api/get-task-result.mdx @@ -0,0 +1,4 @@ +--- +openapi: /api-reference/agent-api/agent-api.yaml get /v1/unstable/agent/tasks/{taskId} +title: "Get task results" +--- \ No newline at end of file diff --git a/api-reference/agent-api/trigger-workflow.mdx b/api-reference/agent-api/trigger-workflow.mdx new file mode 100644 index 0000000..85a8d81 --- /dev/null +++ b/api-reference/agent-api/trigger-workflow.mdx @@ -0,0 +1,4 @@ +--- +openapi: /api-reference/agent-api/agent-api.yaml post /v1/unstable/agent/workflows/{workflowId}/trigger +title: "Trigger workflow" +--- \ No newline at end of file diff --git a/docs.json b/docs.json index aeac6e3..367742b 100644 --- a/docs.json +++ b/docs.json @@ -212,6 +212,14 @@ "api-reference/admin-api/get-usage-analytics" ] }, + { + "group": "Agent API", + "pages": [ + "api-reference/agent-api", + "api-reference/agent-api/trigger-workflow", + "api-reference/agent-api/get-task-result" + ] + }, { "group": "Translate Speech in Realtime", "pages": [ From 59f6973f0a70a03c7abda2ef8067f8b823fc9c35 Mon Sep 17 00:00:00 2001 From: Tatjana Damdinshaw Date: Thu, 19 Feb 2026 17:04:02 +0100 Subject: [PATCH 2/6] agent api specific yaml and json added --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 8b7c61b..3686f52 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .idea/* reviews/* .DS_Store +.tool-versions \ No newline at end of file From 9172d54dc6c16683cf4fd609ab53c62c7aa03e04 Mon Sep 17 00:00:00 2001 From: Tatjana Damdinshaw Date: Fri, 27 Feb 2026 13:08:52 +0000 Subject: [PATCH 3/6] changes suggested by the docs-review subagent implemented and new fields in response added --- api-reference/agent-api.mdx | 184 +++++++++++++++++++++---- api-reference/agent-api/agent-api.yaml | 101 +++++++++++--- 2 files changed, 235 insertions(+), 50 deletions(-) diff --git a/api-reference/agent-api.mdx b/api-reference/agent-api.mdx index 3a857e9..2155c23 100644 --- a/api-reference/agent-api.mdx +++ b/api-reference/agent-api.mdx @@ -2,10 +2,10 @@ title: "DeepL Agent API" public: true sidebarTitle: "Overview" -description: "Explore the DeepL Agent API for workflows" +description: "API reference to trigger DeepL Agent workflows and retrieve task results." --- -### Get started +## Get started The DeepL Agent API is only available to a limited set of DeepL Agent subscribers. Contact your DeepL customer success manager or our support team to enable access for your account. @@ -16,12 +16,18 @@ to create an API key. With the API key, you can trigger a DeepL Agent workflow and retrieve the results. For more information on the DeepL Agent, visit the [HelpCenter](https://support.deepl.com/hc/en-us/categories/22974438575516-DeepL-Agent). -### Trigger a workflow -Workflows are triggered with the help of the workflow ID. For more information on how to obtain a workflow ID, see the [HelpCenter](https://support.deepl.com/hc/en-us/articles/25472835912348). If your workflow contains a variable, you need to add an input to your request. +There's no integration of the Agent API in the official DeepL SDKs yet. Use the HTTP examples below to integrate directly. + +We also provide specs that are auto-generated from DeepL's Agent OpenAPI file: [Trigger workflow](/api-reference/agent-api/trigger-workflow) and [Get task results](/api-reference/agent-api/get-task-result). + +## Trigger a workflow +Workflows are triggered with the help of the workflow ID. For more information on how to obtain a workflow ID, see the [HelpCenter](https://support.deepl.com/hc/en-us/articles/25472835912348). The `input` object's fields are defined by the individual workflow's configuration. +Refer to your workflow in the DeepL Agent interface to determine which input fields are required. Once triggered the workflow runs in a task. + This endpoint is only available on `https://api.deepl.com`. It is not available on the API Free endpoint (`https://api-free.deepl.com`). ```sh Example request: Trigger a workflow curl -X POST 'https://api.deepl.com/v1/unstable/agent/workflows/e1d78ccb-22e0-4a42-90e4-61884cf10af2/trigger' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \ @@ -29,14 +35,15 @@ Once triggered the workflow runs in a task. ``` ```json Example response { - "task_id":"edb5e896-bf21-424e-9ae0-2429ebd53a1e", - "ui_url":"https://agent.deepl.dev/static/chat/edb5e896-bf21-424e-9ae0-2429ebd53a1e", - "polling_url":null, - "last_modified_date":"2025-12-05T12:32:02.191089+00:00" + "task_id": "e634159a-3414-4f66-a5cd-a1d48ff42ce3", + "ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3", + "polling_url": "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3", + "last_modified_date": "2025-12-05T12:32:02.191089+00:00" } ``` + This endpoint is only available on `https://api.deepl.com`. It is not available on the API Free endpoint (`https://api-free.deepl.com`). ```http Example request: Trigger a workflow POST /v1/unstable/agent/workflows/e1d78ccb-22e0-4a42-90e4-61884cf10af2/trigger HTTP/2 Host: api.deepl.com @@ -52,10 +59,10 @@ Once triggered the workflow runs in a task. ``` ```json Example response { - "task_id":"edb5e896-bf21-424e-9ae0-2429ebd53a1e", - "ui_url":"https://agent.deepl.dev/static/chat/edb5e896-bf21-424e-9ae0-2429ebd53a1e", - "polling_url":null, - "last_modified_date":"2025-12-05T12:32:02.191089+00:00" + "task_id": "e634159a-3414-4f66-a5cd-a1d48ff42ce3", + "ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3", + "polling_url": "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3", + "last_modified_date": "2025-12-05T12:32:02.191089+00:00" } ``` @@ -63,29 +70,73 @@ Once triggered the workflow runs in a task. These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable. -### Get the task status and result -Check the status of the task in which the workflow is running, as well as the results once the workflow is completed. If the task isn’t finished, the result will be null. -The agent’s response to the completed workflow is available via a presigned URL, which is valid for five minutes. -The maximum number of requests allowed per minute is 12. +### Request body descriptions + + JSON string containing the workflow input parameters. The `input` object's fields are defined by the individual workflow's configuration. + Refer to your workflow in the DeepL Agent interface to determine which input fields are required. + + + Workflow-specific key-value pairs. + + +### Response body descriptions + + Unique identifier for the triggered task. + + + Relative URL to poll for task status. + + + URL to view the task in the DeepL Agent interface. + + + ISO 8601 timestamp. + + +## Get the task status and result +Check the status of the task in which the workflow is running, as well as the results once the workflow is completed. If the task isn’t finished, the result is an empty object. + +The maximum number of requests allowed per minute is 12 per IP address. +Poll at regular intervals (for example, every 5 seconds) with exponential backoff. + This endpoint is only available on `https://api.deepl.com`. It is not available on the API Free endpoint (`https://api-free.deepl.com`). ```sh Example request: Get task status and results curl -X GET 'https://api.deepl.com/v1/unstable/agent/tasks/[yourTaskId]' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' ``` ```json Example response { - "status":"completed", - "last_modified_date":"2025-12-05T12:54:05.711296+00:00", - "ui_url":null, + "status": "Completed", + "last_modified_date": "2026-02-27T09:57:50.863818+00:00", + "ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3", "result": { - "response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023" - } + "screenshot": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8", + "response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32", + "data": null + }, + "result_data": [ + { + "artifactId": "9a2856bf-5333-4fd8-9500-3ea267b729b6", + "contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8", + "name": "final_screenshot", + "description": "Final browser screenshot", + "schema": null + }, + { + "artifactId": "5e381ed3-1642-40f7-b8de-69338fc4698f", + "contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjVlMzgxZWQzLTE2NDItNDBmNy1iOGRlLTY5MzM4ZmM0Njk4ZiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.f8bd75650b8112fff05b6bef8eae83d2472db96266b795f36c6820659c1feaf2", + "name": "Vodafone_News_Last_7_Days.md", + "description": "Top 10 news articles about Vodafone from the last 7 days", + "schema": null + } + ] } ``` + This endpoint is only available on `https://api.deepl.com`. It is not available on the API Free endpoint (`https://api-free.deepl.com`). ```http Example request: Get task status and results GET /v1/unstable/agent/tasks/[yourTaskId] HTTP/2 Host: api.deepl.com @@ -94,22 +145,86 @@ The maximum number of requests allowed per minute is 12. ``` ```json Example response { - "status":"completed", - "last_modified_date":"2025-12-05T12:54:05.711296+00:00", - "ui_url":null, + "status": "Completed", + "last_modified_date": "2026-02-27T09:57:50.863818+00:00", + "ui_url": "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3", "result": { - "response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023" - } + "screenshot": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8", + "response": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32", + "data": null + }, + "result_data": [ + { + "artifactId": "9a2856bf-5333-4fd8-9500-3ea267b729b6", + "contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8", + "name": "final_screenshot", + "description": "Final browser screenshot", + "schema": null + }, + { + "artifactId": "5e381ed3-1642-40f7-b8de-69338fc4698f", + "contentUrl": "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjVlMzgxZWQzLTE2NDItNDBmNy1iOGRlLTY5MzM4ZmM0Njk4ZiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.f8bd75650b8112fff05b6bef8eae83d2472db96266b795f36c6820659c1feaf2", + "name": "Vodafone_News_Last_7_Days.md", + "description": "Top 10 news articles about Vodafone from the last 7 days", + "schema": null + } + ] } ``` +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable. +### Task status response body descriptions + + Current task status. + + + The date the task was last modified. + + + URL to the task in the DeepL Agent. + + + Workflow result containing presigned URLs to retrieve output artifacts. Present in all responses; empty object `{}` while the task is in progress. + + + Presigned URL to retrieve the primary workflow result content. Valid for five minutes. + + + Presigned URL to retrieve a screenshot artifact from the workflow. Valid for five minutes. + + + Additional workflow result data. Structure is workflow-specific. + + + List of all artifacts produced by the workflow, with metadata and presigned content URLs. + + + Unique identifier of the artifact. + + + Presigned URL to retrieve the artifact content. Valid for five minutes. + + + Filename or identifier of the artifact. + + + Human-readable description of the artifact. + + + Optional schema describing the artifact's data structure. + + +## Retrieve the workflow result + +Once the task status is `Completed`, retrieve the workflow result by fetching the presigned URL returned in the `result.response` field. +Use the presigned URL exactly as returned in `result.response` — it is hosted on `agent.deepl.com` and is valid for five minutes. ```sh Example request: Get content from the presigned URL # Replace with your presigned URL - curl 'https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023' + curl 'https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32' ``` ```json Example response { @@ -121,8 +236,7 @@ The maximum number of requests allowed per minute is 12. ```http Example request: Get content from the presigned URL - # Replace with your presigned URL - GET /api/experimental/content/eyJhcnRpZmFjdF9pZCI6Ijc4MzBiNTMxLTM4YzYtNGQxNC04ZWJjLWMwYzUyOTExODE3OSIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiMDBmNGM5OTUtMDhkMy00NWRmLTg3NTQtNTg2OWI3MmIwYTQxIiwiZXhwaXJlcyI6MTc2NDkzOTU0OH0=.b901bca227e766ca303f09d15fbff465aae4aec69c31422eb0ee7a3217a1d023 HTTP/2 + GET /api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32 HTTP/2 Host: agent.deepl.com ``` ```json Example response @@ -135,4 +249,14 @@ The maximum number of requests allowed per minute is 12. -These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable. \ No newline at end of file +### Presigned URL response body descriptions + + The workflow result as a text string. + + + The type of content returned. For example, `text`. + + + The language code of the returned content. For example, `en`. + + diff --git a/api-reference/agent-api/agent-api.yaml b/api-reference/agent-api/agent-api.yaml index 4639ec1..93514a5 100644 --- a/api-reference/agent-api/agent-api.yaml +++ b/api-reference/agent-api/agent-api.yaml @@ -31,7 +31,8 @@ paths: required: true schema: type: string - example: "workflow-123" + format: uuid + example: "e1d78ccb-22e0-4a42-90e4-61884cf10af2" requestBody: required: true content: @@ -53,9 +54,9 @@ paths: schema: $ref: '#/components/schemas/TriggerWorkflowResponse' example: - task_id: "task-456" - ui_url: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" - polling_url: "/v1/unstable/agent/tasks/task-456" + task_id: "e634159a-3414-4f66-a5cd-a1d48ff42ce3" + ui_url: "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3" + polling_url: "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3" last_modified_date: "2025-12-04T10:30:00Z" 400: description: Bad request - invalid workflow_request JSON or missing required fields @@ -78,7 +79,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' example: - message: "Workflow with ID 'workflow-123' not found" + message: "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found" /v1/unstable/agent/tasks/{taskId}: get: @@ -98,7 +99,8 @@ paths: required: true schema: type: string - example: "task-456" + format: uuid + example: "e634159a-3414-4f66-a5cd-a1d48ff42ce3" responses: 200: description: Successfully retrieved task status @@ -112,16 +114,29 @@ paths: value: status: "InProgress" last_modified_date: "2025-12-04T10:30:00Z" - ui_url: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + ui_url: "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3" result: {} completed: summary: Task completed value: status: "Completed" - last_modified_date: "2025-12-04T10:35:00Z" - ui_url: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + last_modified_date: "2026-02-27T09:57:50.863818+00:00" + ui_url: "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3" result: - output: "Translated text result" + screenshot: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8" + response: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32" + data: null + result_data: + - artifactId: "9a2856bf-5333-4fd8-9500-3ea267b729b6" + contentUrl: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8" + name: "final_screenshot" + description: "Final browser screenshot" + schema: null + - artifactId: "5e381ed3-1642-40f7-b8de-69338fc4698f" + contentUrl: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjVlMzgxZWQzLTE2NDItNDBmNy1iOGRlLTY5MzM4ZmM0Njk4ZiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.f8bd75650b8112fff05b6bef8eae83d2472db96266b795f36c6820659c1feaf2" + name: "Vodafone_News_Last_7_Days.md" + description: "Top 10 news articles about Vodafone from the last 7 days" + schema: null 401: description: Unauthorized - invalid or missing API key, or account is not configured for agentic API use content: @@ -135,7 +150,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' example: - message: "Task with ID 'task-456' not found" + message: "Task with ID 'e634159a-3414-4f66-a5cd-a1d48ff42ce3' not found" components: schemas: @@ -148,17 +163,17 @@ components: task_id: type: string description: Unique identifier for the triggered workflow task - example: "task-456" + example: "e634159a-3414-4f66-a5cd-a1d48ff42ce3" ui_url: type: string nullable: true description: URL to view the task in the agentic system user interface - example: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + example: "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3" polling_url: type: string nullable: true description: Relative URL endpoint to poll for task status updates - example: "/v1/unstable/agent/tasks/task-456" + example: "/v1/unstable/agent/tasks/e634159a-3414-4f66-a5cd-a1d48ff42ce3" last_modified_date: type: string format: date-time @@ -183,13 +198,30 @@ components: type: string nullable: true description: URL to view the task in the agentic UI - example: "https://agent.deepl.com/static/chat/e333fb65-77eb-4669-ba55-201a5e3cff32" + example: "https://agent.deepl.com/static/chat/e634159a-3414-4f66-a5cd-a1d48ff42ce3" result: type: object - description: Workflow-specific result data (structure varies by workflow type) - additionalProperties: true - example: - output: "Translated text result" + description: Workflow result containing presigned URLs to retrieve output artifacts. Present in all responses; empty object `{}` while the task is in progress. + properties: + response: + type: string + nullable: true + description: Presigned URL to retrieve the primary workflow result content. Valid for five minutes. + example: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjUzOGU4OWFmLTNkN2QtNGEwZi04MDYxLWMyOTUzZjExZWEzOCIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.c88919cdc7bb9f7fc22ac7bd9b23c5c325a772d31310f437d4a04672c86cba32" + screenshot: + type: string + nullable: true + description: Presigned URL to retrieve a screenshot artifact from the workflow. Valid for five minutes. + example: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8" + data: + nullable: true + description: Additional workflow result data. Structure is workflow-specific. + result_data: + type: array + nullable: true + description: List of all artifacts produced by the workflow, with metadata and presigned content URLs. + items: + $ref: '#/components/schemas/ResultArtifact' TaskStatus: type: string @@ -203,6 +235,35 @@ components: - FeedbackNeeded example: "Completed" + ResultArtifact: + type: object + required: + - artifactId + - contentUrl + - name + - description + properties: + artifactId: + type: string + format: uuid + description: Unique identifier of the artifact. + example: "9a2856bf-5333-4fd8-9500-3ea267b729b6" + contentUrl: + type: string + description: Presigned URL to retrieve the artifact content. Valid for five minutes. + example: "https://agent.deepl.com/api/experimental/content/eyJhcnRpZmFjdF9pZCI6IjlhMjg1NmJmLTUzMzMtNGZkOC05NTAwLTNlYTI2N2I3MjliNiIsInZlcnNpb24iOjEsIm93bmVyX2lkIjoiNWM3YmIyNTQtZTU3NC00MjcyLTk0NTktZGJjN2JiM2JiMmVhIiwiZXhwaXJlcyI6MTc3MjE4NjYyM30=.686af5947238ed6920c29d83436bfc98c9d6c4015da0594e56007fff234f06e8" + name: + type: string + description: Filename or identifier of the artifact. + example: "final_screenshot" + description: + type: string + description: Human-readable description of the artifact. + example: "Final browser screenshot" + schema: + nullable: true + description: Optional schema describing the artifact's data structure. + ErrorResponse: type: object required: @@ -211,7 +272,7 @@ components: message: type: string description: Human-readable error message - example: "Workflow with ID 'workflow-123' not found" + example: "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found" securitySchemes: auth_header: From b022a8b1adfe85515680b191f538fee03b2075f5 Mon Sep 17 00:00:00 2001 From: Tatjana Damdinshaw Date: Fri, 27 Feb 2026 13:36:36 +0000 Subject: [PATCH 4/6] fixed broken links --- api-reference/translate.mdx | 2 +- docs/best-practices/custom-instructions.mdx | 2 +- docs/best-practices/pre-production-checklist.mdx | 2 +- docs/learning-how-tos/cookbook.mdx | 2 +- .../examples-and-guides/translating-between-variants.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 0e3f739..5e3284c 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -9,7 +9,7 @@ The text-translation API currently consists of a single endpoint, `translate`, w For highest translation quality, we recommend using our next-gen models. For details, please see [here](/docs/api-reference/translate#about-the-model-type-parameter). -To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/how-to-use-context-parameter). +To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter). For more detail about request body parameters, see the [Request Body Descriptions](/api-reference/translate#request-body-descriptions) section further down on the page. diff --git a/docs/best-practices/custom-instructions.mdx b/docs/best-practices/custom-instructions.mdx index 2138d87..a7c78d8 100644 --- a/docs/best-practices/custom-instructions.mdx +++ b/docs/best-practices/custom-instructions.mdx @@ -94,6 +94,6 @@ Combining `custom_instructions` with `model_type: latency_optimized` will result ## Related documentation - [Text translation API reference](/api-reference/translate) -- [Working with context](/docs/examples-and-guides/how-to-use-context-parameter) +- [Working with context](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) - [Style rules API](/api-reference/style-rules) - [Multilingual glossaries](/api-reference/multilingual-glossaries) diff --git a/docs/best-practices/pre-production-checklist.mdx b/docs/best-practices/pre-production-checklist.mdx index bbab7a0..645806f 100644 --- a/docs/best-practices/pre-production-checklist.mdx +++ b/docs/best-practices/pre-production-checklist.mdx @@ -11,5 +11,5 @@ As you prepare to open your DeepL-powered application up to the world, these tip * Uploading a file for document translation requires an HTTP POST request with `Content-Type: multipart/form-data`; this content type should not be used for text translation. 4. **No query parameters:** Please do not make API requests using query parameters. The examples throughout the API reference include properly formed HTTP POST requests. For security reasons, be especially sure not to send your authentication key via query parameters. 5. **CORS requests:** It's not possible to send requests to the DeepL API from the browser, as requests to third-party APIs from front-end applications would expose your credentials on the web. [You can learn more here](/docs/best-practices/cors-requests). -6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate#request-body-descriptions). [Learn more about working with context here](/docs/best-practices/working-with-context). +6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate#request-body-descriptions). [Learn more about working with context here](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter). 7. **Cache results from translation requests:** Storing API responses lets apps serve content faster and avoids extra costs from repeated requests for unchanged content. diff --git a/docs/learning-how-tos/cookbook.mdx b/docs/learning-how-tos/cookbook.mdx index 1baf0b6..39e447f 100644 --- a/docs/learning-how-tos/cookbook.mdx +++ b/docs/learning-how-tos/cookbook.mdx @@ -11,7 +11,7 @@ public: true Updated on 2025-03-12 - + Written by [Michael Winters](https://github.com/mike-winters-deepl) and [Paul Gordon](https://github.com/pgdev) Updated on 2025-03-12 diff --git a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx index 6ecd1d5..3f23d6e 100644 --- a/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/translating-between-variants.mdx @@ -130,5 +130,5 @@ Now that you understand how to translate between language variants: - **Try it yourself:** Test out style rules and custom instructions in the [text translation API playground](/api-reference/translate) - **Learn about the Write API:** Explore the [/write/rephrase endpoint](/api-reference/improve-text) for high-quality variant translation and rephrasing - **Manage reusable rules:** Learn how to create [style rules](/api-reference/style-rules) for systematic variant transformations -- **Improve translation quality:** Understand how [the context parameter](/docs/best-practices/working-with-context) can enhance ambiguous translations +- **Improve translation quality:** Understand how [the context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) can enhance ambiguous translations From 84b46c7faf74fa7c72cb33d33eec8f79ae128fb1 Mon Sep 17 00:00:00 2001 From: Tatjana Damdinshaw Date: Fri, 27 Feb 2026 13:41:57 +0000 Subject: [PATCH 5/6] resolve conflict --- docs/learning-how-tos/cookbook.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/learning-how-tos/cookbook.mdx b/docs/learning-how-tos/cookbook.mdx index 39e447f..51506a4 100644 --- a/docs/learning-how-tos/cookbook.mdx +++ b/docs/learning-how-tos/cookbook.mdx @@ -11,19 +11,11 @@ public: true Updated on 2025-03-12 - - Written by [Michael Winters](https://github.com/mike-winters-deepl) and [Paul Gordon](https://github.com/pgdev) - - Updated on 2025-03-12 - Written by Lucas Mathis Updated on 2024-04-10 - - - Written by [Akash Joshi](https://thewriting.dev) From 7a73596100e1a17ec576ee99e7010c1c904f516b Mon Sep 17 00:00:00 2001 From: Tatjana Damdinshaw Date: Fri, 27 Feb 2026 15:25:12 +0000 Subject: [PATCH 6/6] not used added to response.data field --- api-reference/agent-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/agent-api.mdx b/api-reference/agent-api.mdx index 2155c23..592ba12 100644 --- a/api-reference/agent-api.mdx +++ b/api-reference/agent-api.mdx @@ -195,7 +195,7 @@ These examples are for demonstration purposes only. In production code, the auth Presigned URL to retrieve a screenshot artifact from the workflow. Valid for five minutes. - Additional workflow result data. Structure is workflow-specific. + Optional additional workflow result data. Not used – deprecated. List of all artifacts produced by the workflow, with metadata and presigned content URLs.