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
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": [