KosmoKrator

productivity

Zoho Sheet Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.zoho_sheet.list_spreadsheets({page = 1, per_page = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("zoho-sheet"))' --json
kosmo integrations:lua --eval 'print(docs.read("zoho-sheet.list_spreadsheets"))' --json

Workflow file

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

workflow.lua 
local zoho_sheet = app.integrations.zoho_sheet
local result = zoho_sheet.list_spreadsheets({page = 1, per_page = 1})

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

MCP-only Lua

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

Zoho Sheet — Lua API Reference

zoho_sheet_list_spreadsheets

List all spreadsheets accessible to the authenticated user.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (default: 1)
per_pageintegernoNumber of spreadsheets per page (default: 25, max: 100)

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_list_spreadsheets({
  page = 1,
  per_page = 25
})

for _, sheet in ipairs(result.spreadsheets) do
  print(sheet.name .. " (ID: " .. sheet.resource_id .. ")")
end

zoho_sheet_get_spreadsheet

Get details of a specific spreadsheet.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_get_spreadsheet({
  id = "abc123"
})

print("Spreadsheet: " .. result.name)
print("Worksheets: " .. #result.worksheets)

zoho_sheet_list_worksheets

List all worksheets within a spreadsheet.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_list_worksheets({
  id = "abc123"
})

for _, ws in ipairs(result.worksheets) do
  print(ws.name .. " — " .. ws.row_count .. " rows, " .. ws.column_count .. " columns")
end

zoho_sheet_get_worksheet

Get details of a specific worksheet.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID
worksheet_idstringyesThe worksheet resource ID

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_get_worksheet({
  id = "abc123",
  worksheet_id = "Sheet1"
})

print("Worksheet: " .. result.name)
print("Rows: " .. result.row_count)

zoho_sheet_list_rows

List rows in a worksheet with pagination.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID
worksheet_idstringyesThe worksheet resource ID
pageintegernoPage number for pagination (default: 1)
per_pageintegernoNumber of rows per page (default: 25, max: 100)

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_list_rows({
  id = "abc123",
  worksheet_id = "Sheet1",
  page = 1,
  per_page = 10
})

for _, row in ipairs(result.rows) do
  print(row.Name .. " — " .. row.Email)
end

zoho_sheet_create_row

Create a new row in a worksheet.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID
worksheet_idstringyesThe worksheet resource ID
dataobjectyesRow data as key-value pairs (keys = column headers)

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_create_row({
  id = "abc123",
  worksheet_id = "Sheet1",
  data = {
    Name = "John Doe",
    Email = "john@example.com",
    Status = "Active"
  }
})

print("Row created successfully")

zoho_sheet_get_current_user

Get the authenticated user’s profile information.

Parameters

None.

Example

local result = app.integrations["zoho-sheet"].zoho_sheet_get_current_user({})

print("User: " .. result.display_name)
print("Email: " .. result.email)

Multi-Account Usage

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

-- Default account (always works)
app.integrations["zoho-sheet"].function_name({...})

-- Explicit default (portable across setups)
app.integrations["zoho-sheet"].default.function_name({...})

-- Named accounts
app.integrations["zoho-sheet"].work.function_name({...})
app.integrations["zoho-sheet"].personal.function_name({...})

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

Raw agent markdown 
# Zoho Sheet — Lua API Reference

## zoho_sheet_list_spreadsheets

List all spreadsheets accessible to the authenticated user.

### Parameters

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

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_list_spreadsheets({
  page = 1,
  per_page = 25
})

for _, sheet in ipairs(result.spreadsheets) do
  print(sheet.name .. " (ID: " .. sheet.resource_id .. ")")
end
```

---

## zoho_sheet_get_spreadsheet

Get details of a specific spreadsheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The spreadsheet resource ID |

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_get_spreadsheet({
  id = "abc123"
})

print("Spreadsheet: " .. result.name)
print("Worksheets: " .. #result.worksheets)
```

---

## zoho_sheet_list_worksheets

List all worksheets within a spreadsheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The spreadsheet resource ID |

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_list_worksheets({
  id = "abc123"
})

for _, ws in ipairs(result.worksheets) do
  print(ws.name .. " — " .. ws.row_count .. " rows, " .. ws.column_count .. " columns")
end
```

---

## zoho_sheet_get_worksheet

Get details of a specific worksheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The spreadsheet resource ID |
| `worksheet_id` | string | yes | The worksheet resource ID |

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_get_worksheet({
  id = "abc123",
  worksheet_id = "Sheet1"
})

print("Worksheet: " .. result.name)
print("Rows: " .. result.row_count)
```

---

## zoho_sheet_list_rows

List rows in a worksheet with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The spreadsheet resource ID |
| `worksheet_id` | string | yes | The worksheet resource ID |
| `page` | integer | no | Page number for pagination (default: 1) |
| `per_page` | integer | no | Number of rows per page (default: 25, max: 100) |

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_list_rows({
  id = "abc123",
  worksheet_id = "Sheet1",
  page = 1,
  per_page = 10
})

for _, row in ipairs(result.rows) do
  print(row.Name .. " — " .. row.Email)
end
```

---

## zoho_sheet_create_row

Create a new row in a worksheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The spreadsheet resource ID |
| `worksheet_id` | string | yes | The worksheet resource ID |
| `data` | object | yes | Row data as key-value pairs (keys = column headers) |

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_create_row({
  id = "abc123",
  worksheet_id = "Sheet1",
  data = {
    Name = "John Doe",
    Email = "john@example.com",
    Status = "Active"
  }
})

print("Row created successfully")
```

---

## zoho_sheet_get_current_user

Get the authenticated user's profile information.

### Parameters

None.

### Example

```lua
local result = app.integrations["zoho-sheet"].zoho_sheet_get_current_user({})

print("User: " .. result.display_name)
print("Email: " .. result.email)
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations["zoho-sheet"].function_name({...})

-- Explicit default (portable across setups)
app.integrations["zoho-sheet"].default.function_name({...})

-- Named accounts
app.integrations["zoho-sheet"].work.function_name({...})
app.integrations["zoho-sheet"].personal.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.zoho_sheet.list_spreadsheets({page = 1, per_page = 1})
print(result)

Functions

list_spreadsheets Read

List all spreadsheets accessible to the authenticated Zoho Sheet user. Returns spreadsheet names, IDs, and metadata. Use this to discover available spreadsheets before querying worksheets or rows.

Lua path
app.integrations.zoho_sheet.list_spreadsheets
Full name
zoho-sheet.zoho_sheet_list_spreadsheets
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of spreadsheets per page (default: 25, max: 100).
get_spreadsheet Read

Get details of a specific Zoho Sheet spreadsheet by its ID. Returns spreadsheet metadata including name, description, and associated worksheets.

Lua path
app.integrations.zoho_sheet.get_spreadsheet
Full name
zoho-sheet.zoho_sheet_get_spreadsheet
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.
list_worksheets Read

List all worksheets within a Zoho Sheet spreadsheet. Returns worksheet names, IDs, and metadata like row/column counts. Use this to discover worksheets before reading or writing row data.

Lua path
app.integrations.zoho_sheet.list_worksheets
Full name
zoho-sheet.zoho_sheet_list_worksheets
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.
get_worksheet Read

Get details of a specific worksheet within a Zoho Sheet spreadsheet. Returns worksheet metadata including name, row/column counts, and header information.

Lua path
app.integrations.zoho_sheet.get_worksheet
Full name
zoho-sheet.zoho_sheet_get_worksheet
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.
worksheet_id string yes The worksheet resource ID.
list_rows Read

List rows in a Zoho Sheet worksheet with pagination. Returns row data as key-value pairs using column headers as keys. Use this to read data from a specific worksheet.

Lua path
app.integrations.zoho_sheet.list_rows
Full name
zoho-sheet.zoho_sheet_list_rows
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.
worksheet_id string yes The worksheet resource ID.
page integer no Page number for pagination (default: 1).
per_page integer no Number of rows per page (default: 25, max: 100).
create_row Write

Create a new row in a Zoho Sheet worksheet. Provide column header names as keys and their values. The row will be appended to the end of the worksheet.

Lua path
app.integrations.zoho_sheet.create_row
Full name
zoho-sheet.zoho_sheet_create_row
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.
worksheet_id string yes The worksheet resource ID.
data object yes Row data as key-value pairs. Keys must match column headers in the worksheet (e.g., {"Name": "John", "Email": "john@example.com", "Age": 30}).
get_current_user Read

Get the authenticated Zoho Sheet user's profile information. Returns display name, email, and account details. Useful for verifying which account is connected.

Lua path
app.integrations.zoho_sheet.get_current_user
Full name
zoho-sheet.zoho_sheet_get_current_user
ParameterTypeRequiredDescription
No parameters.