KosmoKrator

productivity

CloudConvert Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.cloudconvert.*. Use lua_read_doc("integrations.cloudconvert") 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 CloudConvert workflow without starting an interactive agent session.

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

Workflow file

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

workflow.lua 
local cloudconvert = app.integrations.cloudconvert
local result = cloudconvert.api_get({})

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.cloudconvert, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.cloudconvert.default.* or app.integrations.cloudconvert.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need CloudConvert, 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.

CloudConvert Lua Reference

Namespace: app.integrations.cloudconvert

CloudConvert tools use a bearer api_key. Domain-specific task payloads are passed through to CloudConvert as JSON, so use the field names from the CloudConvert v2 API.

Common Workflows

Create an async conversion job:

local job = app.integrations.cloudconvert.create_job({
  tasks = {
    import_file = {
      operation = "import/url",
      url = "https://example.test/document.pdf"
    },
    convert_file = {
      operation = "convert",
      input = "import_file",
      output_format = "png"
    },
    export_file = {
      operation = "export/url",
      input = "convert_file"
    }
  },
  tag = "agent-demo"
})

Discover supported operation parameters:

local operations = app.integrations.cloudconvert.list_operations({
  operation = "convert",
  output_format = "pdf",
  include = "options"
})

Wait for sync completion:

local finished = app.integrations.cloudconvert.wait_job({
  job_id = job.data.id
})

Coverage Notes

  • list_operations is the discovery entry point for supported operations, formats, engines, versions, and option schemas.
  • create_job and create_job_sync expect named task definitions, not an ordered list.
  • Task operations such as convert, import/url, and export/url are created inside job payloads; CloudConvert does not expose separate public create-task endpoints for those operation pages.
  • list_jobs and list_tasks normalize simple status, tag, job_id, and operation parameters into CloudConvert filter[...] query keys.
  • Sync tools use the configured sync_url and may hold the HTTP request open while CloudConvert processes the job or task.
  • Raw api_get, api_post, api_put, and api_delete can call any CloudConvert v2 endpoint path.
  • create_signed_url and verify_webhook_signature run locally because CloudConvert documents those as signing helpers rather than API calls.

Responses are decoded CloudConvert JSON exactly as returned by the API.

Raw agent markdown 
# CloudConvert Lua Reference

Namespace: `app.integrations.cloudconvert`

CloudConvert tools use a bearer `api_key`. Domain-specific task payloads are passed through to CloudConvert as JSON, so use the field names from the CloudConvert v2 API.

## Common Workflows

Create an async conversion job:

```lua
local job = app.integrations.cloudconvert.create_job({
  tasks = {
    import_file = {
      operation = "import/url",
      url = "https://example.test/document.pdf"
    },
    convert_file = {
      operation = "convert",
      input = "import_file",
      output_format = "png"
    },
    export_file = {
      operation = "export/url",
      input = "convert_file"
    }
  },
  tag = "agent-demo"
})
```

Discover supported operation parameters:

```lua
local operations = app.integrations.cloudconvert.list_operations({
  operation = "convert",
  output_format = "pdf",
  include = "options"
})
```

Wait for sync completion:

```lua
local finished = app.integrations.cloudconvert.wait_job({
  job_id = job.data.id
})
```

## Coverage Notes

- `list_operations` is the discovery entry point for supported operations, formats, engines, versions, and option schemas.
- `create_job` and `create_job_sync` expect named task definitions, not an ordered list.
- Task operations such as `convert`, `import/url`, and `export/url` are created inside job payloads; CloudConvert does not expose separate public create-task endpoints for those operation pages.
- `list_jobs` and `list_tasks` normalize simple `status`, `tag`, `job_id`, and `operation` parameters into CloudConvert `filter[...]` query keys.
- Sync tools use the configured `sync_url` and may hold the HTTP request open while CloudConvert processes the job or task.
- Raw `api_get`, `api_post`, `api_put`, and `api_delete` can call any CloudConvert v2 endpoint path.
- `create_signed_url` and `verify_webhook_signature` run locally because CloudConvert documents those as signing helpers rather than API calls.

Responses are decoded CloudConvert JSON exactly as returned by the API.
Metadata-derived Lua example 
local result = app.integrations.cloudconvert.api_get({})
print(result)

Functions

api_get Read

Call any CloudConvert API GET endpoint path.

Lua path
app.integrations.cloudconvert.api_get
Full name
cloudconvert.cloudconvert_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call any CloudConvert API POST endpoint path.

Lua path
app.integrations.cloudconvert.api_post
Full name
cloudconvert.cloudconvert_api_post
ParameterTypeRequiredDescription
No parameters.
api_put Write

Call any CloudConvert API PUT endpoint path.

Lua path
app.integrations.cloudconvert.api_put
Full name
cloudconvert.cloudconvert_api_put
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call any CloudConvert API DELETE endpoint path.

