KosmoKrator

productivity

DeepL Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the DeepL KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.deepl.*. Use lua_read_doc("integrations.deepl") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic DeepL workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.deepl.request_translation({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("deepl"))' --json
kosmo integrations:lua --eval 'print(docs.read("deepl.request_translation"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local deepl = app.integrations.deepl
local result = deepl.request_translation({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.deepl, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.deepl.default.* or app.integrations.deepl.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need DeepL, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

DeepL Lua Docs

Namespace: deepl

DeepL tools call the official DeepL API. Configure an API key and base URL before use. Use https://api.deepl.com for paid plans or https://api-free.deepl.com for the free tier.

This integration mirrors DeepL’s official OpenAPI document, including tools for text translation, document translation, v2 and v3 glossaries, glossary language pairs, write/rephrase, usage, supported languages, admin developer keys, admin analytics, style rules, translation memories, and voice realtime sessions.

Common tools:

local translated = deepl.deepl_translate_text({
  body = {
    text = { "Hello world" },
    target_lang = "DE"
  }
})

local usage = deepl.deepl_get_usage({})

local languages = deepl.deepl_list_languages({
  type = "target"
})

Request bodies can be passed as a body object. DeepL operations that support both JSON and form bodies default to JSON; pass content_type = "application/x-www-form-urlencoded" when you need form encoding. Document upload uses multipart/form-data according to the upstream API.

The previous deepl_get_current_user tool has been removed because DeepL does not expose a current-user endpoint in the official OpenAPI definition. Use deepl_get_usage for account usage and limits.

Use fake text, glossary ids, and API keys in examples and tests. Do not store real DeepL API keys in committed fixtures.

Raw agent markdown 
# DeepL Lua Docs

Namespace: `deepl`

DeepL tools call the official DeepL API. Configure an API key and base URL before use. Use `https://api.deepl.com` for paid plans or `https://api-free.deepl.com` for the free tier.

This integration mirrors DeepL's official OpenAPI document, including tools for text translation, document translation, v2 and v3 glossaries, glossary language pairs, write/rephrase, usage, supported languages, admin developer keys, admin analytics, style rules, translation memories, and voice realtime sessions.

Common tools:

```lua
local translated = deepl.deepl_translate_text({
  body = {
    text = { "Hello world" },
    target_lang = "DE"
  }
})

local usage = deepl.deepl_get_usage({})

local languages = deepl.deepl_list_languages({
  type = "target"
})
```

Request bodies can be passed as a `body` object. DeepL operations that support both JSON and form bodies default to JSON; pass `content_type = "application/x-www-form-urlencoded"` when you need form encoding. Document upload uses `multipart/form-data` according to the upstream API.

The previous `deepl_get_current_user` tool has been removed because DeepL does not expose a current-user endpoint in the official OpenAPI definition. Use `deepl_get_usage` for account usage and limits.

Use fake text, glossary ids, and API keys in examples and tests. Do not store real DeepL API keys in committed fixtures.
Metadata-derived Lua example 
local result = app.integrations.deepl.request_translation({})
print(result)

Functions

request_translation Write

The translate function. The total request body size must not exceed 128 KiB (128 * 1024 bytes). Please split up your text into multiple calls if it exceeds this limit.

Lua path
app.integrations.deepl.request_translation
Full name
deepl.deepl_translate_text
ParameterTypeRequiredDescription
No parameters.
upload_and_translate_document Write

This call uploads a document and queues it for translation. The call returns once the upload is complete, returning a document ID and key which can be used to query the translation statushttps://www.deepl.com/docs-api/documents/get-document-status and to download the translated documenthttps://www.deepl.com/docs-api/documents/download-document once translation is complete. Because the request includes a file upload, it must be an HTTP POST request with content type multipart/form-data. Please be aware that the uploaded document is automatically removed from the server once the translated document has been downloaded. You have to upload the document again in order to restart the translation. The maximum upload limit for documents is available herehttps://support.deepl.com/hc/articles/360020582359-Document-formats and may vary based on API plan and document type. You may specify the glossary to use for the document translation using the glossaryid parameter. Important: This requires the sourcelang parameter to be set and the language pair of the glossary has to match the language pair of the request.

Lua path
app.integrations.deepl.upload_and_translate_document
Full name
deepl.deepl_translate_document
ParameterTypeRequiredDescription
No parameters.
check_document_status Write

Retrieve the current status of a document translation process. If the translation is still in progress, the estimated time remaining is also included in the response.

Lua path
app.integrations.deepl.check_document_status
Full name
deepl.deepl_get_document_status
ParameterTypeRequiredDescription
No parameters.
download_translated_document Write

Once the status of the document translation process is done, the result can be downloaded. For privacy reasons the translated document is automatically removed from the server once it was downloaded and cannot be downloaded again.

Lua path
app.integrations.deepl.download_translated_document
Full name
deepl.deepl_download_document
ParameterTypeRequiredDescription
No parameters.
list_language_pairs_supported_by_glossaries Read

Retrieve the list of language pairs supported by the glossary feature.

Lua path
app.integrations.deepl.list_language_pairs_supported_by_glossaries
Full name
deepl.deepl_list_glossary_languages
ParameterTypeRequiredDescription
No parameters.
create_glossary Write

Create a Glossary

Lua path
app.integrations.deepl.create_glossary
Full name
deepl.deepl_create_multilingual_glossary
ParameterTypeRequiredDescription
No parameters.
list_all_glossaries Read

List all glossaries and their meta-information, but not the glossary entries.

Lua path
app.integrations.deepl.list_all_glossaries
Full name
deepl.deepl_list_multilingual_glossaries
ParameterTypeRequiredDescription
No parameters.
retrieve_glossary_details Read

Retrieve meta information for a single glossary, omitting the glossary entries.

Lua path
app.integrations.deepl.retrieve_glossary_details
Full name
deepl.deepl_get_multilingual_glossary
ParameterTypeRequiredDescription
No parameters.
edit_glossary_details Write

Edit glossary details, such as name or a dictionary for a source and target language.

Lua path
app.integrations.deepl.edit_glossary_details
Full name
deepl.deepl_patch_multilingual_glossary
ParameterTypeRequiredDescription
No parameters.
delete_glossary Write

Deletes the specified glossary.

Lua path
app.integrations.deepl.delete_glossary
Full name
deepl.deepl_delete_multilingual_glossary
ParameterTypeRequiredDescription
No parameters.
retrieve_glossary_entries Read

List the entries of a single glossary in tsv format.

Lua path
app.integrations.deepl.retrieve_glossary_entries
Full name
deepl.deepl_get_multilingual_glossary_entries
ParameterTypeRequiredDescription
No parameters.
deletes_dictionary_associated_with_given_language_pair_with_given_glossary_id Write

Deletes the dictionary associated with the given language pair with the given glossary ID.

Lua path
app.integrations.deepl.deletes_dictionary_associated_with_given_language_pair_with_given_glossary_id
Full name
deepl.deepl_delete_dictionary
ParameterTypeRequiredDescription
No parameters.
replaces_or_creates_dictionary_glossary_with_specified_entries Write

Replaces or creates a dictionary in the glossary with the specified entries.

Lua path
app.integrations.deepl.replaces_or_creates_dictionary_glossary_with_specified_entries
Full name
deepl.deepl_replace_dictionary
ParameterTypeRequiredDescription
No parameters.
create_glossary Write

Create a Glossary

Lua path
app.integrations.deepl.create_glossary
Full name
deepl.deepl_create_glossary
ParameterTypeRequiredDescription
No parameters.
list_all_glossaries Read

List all glossaries and their meta-information, but not the glossary entries.

Lua path
app.integrations.deepl.list_all_glossaries
Full name
deepl.deepl_list_glossaries
ParameterTypeRequiredDescription
No parameters.
retrieve_glossary_details Read

Retrieve meta information for a single glossary, omitting the glossary entries.

Lua path
app.integrations.deepl.retrieve_glossary_details
Full name
deepl.deepl_get_glossary
ParameterTypeRequiredDescription
No parameters.
delete_glossary Write

Deletes the specified glossary.

Lua path
app.integrations.deepl.delete_glossary
Full name
deepl.deepl_delete_glossary
ParameterTypeRequiredDescription
No parameters.
retrieve_glossary_entries Read

List the entries of a single glossary in the format specified by the Accept header.

Lua path
app.integrations.deepl.retrieve_glossary_entries
Full name
deepl.deepl_get_glossary_entries
ParameterTypeRequiredDescription
No parameters.
request_text_improvement Write

Request text improvement

Lua path
app.integrations.deepl.request_text_improvement
Full name
deepl.deepl_rephrase_text
ParameterTypeRequiredDescription
No parameters.
check_usage_and_limits Read

Retrieve usage information within the current billing period together with the corresponding account limits. Usage is returned for translated characters, translated documents, and translated documents team totals for team accounts only. Character usage includes both text and document translations, and is measured by the source text length in Unicode code points. Document usage only includes document translations, and is measured in individual documents. Depending on the user account type, some usage types will be omitted. Character usage is only included for developer accounts. Document usage is only included for non-developer accounts, and team-combined document usage is only included for non-developer team accounts.

Lua path
app.integrations.deepl.check_usage_and_limits
Full name
deepl.deepl_get_usage
ParameterTypeRequiredDescription
No parameters.
retrieve_supported_languages Read

Retrieve the list of languages that are currently supported for translation, either as source or target language, respectively.

Lua path
app.integrations.deepl.retrieve_supported_languages
Full name
deepl.deepl_list_languages
ParameterTypeRequiredDescription
No parameters.
create_developer_key_as_admin Write

Create a developer key as an admin

Lua path
app.integrations.deepl.create_developer_key_as_admin
Full name
deepl.deepl_admin_create_developer_key
ParameterTypeRequiredDescription
No parameters.
get_all_developer_keys_as_admin Read

Get all developer keys as an admin

Lua path
app.integrations.deepl.get_all_developer_keys_as_admin
Full name
deepl.deepl_admin_get_developer_keys
ParameterTypeRequiredDescription
No parameters.
deactivate_developer_key_as_admin Write

Deactivate a developer key as an admin

Lua path
app.integrations.deepl.deactivate_developer_key_as_admin
Full name
deepl.deepl_admin_deactivate_developer_key
ParameterTypeRequiredDescription
No parameters.
rename_developer_key_as_admin Write

Rename a developer key as an admin

Lua path
app.integrations.deepl.rename_developer_key_as_admin
Full name
deepl.deepl_admin_rename_developer_key
ParameterTypeRequiredDescription
No parameters.
set_developer_key_usage_limits_as_admin Write

Set developer key usage limits as an admin

Lua path
app.integrations.deepl.set_developer_key_usage_limits_as_admin
Full name
deepl.deepl_admin_set_developer_key_usage_limits
ParameterTypeRequiredDescription
No parameters.
get_usage_statistics_as_admin Read

Retrieve usage statistics for the organization within a specified date range. Optionally group the results by API key or by API key and day.

Lua path
app.integrations.deepl.get_usage_statistics_as_admin
Full name
deepl.deepl_admin_get_analytics
ParameterTypeRequiredDescription
No parameters.
retrieve_style_rule_lists Read

Retrieve style rule lists

Lua path
app.integrations.deepl.retrieve_style_rule_lists
Full name
deepl.deepl_get_style_rule_lists
ParameterTypeRequiredDescription
No parameters.
create_style_rule_list Write

Create a style rule list

Lua path
app.integrations.deepl.create_style_rule_list
Full name
deepl.deepl_create_style_rule_list
ParameterTypeRequiredDescription
No parameters.
retrieve_style_rule_list Read

Retrieve a style rule list

Lua path
app.integrations.deepl.retrieve_style_rule_list
Full name
deepl.deepl_get_style_rule_list
ParameterTypeRequiredDescription
No parameters.
update_style_rule_list Write

Update a style rule list

Lua path
app.integrations.deepl.update_style_rule_list
Full name
deepl.deepl_update_style_rule_list
ParameterTypeRequiredDescription
No parameters.
delete_style_rule_list Write

Delete a style rule list

Lua path
app.integrations.deepl.delete_style_rule_list
Full name
deepl.deepl_delete_style_rule_list
ParameterTypeRequiredDescription
No parameters.
update_configured_rules_style_rule_list Write

Update configured rules for a style rule list

Lua path
app.integrations.deepl.update_configured_rules_style_rule_list
Full name
deepl.deepl_update_style_rule_configured_rules
ParameterTypeRequiredDescription
No parameters.
create_custom_instruction Write

Create a custom instruction

Lua path
app.integrations.deepl.create_custom_instruction
Full name
deepl.deepl_create_custom_instruction
ParameterTypeRequiredDescription
No parameters.
retrieve_custom_instruction Read

Retrieve a custom instruction

Lua path
app.integrations.deepl.retrieve_custom_instruction
Full name
deepl.deepl_get_custom_instruction
ParameterTypeRequiredDescription
No parameters.
update_custom_instruction Write

Update a custom instruction

Lua path
app.integrations.deepl.update_custom_instruction
Full name
deepl.deepl_update_custom_instruction
ParameterTypeRequiredDescription
No parameters.
delete_custom_instruction Write

Delete a custom instruction

Lua path
app.integrations.deepl.delete_custom_instruction
Full name
deepl.deepl_delete_custom_instruction
ParameterTypeRequiredDescription
No parameters.
list_translation_memories Read

Retrieve a list of translation memories associated with the authenticated account.

Lua path
app.integrations.deepl.list_translation_memories
Full name
deepl.deepl_list_translation_memories
ParameterTypeRequiredDescription
No parameters.
get_streaming_url Write

Get Streaming URL

Lua path
app.integrations.deepl.get_streaming_url
Full name
deepl.deepl_get_voice_streaming_url
ParameterTypeRequiredDescription
No parameters.
request_reconnection Read

Request Reconnection

Lua path
app.integrations.deepl.request_reconnection
Full name
deepl.deepl_request_reconnection
ParameterTypeRequiredDescription
No parameters.