From 0d7c909eafeb41cf73d4df839e80b2f747d62fa8 Mon Sep 17 00:00:00 2001 From: Ben Morss Date: Wed, 11 Mar 2026 15:37:30 -0400 Subject: [PATCH] Initial edits to Agent API docs, plus warning box around JS warning --- api-reference/agent-api.mdx | 23 ++++++++++++----------- api-reference/document.mdx | 4 +++- api-reference/improve-text.mdx | 4 +++- api-reference/translate.mdx | 4 +++- docs/getting-started/intro.mdx | 3 +++ 5 files changed, 24 insertions(+), 14 deletions(-) diff --git a/api-reference/agent-api.mdx b/api-reference/agent-api.mdx index 592ba12a..b897f8a0 100644 --- a/api-reference/agent-api.mdx +++ b/api-reference/agent-api.mdx @@ -2,26 +2,26 @@ title: "DeepL Agent API" public: true sidebarTitle: "Overview" -description: "API reference to trigger DeepL Agent workflows and retrieve task results." +description: "API reference for interacting with the DeepL Agent" --- ## 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. + Currently the DeepL Agent API is only available to a limited set of 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). +This API lets you trigger [DeepL Agent](https://support.deepl.com/hc/en-us/articles/23243163271196-About-DeepL-Agent) workflows and retrieve the results. + +If you don't already have a key for the DeepL API, -There's no integration of the Agent API in the official DeepL SDKs yet. Use the HTTP examples below to integrate directly. +Once enabled, follow the instructions in [Managing API keys](/docs/getting-started/managing-api-keys#basic-api-key-management) +to create an API key. -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). +DeepL's client libraries presently do not support the Agent API. Use the HTTP examples below to integrate directly. See also the [Trigger workflow](/api-reference/agent-api/trigger-workflow) and [Get task results](/api-reference/agent-api/get-task-result) HTTP requests samples that are auto-generated from DeepL's Agent OpenAPI file. ## 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. +To trigger a workflow, you will need its 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. @@ -68,7 +68,9 @@ 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. + +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded. Fetch it instead from a configuration file or environment variable. + ### Request body descriptions @@ -173,7 +175,6 @@ Poll at regular intervals (for example, every 5 seconds) with exponential backof ``` -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 diff --git a/api-reference/document.mdx b/api-reference/document.mdx index 6b99401c..d8be4d94 100644 --- a/api-reference/document.mdx +++ b/api-reference/document.mdx @@ -115,7 +115,9 @@ DE -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. + +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded. Fetch it instead from a configuration file or environment variable. + #### Request Body Descriptions diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx index 8c998ea4..8e4a94fd 100644 --- a/api-reference/improve-text.mdx +++ b/api-reference/improve-text.mdx @@ -29,7 +29,9 @@ For more detail about request body parameters, see the [Request body description ### Example cURL request and response -*These examples are for demonstration purposes only. In your code, the authentication key should not be hard-coded but instead fetched from a configuration file or environment variable.* + +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded. Fetch it instead from a configuration file or environment variable. + diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx index 5e3284c8..71abc1be 100644 --- a/api-reference/translate.mdx +++ b/api-reference/translate.mdx @@ -162,7 +162,9 @@ class Example { -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. + +These examples are for demonstration purposes only. In production code, the authentication key should not be hard-coded. Fetch it instead from a configuration file or environment variable. + Note that we do not include examples for our client libraries in every single section of this reference, but our client libraries *do* support all use cases shown on this page. diff --git a/docs/getting-started/intro.mdx b/docs/getting-started/intro.mdx index 1323ddb0..1cce3c5b 100644 --- a/docs/getting-started/intro.mdx +++ b/docs/getting-started/intro.mdx @@ -237,6 +237,9 @@ New user? Follow these quick steps to get started with the DeepL API. + + JavaScript/TypeScript users: for security reasons, you cannot call the DeepL API directly from client-side JavaScript. To do this during testing or prototyping, try one of [these quick proxies](https://developers.deepl.com/docs/learning-how-tos/cookbook/nodejs-proxy). + [Our official client libraries](/docs/getting-started/client-libraries) let you use the API with six popular programming languages - [Python](https://www.github.com/deeplcom/deepl-python), [JavaScript](https://www.github.com/deeplcom/deepl-node), [PHP](https://www.github.com/deeplcom/deepl-php), [.NET](https://www.github.com/deeplcom/deepl-dotnet), [Java](https://www.github.com/deeplcom/deepl-java), or [Ruby](https://www.github.com/deeplcom/deepl-rb). The DeepL community has [contributed client libraries](https://github.com/DeepLcom/awesome-deepl?tab=readme-ov-file#community-libraries--sdks) for other languages, including [Dart](https://github.com/komape/deepl_dart), [Go](https://github.com/candy12t/go-deepl), and [Rust](https://github.com/Avimitin/deepl-rs). You may also wish to check out [these examples and guides](/docs/learning-how-tos/examples-and-guides).