KosmoKrator

productivity

Zoho Sheet Lua API for KosmoKrator Agents

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

7 functions 6 read 1 write Manual OAuth token auth
Submit Zoho Sheet feedback View package source

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.

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

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.list_spreadsheets({
  page = 1,
  per_page = 25
})

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

get_spreadsheet

Get details of a specific spreadsheet.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID

Example

local result = app.integrations.zoho_sheet.get_spreadsheet({
  id = "abc123"
})

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

list_worksheets

List all worksheets within a spreadsheet.

Parameters

NameTypeRequiredDescription
idstringyesThe spreadsheet resource ID

Example

local result = app.integrations.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

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.get_worksheet({
  id = "abc123",
  worksheet_id = "Sheet1"
})

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

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.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

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.create_row({
  id = "abc123",
  worksheet_id = "Sheet1",
  data = {
    Name = "John Doe",
    Email = "[email protected]",
    Status = "Active"
  }
})

print("Row created successfully")

get_current_user

Get the authenticated user’s profile information.

Parameters

None.

Example

local result = app.integrations.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

## 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.list_spreadsheets({
  page = 1,
  per_page = 25
})

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

---

## 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.get_spreadsheet({
  id = "abc123"
})

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

---

## 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.list_worksheets({
  id = "abc123"
})

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

---

## 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.get_worksheet({
  id = "abc123",
  worksheet_id = "Sheet1"
})

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

---

## 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.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
```

---

## 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.create_row({
  id = "abc123",
  worksheet_id = "Sheet1",
  data = {
    Name = "John Doe",
    Email = "[email protected]",
    Status = "Active"
  }
})

print("Row created successfully")
```

---

## get_current_user

Get the authenticated user's profile information.

### Parameters

None.

### Example

```lua
local result = app.integrations.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.zoho_sheet_list_spreadsheets({
  page = 1,
  per_page = 1
})
print(result)

Functions

zoho_sheet_list_spreadsheets

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.

Operation
Read read
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).

zoho_sheet_get_spreadsheet

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

Operation
Read read
Full name
zoho_sheet.zoho_sheet_get_spreadsheet
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.

zoho_sheet_list_worksheets

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.

Operation
Read read
Full name
zoho_sheet.zoho_sheet_list_worksheets
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.

zoho_sheet_get_worksheet

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

Operation
Read read
Full name
zoho_sheet.zoho_sheet_get_worksheet
ParameterTypeRequiredDescription
id string yes The spreadsheet resource ID.
worksheet_id string yes The worksheet resource ID.

zoho_sheet_list_rows

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.

Operation
Read read
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).

zoho_sheet_create_row

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.

Operation
Write write
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": "[email protected]", "Age": 30}).

zoho_sheet_get_current_user

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

Operation
Read read
Full name
zoho_sheet.zoho_sheet_get_current_user
ParameterTypeRequiredDescription
No parameters.