Add Agent API endpoints #249
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,4 @@ | ||
| .idea/* | ||
| reviews/* | ||
| .DS_Store | ||
| .tool-versions |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| title: "DeepL Agent API" | ||
| public: true | ||
| sidebarTitle: "Overview" | ||
| description: "Explore the DeepL Agent API for workflows" | ||
| --- | ||
|
|
||
| ### Get started | ||
|
|
||
| <Info> | ||
| 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. | ||
| </Info> | ||
|
|
||
| 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. | ||
|
Contributor
There was a problem hiding this comment. To avoid passive voice here, how about replacing this first sentence with "To trigger a workflow, you'll need a workflow ID".
Contributor
There was a problem hiding this comment. I'm also not sure what the last sentence means. I assume you mean that the variable should be sent in the |
||
| Once triggered the workflow runs in a task. | ||
|
|
||
| <Tabs> | ||
| <Tab title="cURL"> | ||
| ```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" | ||
| } | ||
| ``` | ||
| </Tab> | ||
| <Tab title="HTTP Request"> | ||
| ```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" | ||
| } | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| 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. | ||
|
|
||
| <Tabs> | ||
| <Tab title="cURL"> | ||
| ```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" | ||
| } | ||
| } | ||
| ``` | ||
| </Tab> | ||
| <Tab title="HTTP Request"> | ||
| ```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" | ||
| } | ||
| } | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| <Tabs> | ||
| <Tab title="cURL"> | ||
| ```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" | ||
| } | ||
| ``` | ||
| </Tab> | ||
| <Tab title="HTTP Request"> | ||
| ```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" | ||
| } | ||
| ``` | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <api-key>` | ||
| name: Authorization | ||
| in: header |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| --- | ||
| openapi: /api-reference/agent-api/agent-api.yaml get /v1/unstable/agent/tasks/{taskId} | ||
| title: "Get task results" | ||
| --- |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| --- | ||
| openapi: /api-reference/agent-api/agent-api.yaml post /v1/unstable/agent/workflows/{workflowId}/trigger | ||
| title: "Trigger workflow" | ||
| --- |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are you saying that people need to create a special API key to use the Agent API? If not, I don't think we need this part.