KosmoKrator

productivity

Zendesk Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.zendesk.create_ticket({subject = "example_subject", description = "example_description", priority = "example_priority", type = "example_type", status = "example_status", assignee_id = "example_assignee_id", tags = "example_tags"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("zendesk"))' --json
kosmo integrations:lua --eval 'print(docs.read("zendesk.create_ticket"))' --json

Workflow file

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

workflow.lua 
local zendesk = app.integrations.zendesk
local result = zendesk.create_ticket({subject = "example_subject", description = "example_description", priority = "example_priority", type = "example_type", status = "example_status", assignee_id = "example_assignee_id", tags = "example_tags"})

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

MCP-only Lua

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

Client for the Zendesk REST API covering tickets, users, and organizations — Lua API Reference

zendesk_list_tickets

List Zendesk tickets with pagination and filtering. Returns ticket IDs, subjects, status, priority, and created dates.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of tickets per page (default 25, max 100).
pageintegernoPage number for pagination (1-indexed).
sort_bystringnoField to sort by (e.g. “created_at”, “updated_at”, “priority”).
sort_orderstringnoSort order: “asc” or “desc”.
statusstringnoFilter by ticket status: “new”, “open”, “pending”, “hold”, “solved”, “closed”.

Example

local result = app.integrations.zendesk.zendesk_list_tickets({
  per_page = 25
  page = 1
  status = "open"
})

zendesk_get_ticket

Retrieve a Zendesk ticket by its ID. Returns the full ticket including subject, description, status, priority, and metadata.

Parameters

NameTypeRequiredDescription
ticket_idstringyesZendesk ticket ID.

Example

local result = app.integrations.zendesk.zendesk_get_ticket({
  ticket_id = "12345"
})

zendesk_create_ticket

Create a new ticket in Zendesk. Requires a subject and description. Optionally set priority, type, status, and assignee. Returns the created ticket with its ID.

Parameters

NameTypeRequiredDescription
subjectstringyesSubject of the ticket.
descriptionstringyesInitial description/body of the ticket.
prioritystringnoTicket priority: “urgent”, “high”, “normal”, “low”.
typestringnoTicket type: “problem”, “incident”, “question”, “task”.
statusstringnoInitial status: “new”, “open”, “pending”, “hold” (default: “new”).
assignee_idstringnoID of the agent to assign the ticket to.
tagsarraynoArray of tags to apply to the ticket.

Example

local result = app.integrations.zendesk.zendesk_create_ticket({
  subject = "Login issue"
  description = "User cannot log in to the application."
  priority = "high"
  type = "incident"
})

zendesk_list_users

List Zendesk users with pagination and filtering. Returns user IDs, names, emails, and roles.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of users per page (default 100, max 100).
pageintegernoPage number for pagination (1-indexed).
rolestringnoFilter by role: “end-user”, “agent”, “admin”.
sort_bystringnoField to sort by (e.g. “name”, “created_at”).
sort_orderstringnoSort order: “asc” or “desc”.

Example

local result = app.integrations.zendesk.zendesk_list_users({
  per_page = 50
  role = "agent"
})

zendesk_get_user

Retrieve a Zendesk user by its ID. Returns the user’s ID, name, email, role, and profile details.

Parameters

NameTypeRequiredDescription
user_idstringyesZendesk user ID.

Example

local result = app.integrations.zendesk.zendesk_get_user({
  user_id = "98765"
})

zendesk_list_organizations

List Zendesk organizations with pagination. Returns organization IDs, names, and created dates.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of organizations per page (default 100, max 100).
pageintegernoPage number for pagination (1-indexed).

Example

local result = app.integrations.zendesk.zendesk_list_organizations({
  per_page = 50
})

zendesk_get_current_user

Retrieve the currently authenticated Zendesk user. Returns the user’s ID, name, email, role, and avatar. Useful for identifying which account or token is in use.

Example

local result = app.integrations.zendesk.zendesk_get_current_user({
})

Multi-Account Usage

If you have multiple zendesk accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.zendesk.function_name({...})

-- Explicit default (portable across setups)
app.integrations.zendesk.default.function_name({...})

-- Named accounts
app.integrations.zendesk.work.function_name({...})
app.integrations.zendesk.personal.function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Client for the Zendesk REST API covering tickets, users, and organizations — Lua API Reference

## zendesk_list_tickets

List Zendesk tickets with pagination and filtering.
Returns ticket IDs, subjects, status, priority, and created dates.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of tickets per page (default 25, max 100). |
| `page` | integer | no | Page number for pagination (1-indexed). |
| `sort_by` | string | no | Field to sort by (e.g. "created_at", "updated_at", "priority"). |
| `sort_order` | string | no | Sort order: "asc" or "desc". |
| `status` | string | no | Filter by ticket status: "new", "open", "pending", "hold", "solved", "closed". |

### Example

```lua
local result = app.integrations.zendesk.zendesk_list_tickets({
  per_page = 25
  page = 1
  status = "open"
})
```

## zendesk_get_ticket

Retrieve a Zendesk ticket by its ID.
Returns the full ticket including subject, description, status, priority, and metadata.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticket_id` | string | yes | Zendesk ticket ID. |

### Example

```lua
local result = app.integrations.zendesk.zendesk_get_ticket({
  ticket_id = "12345"
})
```

## zendesk_create_ticket

Create a new ticket in Zendesk.
Requires a subject and description. Optionally set priority, type, status, and assignee.
Returns the created ticket with its ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subject` | string | yes | Subject of the ticket. |
| `description` | string | yes | Initial description/body of the ticket. |
| `priority` | string | no | Ticket priority: "urgent", "high", "normal", "low". |
| `type` | string | no | Ticket type: "problem", "incident", "question", "task". |
| `status` | string | no | Initial status: "new", "open", "pending", "hold" (default: "new"). |
| `assignee_id` | string | no | ID of the agent to assign the ticket to. |
| `tags` | array | no | Array of tags to apply to the ticket. |

### Example

```lua
local result = app.integrations.zendesk.zendesk_create_ticket({
  subject = "Login issue"
  description = "User cannot log in to the application."
  priority = "high"
  type = "incident"
})
```

## zendesk_list_users

List Zendesk users with pagination and filtering.
Returns user IDs, names, emails, and roles.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of users per page (default 100, max 100). |
| `page` | integer | no | Page number for pagination (1-indexed). |
| `role` | string | no | Filter by role: "end-user", "agent", "admin". |
| `sort_by` | string | no | Field to sort by (e.g. "name", "created_at"). |
| `sort_order` | string | no | Sort order: "asc" or "desc". |

### Example

```lua
local result = app.integrations.zendesk.zendesk_list_users({
  per_page = 50
  role = "agent"
})
```

## zendesk_get_user

Retrieve a Zendesk user by its ID.
Returns the user's ID, name, email, role, and profile details.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `user_id` | string | yes | Zendesk user ID. |

### Example

```lua
local result = app.integrations.zendesk.zendesk_get_user({
  user_id = "98765"
})
```

## zendesk_list_organizations

List Zendesk organizations with pagination.
Returns organization IDs, names, and created dates.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of organizations per page (default 100, max 100). |
| `page` | integer | no | Page number for pagination (1-indexed). |

### Example

```lua
local result = app.integrations.zendesk.zendesk_list_organizations({
  per_page = 50
})
```

## zendesk_get_current_user

Retrieve the currently authenticated Zendesk user.
Returns the user's ID, name, email, role, and avatar.
Useful for identifying which account or token is in use.

### Example

```lua
local result = app.integrations.zendesk.zendesk_get_current_user({
})
```

---

## Multi-Account Usage

If you have multiple zendesk accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.zendesk.function_name({...})

-- Explicit default (portable across setups)
app.integrations.zendesk.default.function_name({...})

-- Named accounts
app.integrations.zendesk.work.function_name({...})
app.integrations.zendesk.personal.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.zendesk.create_ticket({subject = "example_subject", description = "example_description", priority = "example_priority", type = "example_type", status = "example_status", assignee_id = "example_assignee_id", tags = "example_tags"})
print(result)

Functions

create_ticket Write

Create a new ticket in Zendesk. Requires a subject and description. Optionally set priority, type, status, and assignee. Returns the created ticket with its ID.

Lua path
app.integrations.zendesk.create_ticket
Full name
zendesk.zendesk_create_ticket
ParameterTypeRequiredDescription
subject string yes Subject of the ticket.
description string yes Initial description/body of the ticket.
priority string no Ticket priority: "urgent", "high", "normal", "low".
type string no Ticket type: "problem", "incident", "question", "task".
status string no Initial status: "new", "open", "pending", "hold" (default: "new").
assignee_id string no ID of the agent to assign the ticket to.
tags array no Array of tags to apply to the ticket.
get_current_user Read

Retrieve the currently authenticated Zendesk user. Returns the user's ID, name, email, role, and avatar. Useful for identifying which account or token is in use.

Lua path
app.integrations.zendesk.get_current_user
Full name
zendesk.zendesk_get_current_user
ParameterTypeRequiredDescription
No parameters.
get_ticket Read

Retrieve a Zendesk ticket by its ID. Returns the full ticket including subject, description, status, priority, and metadata.

Lua path
app.integrations.zendesk.get_ticket
Full name
zendesk.zendesk_get_ticket
ParameterTypeRequiredDescription
ticket_id string yes Zendesk ticket ID.
get_user Read

Retrieve a Zendesk user by its ID. Returns the user's ID, name, email, role, and profile details.

Lua path
app.integrations.zendesk.get_user
Full name
zendesk.zendesk_get_user
ParameterTypeRequiredDescription
user_id string yes Zendesk user ID.
list_organizations Read

List Zendesk organizations with pagination. Returns organization IDs, names, and created dates. Use per_page and page for pagination.

Lua path
app.integrations.zendesk.list_organizations
Full name
zendesk.zendesk_list_organizations
ParameterTypeRequiredDescription
per_page integer no Number of organizations per page (default 100, max 100).
page integer no Page number for pagination (1-indexed).
list_tickets Read

List Zendesk tickets with pagination and filtering. Returns ticket IDs, subjects, status, priority, and created dates. Use per_page, page, and status for pagination and filtering.

Lua path
app.integrations.zendesk.list_tickets
Full name
zendesk.zendesk_list_tickets
ParameterTypeRequiredDescription
per_page integer no Number of tickets per page (default 25, max 100).
page integer no Page number for pagination (1-indexed).
sort_by string no Field to sort by (e.g. "created_at", "updated_at", "priority").
sort_order string no Sort order: "asc" or "desc".
status string no Filter by ticket status: "new", "open", "pending", "hold", "solved", "closed".
list_users Read

List Zendesk users with pagination and filtering. Returns user IDs, names, emails, and roles. Use per_page, page, and role for pagination and filtering.

Lua path
app.integrations.zendesk.list_users
Full name
zendesk.zendesk_list_users
ParameterTypeRequiredDescription
per_page integer no Number of users per page (default 100, max 100).
page integer no Page number for pagination (1-indexed).
role string no Filter by role: "end-user", "agent", "admin".
sort_by string no Field to sort by (e.g. "name", "created_at").
sort_order string no Sort order: "asc" or "desc".