KosmoKrator

productivity

Smartsheet Lua API for KosmoKrator Agents

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

12 functions 7 read 5 write Bearer token auth
Submit Smartsheet feedback View package source

Lua Namespace

Agents call this integration through app.integrations.smartsheet.*. Use lua_read_doc("integrations.smartsheet") 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.

Smartsheet — Lua API Reference

Authentication

This integration uses a Smartsheet Personal Access Token. Configure it in your integration settings before using any tools.

smartsheet_list_sheets

List all sheets accessible to the authenticated user.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of sheets to return (default 100, max 100)
pageintegernoPage number for pagination (1-based)

Example

local result = app.integrations.smartsheet.list_sheets({
  limit = 25,
  page = 1
})

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

smartsheet_get_sheet

Get a specific sheet by ID, including its rows and columns.

Parameters

NameTypeRequiredDescription
sheet_idintegeryesThe unique identifier of the sheet
page_sizeintegernoNumber of rows per page (default 100)
pageintegernoPage number for pagination (1-based)

Example

local result = app.integrations.smartsheet.get_sheet({
  sheet_id = 1234567890,
  page_size = 50,
  page = 1
})

print("Sheet: " .. result.name)
for _, col in ipairs(result.columns) do
  print("  Column: " .. col.title .. " (" .. col.type .. ")")
end
for _, row in ipairs(result.rows) do
  for _, cell in ipairs(row.cells) do
    print("  Cell value: " .. tostring(cell.value))
  end
end

smartsheet_create_sheet

Create a new sheet with the specified name and column definitions.

Parameters

NameTypeRequiredDescription
namestringyesThe name for the new sheet
columnsarrayyesArray of column definitions, each with "title" and "type"

Column Types

TEXT_NUMBER, DATE, CHECKBOX, PICKLIST, CONTACT_LIST, DATETIME, DURATION, ABSTRACT_DATETIME, MULTI_CONTACT_LIST, AUTO_NUMBER

Example

local result = app.integrations.smartsheet.create_sheet({
  name = "Project Tracker",
  columns = {
    { title = "Task Name", type = "TEXT_NUMBER", primary = true },
    { title = "Due Date", type = "DATE" },
    { title = "Status", type = "PICKLIST", options = { "Not Started", "In Progress", "Done" } },
    { title = "Complete", type = "CHECKBOX" }
  }
})

print("Created sheet: " .. result.name .. " (ID: " .. result.id .. ")")

smartsheet_add_rows

Add one or more rows to a sheet.

Parameters

NameTypeRequiredDescription
sheet_idintegeryesThe unique identifier of the sheet
rowsarrayyesArray of row objects, each with a "cells" array

Cell Format

Each cell in the "cells" array is an object with "columnId" and "value":

{ "columnId": 123456, "value": "Some text" }

Optional row positioning keys: "toTop", "toBottom", "parentId".

Example

local result = app.integrations.smartsheet.add_rows({
  sheet_id = 1234567890,
  rows = {
    {
      toBottom = true,
      cells = {
        { columnId = 111, value = "Design mockups" },
        { columnId = 222, value = "2026-04-15" },
        { columnId = 333, value = "In Progress" }
      }
    },
    {
      toBottom = true,
      cells = {
        { columnId = 111, value = "API integration" },
        { columnId = 222, value = "2026-04-20" },
        { columnId = 333, value = "Not Started" }
      }
    }
  }
})