Lua path
app.integrations.cloudconvert.api_delete
Full name
cloudconvert.cloudconvert_api_delete
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the authenticated CloudConvert user profile and remaining credits.

Lua path
app.integrations.cloudconvert.get_current_user
Full name
cloudconvert.cloudconvert_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_operations Read

List available operations, formats, engines, versions, and options.

Lua path
app.integrations.cloudconvert.list_operations
Full name
cloudconvert.cloudconvert_list_operations
ParameterTypeRequiredDescription
No parameters.
create_job Write

Create an async CloudConvert job with named tasks.

Lua path
app.integrations.cloudconvert.create_job
Full name
cloudconvert.cloudconvert_create_job
ParameterTypeRequiredDescription
No parameters.
create_job_sync Write

Create a CloudConvert job and wait for completion using the sync API.

Lua path
app.integrations.cloudconvert.create_job_sync
Full name
cloudconvert.cloudconvert_create_job_sync
ParameterTypeRequiredDescription
No parameters.
get_job Read

Get details and status for a CloudConvert job.

Lua path
app.integrations.cloudconvert.get_job
Full name
cloudconvert.cloudconvert_get_job
ParameterTypeRequiredDescription
No parameters.
wait_job Read

Wait until a CloudConvert job finishes or fails using the sync API.

Lua path
app.integrations.cloudconvert.wait_job
Full name
cloudconvert.cloudconvert_wait_job
ParameterTypeRequiredDescription
No parameters.
list_jobs Read

List CloudConvert jobs with documented filters.

Lua path
app.integrations.cloudconvert.list_jobs
Full name
cloudconvert.cloudconvert_list_jobs
ParameterTypeRequiredDescription
No parameters.
delete_job Write

Delete a CloudConvert job and its temporary data.

Lua path
app.integrations.cloudconvert.delete_job
Full name
cloudconvert.cloudconvert_delete_job
ParameterTypeRequiredDescription
No parameters.
get_task Read

Get details and status for a CloudConvert task.

Lua path
app.integrations.cloudconvert.get_task
Full name
cloudconvert.cloudconvert_get_task
ParameterTypeRequiredDescription
No parameters.
wait_task Read

Wait until a CloudConvert task finishes or fails using the sync API.

Lua path
app.integrations.cloudconvert.wait_task
Full name
cloudconvert.cloudconvert_wait_task
ParameterTypeRequiredDescription
No parameters.
list_tasks Read

List CloudConvert tasks with documented filters.

Lua path
app.integrations.cloudconvert.list_tasks
Full name
cloudconvert.cloudconvert_list_tasks
ParameterTypeRequiredDescription
No parameters.
cancel_task Write

Cancel a waiting or processing CloudConvert task.

Lua path
app.integrations.cloudconvert.cancel_task
Full name
cloudconvert.cloudconvert_cancel_task
ParameterTypeRequiredDescription
No parameters.
retry_task Write

Create a retry task from the payload of another task.

Lua path
app.integrations.cloudconvert.retry_task
Full name
cloudconvert.cloudconvert_retry_task
ParameterTypeRequiredDescription
No parameters.
delete_task Write

Delete a CloudConvert task and its temporary data.

Lua path
app.integrations.cloudconvert.delete_task
Full name
cloudconvert.cloudconvert_delete_task
ParameterTypeRequiredDescription
No parameters.
create_webhook Write

Create an account-level CloudConvert webhook.

Lua path
app.integrations.cloudconvert.create_webhook
Full name
cloudconvert.cloudconvert_create_webhook
ParameterTypeRequiredDescription
No parameters.
list_webhooks Read

List account-level CloudConvert webhooks.

Lua path
app.integrations.cloudconvert.list_webhooks
Full name
cloudconvert.cloudconvert_list_webhooks
ParameterTypeRequiredDescription
No parameters.
delete_webhook Write

Delete an account-level CloudConvert webhook.

Lua path
app.integrations.cloudconvert.delete_webhook
Full name
cloudconvert.cloudconvert_delete_webhook
ParameterTypeRequiredDescription
No parameters.
create_signed_url Write

Create a CloudConvert signed URL for on-demand conversions.

Lua path
app.integrations.cloudconvert.create_signed_url
Full name
cloudconvert.cloudconvert_create_signed_url
ParameterTypeRequiredDescription
signed_url_base string yes Signed URL base from CloudConvert signed URL settings.
signing_secret string yes Signing secret for the signed URL base.
job object yes CloudConvert job payload with tasks and an export/url task.
cache_key string no Optional cache key to reuse output for 24 hours.
verify_webhook_signature Read

Verify a CloudConvert webhook HMAC signature.

Lua path
app.integrations.cloudconvert.verify_webhook_signature
Full name
cloudconvert.cloudconvert_verify_webhook_signature
ParameterTypeRequiredDescription
payload string yes Raw webhook request body.
signature string yes CloudConvert-Signature header value.
signing_secret string yes Webhook signing secret from CloudConvert webhook settings.