DeepLcom · ta-dam · Feb 27, 2026 · Feb 19, 2026 · Feb 19, 2026 · Feb 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 .idea/*
 reviews/*
 .DS_Store
+.tool-versions
diff --git a/api-reference/agent-api.mdx b/api-reference/agent-api.mdx
diff --git a/api-reference/agent-api/agent-api.yaml b/api-reference/agent-api/agent-api.yaml
@@ -0,0 +1,285 @@
+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
+            format: uuid
+          example: "e1d78ccb-22e0-4a42-90e4-61884cf10af2"
+      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: "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
+          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 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' 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
+            format: uuid
+          example: "e634159a-3414-4f66-a5cd-a1d48ff42ce3"
+      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/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
+                    result: {}
+                completed:
+                  summary: Task completed
+                  value:
+                    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:
+                      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:
+            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 'e634159a-3414-4f66-a5cd-a1d48ff42ce3' 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: "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/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/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
+        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/e634159a-3414-4f66-a5cd-a1d48ff42ce3"
+        result:
+          type: object
+          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
+      description: Current status of the task
+      enum:
+        - Archived
+        - InProgress
+        - Completed
+        - Canceled
+        - Error
+        - 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:
+        - message
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+          example: "Workflow with ID 'e1d78ccb-22e0-4a42-90e4-61884cf10af2' not found"
+
+  securitySchemes:
+    auth_header:
+      type: apiKey
+      description: >
+        Authentication with `Authorization` header and 
+        `DeepL-Auth-Key` authentication scheme. Example: 
+        `DeepL-Auth-Key <api-key>`
+      name: Authorization
+      in: header
diff --git a/api-reference/agent-api/get-task-result.mdx 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"
+---
diff --git a/api-reference/agent-api/trigger-workflow.mdx 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"
+---
diff --git 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.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": [

diff --git 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
@@ -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
@@ -11,19 +11,11 @@ public: true
 
     Updated on 2025-03-12
   </Card>
-  <Card title="Context Parameter Examples" icon="braille" href="/docs/learning-how-tos/cookbook/context-parameter-examples">
-    Written by [Michael Winters](https://github.com/mike-winters-deepl) and [Paul Gordon](https://github.com/pgdev)
-
-    Updated on 2025-03-12
-  </Card>
   <Card title="Using the DeepL API and Godot to localize indie games" icon="gamepad-modern" href="/docs/learning-how-tos/cookbook/automating-indie-game-localization-with-the-deepl-api-and-godot">
     Written by Lucas Mathis
 
     Updated on 2024-04-10
   </Card>
-</CardGroup>
-
-<CardGroup cols={3}>
   <Card title="Building a Document Translator with the DeepL API" icon="file" href="/docs/learning-how-tos/cookbook/java-document-translator">
     Written by [Akash Joshi](https://thewriting.dev)
 

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
@@ -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