print("Added " .. #result.result .. " rows")

smartsheet_update_rows

Update one or more existing rows in a sheet.

Parameters

NameTypeRequiredDescription
sheet_idintegeryesThe unique identifier of the sheet
rowsarrayyesArray of row objects, each must include "id" and updated "cells"

Example

local result = app.integrations.smartsheet.update_rows({
  sheet_id = 1234567890,
  rows = {
    {
      id = 999888777,
      cells = {
        { columnId = 333, value = "Done" }
      }
    }
  }
})

smartsheet_delete_rows

Delete one or more rows from a sheet.

Parameters

NameTypeRequiredDescription
sheet_idintegeryesThe unique identifier of the sheet
row_idsarrayyesArray of row IDs to delete

Example

local result = app.integrations.smartsheet.delete_rows({
  sheet_id = 1234567890,
  row_ids = { 111, 222, 333 }
})

smartsheet_list_columns

List all columns in a sheet.

Parameters

NameTypeRequiredDescription
sheet_idintegeryesThe unique identifier of the sheet

Example

local result = app.integrations.smartsheet.list_columns({
  sheet_id = 1234567890
})

for _, col in ipairs(result.data) do
  print(col.title .. " — type: " .. col.type .. ", ID: " .. col.id)
end

smartsheet_add_column

Add a new column to a sheet.

Parameters

NameTypeRequiredDescription
sheet_idintegeryesThe unique identifier of the sheet
titlestringyesThe title for the new column
typestringyesColumn type (see list below)

Column Types

TEXT_NUMBER, DATE, CHECKBOX, PICKLIST, CONTACT_LIST, DATETIME, DURATION, ABSTRACT_DATETIME, MULTI_CONTACT_LIST, AUTO_NUMBER

Example

local result = app.integrations.smartsheet.add_column({
  sheet_id = 1234567890,
  title = "Priority",
  type = "PICKLIST",
  options = { "High", "Medium", "Low" }
})

print("Created column: " .. result.title .. " (ID: " .. result.id .. ")")

smartsheet_list_workspaces

List all workspaces accessible to the authenticated user.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of workspaces to return (default 100)
pageintegernoPage number for pagination (1-based)

Example

local result = app.integrations.smartsheet.list_workspaces({
  limit = 50
})

for _, ws in ipairs(result.data) do
  print("Workspace: " .. ws.name .. " (ID: " .. ws.id .. ")")
end

smartsheet_get_workspace

Get a specific workspace by ID, including its sheets, reports, and other contents.

Parameters

NameTypeRequiredDescription
workspace_idintegeryesThe unique identifier of the workspace

Example

local result = app.integrations.smartsheet.get_workspace({
  workspace_id = 9876543210
})

print("Workspace: " .. result.name)
if result.sheets then
  for _, sheet in ipairs(result.sheets) do
    print("  Sheet: " .. sheet.name)
  end
end

Search across Smartsheet sheets, reports, and templates.

Parameters

NameTypeRequiredDescription
querystringyesThe search query string
limitintegernoMaximum number of search results to return (default 100)

Example

local result = app.integrations.smartsheet.search({
  query = "budget review",
  limit = 10
})

if result.results then
  for _, item in ipairs(result.results) do
    print("Found: " .. item.text .. " in " .. (item.parentName or "unknown"))
  end
end

smartsheet_get_current_user

Get the currently authenticated user’s profile, including name and email.

Parameters

None.

Example

local result = app.integrations.smartsheet.get_current_user({})

print("Logged in as: " .. result.firstName .. " " .. result.lastName .. " <" .. result.email .. ">")

Multi-Account Usage

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

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

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

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

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

Raw agent markdown 
# Smartsheet — Lua API Reference

## Authentication

This integration uses a Smartsheet Personal Access Token. Configure it in your integration settings before using any tools.

---

## smartsheet_list_sheets

List all sheets accessible to the authenticated user.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of sheets to return (default 100, max 100) |
| `page` | integer | no | Page number for pagination (1-based) |

### Example

```lua
local result = app.integrations.smartsheet.list_sheets({
  limit = 25,
  page = 1
})

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

---

## smartsheet_get_sheet

Get a specific sheet by ID, including its rows and columns.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sheet_id` | integer | yes | The unique identifier of the sheet |
| `page_size` | integer | no | Number of rows per page (default 100) |
| `page` | integer | no | Page number for pagination (1-based) |

### Example

```lua
local result = app.integrations.smartsheet.get_sheet({
  sheet_id = 1234567890,
  page_size = 50,
  page = 1
})

print("Sheet: " .. result.name)
for _, col in ipairs(result.columns) do
  print("  Column: " .. col.title .. " (" .. col.type .. ")")
end
for _, row in ipairs(result.rows) do
  for _, cell in ipairs(row.cells) do
    print("  Cell value: " .. tostring(cell.value))
  end
end
```

---

## smartsheet_create_sheet

Create a new sheet with the specified name and column definitions.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The name for the new sheet |
| `columns` | array | yes | Array of column definitions, each with `"title"` and `"type"` |

### Column Types

`TEXT_NUMBER`, `DATE`, `CHECKBOX`, `PICKLIST`, `CONTACT_LIST`, `DATETIME`, `DURATION`, `ABSTRACT_DATETIME`, `MULTI_CONTACT_LIST`, `AUTO_NUMBER`

### Example

```lua
local result = app.integrations.smartsheet.create_sheet({
  name = "Project Tracker",
  columns = {
    { title = "Task Name", type = "TEXT_NUMBER", primary = true },
    { title = "Due Date", type = "DATE" },
    { title = "Status", type = "PICKLIST", options = { "Not Started", "In Progress", "Done" } },
    { title = "Complete", type = "CHECKBOX" }
  }
})

print("Created sheet: " .. result.name .. " (ID: " .. result.id .. ")")
```

---

## smartsheet_add_rows

Add one or more rows to a sheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sheet_id` | integer | yes | The unique identifier of the sheet |
| `rows` | array | yes | Array of row objects, each with a `"cells"` array |

### Cell Format

Each cell in the `"cells"` array is an object with `"columnId"` and `"value"`:

```json
{ "columnId": 123456, "value": "Some text" }
```

Optional row positioning keys: `"toTop"`, `"toBottom"`, `"parentId"`.

### Example

```lua
local result = app.integrations.smartsheet.add_rows({
  sheet_id = 1234567890,
  rows = {
    {
      toBottom = true,
      cells = {
        { columnId = 111, value = "Design mockups" },
        { columnId = 222, value = "2026-04-15" },
        { columnId = 333, value = "In Progress" }
      }
    },
    {
      toBottom = true,
      cells = {
        { columnId = 111, value = "API integration" },
        { columnId = 222, value = "2026-04-20" },
        { columnId = 333, value = "Not Started" }
      }
    }
  }
})

print("Added " .. #result.result .. " rows")
```

---

## smartsheet_update_rows

Update one or more existing rows in a sheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sheet_id` | integer | yes | The unique identifier of the sheet |
| `rows` | array | yes | Array of row objects, each must include `"id"` and updated `"cells"` |

### Example

```lua
local result = app.integrations.smartsheet.update_rows({
  sheet_id = 1234567890,
  rows = {
    {
      id = 999888777,
      cells = {
        { columnId = 333, value = "Done" }
      }
    }
  }
})
```

---

## smartsheet_delete_rows

Delete one or more rows from a sheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sheet_id` | integer | yes | The unique identifier of the sheet |
| `row_ids` | array | yes | Array of row IDs to delete |

### Example

```lua
local result = app.integrations.smartsheet.delete_rows({
  sheet_id = 1234567890,
  row_ids = { 111, 222, 333 }
})
```

---

## smartsheet_list_columns

List all columns in a sheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sheet_id` | integer | yes | The unique identifier of the sheet |

### Example

```lua
local result = app.integrations.smartsheet.list_columns({
  sheet_id = 1234567890
})

for _, col in ipairs(result.data) do
  print(col.title .. " — type: " .. col.type .. ", ID: " .. col.id)
end
```

---

## smartsheet_add_column

Add a new column to a sheet.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sheet_id` | integer | yes | The unique identifier of the sheet |
| `title` | string | yes | The title for the new column |
| `type` | string | yes | Column type (see list below) |

### Column Types

`TEXT_NUMBER`, `DATE`, `CHECKBOX`, `PICKLIST`, `CONTACT_LIST`, `DATETIME`, `DURATION`, `ABSTRACT_DATETIME`, `MULTI_CONTACT_LIST`, `AUTO_NUMBER`

### Example

```lua
local result = app.integrations.smartsheet.add_column({
  sheet_id = 1234567890,
  title = "Priority",
  type = "PICKLIST",
  options = { "High", "Medium", "Low" }
})

print("Created column: " .. result.title .. " (ID: " .. result.id .. ")")
```

---

## smartsheet_list_workspaces

List all workspaces accessible to the authenticated user.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of workspaces to return (default 100) |
| `page` | integer | no | Page number for pagination (1-based) |

### Example

```lua
local result = app.integrations.smartsheet.list_workspaces({
  limit = 50
})

for _, ws in ipairs(result.data) do
  print("Workspace: " .. ws.name .. " (ID: " .. ws.id .. ")")
end
```

---

## smartsheet_get_workspace

Get a specific workspace by ID, including its sheets, reports, and other contents.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | yes | The unique identifier of the workspace |

### Example

```lua
local result = app.integrations.smartsheet.get_workspace({
  workspace_id = 9876543210
})

print("Workspace: " .. result.name)
if result.sheets then
  for _, sheet in ipairs(result.sheets) do
    print("  Sheet: " .. sheet.name)
  end
end
```

---

## smartsheet_search

Search across Smartsheet sheets, reports, and templates.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | yes | The search query string |
| `limit` | integer | no | Maximum number of search results to return (default 100) |

### Example

```lua
local result = app.integrations.smartsheet.search({
  query = "budget review",
  limit = 10
})

if result.results then
  for _, item in ipairs(result.results) do
    print("Found: " .. item.text .. " in " .. (item.parentName or "unknown"))
  end
end
```

---

## smartsheet_get_current_user

Get the currently authenticated user's profile, including name and email.

### Parameters

None.

### Example

```lua
local result = app.integrations.smartsheet.get_current_user({})

print("Logged in as: " .. result.firstName .. " " .. result.lastName .. " <" .. result.email .. ">")
```

---

## Multi-Account Usage

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

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

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

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

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

Metadata-Derived Lua Example

local result = app.integrations.smartsheet.smartsheet_list_sheets({
  limit = 1,
  page = 1
})
print(result)

Functions

smartsheet_list_sheets

List all sheets accessible to the authenticated Smartsheet user. Returns sheet names and IDs.

Operation
Read read
Full name
smartsheet.smartsheet_list_sheets
ParameterTypeRequiredDescription
limit integer no Maximum number of sheets to return (default 100, max 100).
page integer no Page number for pagination (1-based).

smartsheet_get_sheet

Get a specific Smartsheet sheet by ID, including its rows and columns.

Operation
Read read
Full name
smartsheet.smartsheet_get_sheet
ParameterTypeRequiredDescription
sheet_id integer yes The unique identifier of the sheet to retrieve.
level integer no The nesting level for the response (0–2). Default is 0.
page_size integer no Number of rows per page. Default is 100.
page integer no Page number for pagination (1-based).

smartsheet_create_sheet

Create a new Smartsheet sheet with a specified name and column definitions.

Operation
Write write
Full name
smartsheet.smartsheet_create_sheet
ParameterTypeRequiredDescription
name string yes The name for the new sheet.
columns array yes Array of column definitions. Each column must have "title" and "type". Supported types: TEXT_NUMBER, DATE, CHECKBOX, PICKLIST, CONTACT_LIST, DATETIME, DURATION, MULTI_CONTACT_LIST, AUTO_NUMBER.

smartsheet_add_rows

Add one or more rows to a Smartsheet sheet. Each row should have a "cells" array with objects containing "columnId" and "value".

Operation
Write write
Full name
smartsheet.smartsheet_add_rows
ParameterTypeRequiredDescription
sheet_id integer yes The unique identifier of the sheet to add rows to.
rows array yes Array of row objects. Each row must have a "cells" array with {"columnId": int, "value": mixed}. Optionally include "toTop": true or "toBottom": true.

smartsheet_update_rows

Update one or more existing rows in a Smartsheet sheet. Each row must include its "id" field along with updated cell values.

Operation
Write write
Full name
smartsheet.smartsheet_update_rows
ParameterTypeRequiredDescription
sheet_id integer yes The unique identifier of the sheet containing the rows to update.
rows array yes Array of row objects to update. Each row must have "id" and a "cells" array with {"columnId": int, "value": mixed}.

smartsheet_delete_rows

Delete one or more rows from a Smartsheet sheet by their row IDs.

Operation
Write write
Full name
smartsheet.smartsheet_delete_rows
ParameterTypeRequiredDescription
sheet_id integer yes The unique identifier of the sheet containing the rows to delete.
row_ids array yes Array of row IDs to delete.

smartsheet_list_columns

List all columns in a Smartsheet sheet, including their titles, types, and IDs.

Operation
Read read
Full name
smartsheet.smartsheet_list_columns
ParameterTypeRequiredDescription
sheet_id integer yes The unique identifier of the sheet.
limit integer no Maximum number of columns to return (default 100).
page integer no Page number for pagination (1-based).

smartsheet_add_column

Add a new column to a Smartsheet sheet. Column types include TEXT_NUMBER, DATE, CHECKBOX, PICKLIST, CONTACT_LIST, DATETIME, DURATION, and AUTO_NUMBER.

Operation
Write write
Full name
smartsheet.smartsheet_add_column
ParameterTypeRequiredDescription
sheet_id integer yes The unique identifier of the sheet to add the column to.
title string yes The title for the new column.
type string yes The column type. Supported: TEXT_NUMBER, DATE, CHECKBOX, PICKLIST, CONTACT_LIST, DATETIME, DURATION, ABSTRACT_DATETIME, MULTI_CONTACT_LIST, AUTO_NUMBER.
options array no Optional additional column options. For PICKLIST columns, include "options" (array of string values) and optionally "option" (e.g., "options": ["Yes","No"]). Other options include "symbol", "width", "format", etc.

smartsheet_list_workspaces

List all workspaces accessible to the authenticated Smartsheet user.

Operation
Read read
Full name
smartsheet.smartsheet_list_workspaces
ParameterTypeRequiredDescription
limit integer no Maximum number of workspaces to return (default 100).
page integer no Page number for pagination (1-based).

smartsheet_get_workspace

Get a specific Smartsheet workspace by ID, including its sheets, reports, and other contents.

Operation
Read read
Full name
smartsheet.smartsheet_get_workspace
ParameterTypeRequiredDescription
workspace_id integer yes The unique identifier of the workspace to retrieve.

smartsheet_get_current_user

Get the currently authenticated Smartsheet user's profile, including name and email.

Operation
Read read
Full name
smartsheet.smartsheet_get_current_user
ParameterTypeRequiredDescription
No parameters.