KosmoKrator

data

Microsoft OneDrive Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.one_drive.list_files({top = 1, skip_token = "example_skip_token"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("one-drive"))' --json
kosmo integrations:lua --eval 'print(docs.read("one-drive.list_files"))' --json

Workflow file

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

workflow.lua 
local one_drive = app.integrations.one_drive
local result = one_drive.list_files({top = 1, skip_token = "example_skip_token"})

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

MCP-only Lua

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

Microsoft OneDrive Lua API Reference

Namespace: app.integrations["one-drive"]

This integration wraps Microsoft OneDrive through Microsoft Graph v1.0. Use it to inspect the signed-in user’s drive, manage DriveItems, upload and download content, create sharing links, list permissions, track changes, and call relative Graph paths when a named tool does not exist.

Drive And Items

local drive = app.integrations["one-drive"].onedrive_get_drive({})

local root = app.integrations["one-drive"].onedrive_list_files({
  top = 50
})

local children = app.integrations["one-drive"].onedrive_list_children({
  parent_id = "01ABCDEFOLDERID",
  top = 25
})

local item = app.integrations["one-drive"].onedrive_get_file({
  id = "01ABCDEITEMID"
})

list_files is a root-folder convenience wrapper. list_children can list root children when parent_id is omitted, or children of a specific folder item when parent_id is provided.

Create, Update, Copy, Delete

local folder = app.integrations["one-drive"].onedrive_create_folder({
  name = "Reports",
  conflict_behavior = "rename"
})

local renamed = app.integrations["one-drive"].onedrive_update_item({
  id = "01ABCDEITEMID",
  name = "Q4 report.xlsx"
})

local copy = app.integrations["one-drive"].onedrive_copy_item({
  id = "01ABCDEITEMID",
  name = "Q4 report copy.xlsx"
})

local deleted = app.integrations["one-drive"].onedrive_delete_item({
  id = "01ABCDEITEMID"
})

update_item also accepts parent_reference for Graph move operations and payload for official DriveItem update fields. copy_item is asynchronous; Microsoft Graph usually returns a monitor URL.

Upload And Download

local uploaded = app.integrations["one-drive"].onedrive_upload_file({
  path = "Reports/summary.txt",
  content = "Quarterly summary",
  content_type = "text/plain"
})

local file = app.integrations["one-drive"].onedrive_download_file({
  id = uploaded.id
})

Simple upload is intended for small files. For large upload sessions, use the generic API tools with the documented Graph upload-session endpoint.

Search, Delta, Thumbnails

local matches = app.integrations["one-drive"].onedrive_search({
  query = "quarterly report"
})

local changes = app.integrations["one-drive"].onedrive_delta({})

local thumbs = app.integrations["one-drive"].onedrive_list_thumbnails({
  id = "01ABCDEITEMID"
})

Delta responses may include @odata.nextLink or @odata.deltaLink. Continue by calling the relative path from those links with api_get.

Sharing And Permissions

local link = app.integrations["one-drive"].onedrive_create_sharing_link({
  id = "01ABCDEITEMID",
  type = "view",
  scope = "organization"
})

local permissions = app.integrations["one-drive"].onedrive_list_permissions({
  id = "01ABCDEITEMID"
})

app.integrations["one-drive"].onedrive_delete_permission({
  item_id = "01ABCDEITEMID",
  permission_id = "perm-id"
})

Sharing capabilities depend on tenant policy and token scopes. Prefer organization-scoped links unless anonymous links are explicitly allowed.

Generic Graph API Tools

Use api_get, api_post, api_patch, and api_delete for documented Microsoft Graph paths that are not wrapped yet. Absolute URLs are rejected; pass paths such as /me/drive/root/delta, not full URLs.

local raw = app.integrations["one-drive"].onedrive_api_get({
  path = "/me/drive/recent"
})

local created = app.integrations["one-drive"].onedrive_api_post({
  path = "/me/drive/root/children",
  payload = {
    name = "Archive",
    folder = {}
  }
})

Account

get_current_user returns the signed-in Microsoft Graph user profile. Multi-account namespaces expose the same tools:

app.integrations["one-drive"].onedrive_list_files({})
app.integrations["one-drive"].default.onedrive_list_files({})
app.integrations["one-drive"].work.onedrive_list_files({})
Raw agent markdown 
# Microsoft OneDrive Lua API Reference

Namespace: `app.integrations["one-drive"]`

This integration wraps Microsoft OneDrive through Microsoft Graph v1.0. Use it to inspect the signed-in user's drive, manage DriveItems, upload and download content, create sharing links, list permissions, track changes, and call relative Graph paths when a named tool does not exist.

## Drive And Items

```lua
local drive = app.integrations["one-drive"].onedrive_get_drive({})

local root = app.integrations["one-drive"].onedrive_list_files({
  top = 50
})

local children = app.integrations["one-drive"].onedrive_list_children({
  parent_id = "01ABCDEFOLDERID",
  top = 25
})

local item = app.integrations["one-drive"].onedrive_get_file({
  id = "01ABCDEITEMID"
})
```

`list_files` is a root-folder convenience wrapper. `list_children` can list root children when `parent_id` is omitted, or children of a specific folder item when `parent_id` is provided.

## Create, Update, Copy, Delete

```lua
local folder = app.integrations["one-drive"].onedrive_create_folder({
  name = "Reports",
  conflict_behavior = "rename"
})

local renamed = app.integrations["one-drive"].onedrive_update_item({
  id = "01ABCDEITEMID",
  name = "Q4 report.xlsx"
})

local copy = app.integrations["one-drive"].onedrive_copy_item({
  id = "01ABCDEITEMID",
  name = "Q4 report copy.xlsx"
})

local deleted = app.integrations["one-drive"].onedrive_delete_item({
  id = "01ABCDEITEMID"
})
```

`update_item` also accepts `parent_reference` for Graph move operations and `payload` for official DriveItem update fields. `copy_item` is asynchronous; Microsoft Graph usually returns a monitor URL.

## Upload And Download

```lua
local uploaded = app.integrations["one-drive"].onedrive_upload_file({
  path = "Reports/summary.txt",
  content = "Quarterly summary",
  content_type = "text/plain"
})

local file = app.integrations["one-drive"].onedrive_download_file({
  id = uploaded.id
})
```

Simple upload is intended for small files. For large upload sessions, use the generic API tools with the documented Graph upload-session endpoint.

## Search, Delta, Thumbnails

```lua
local matches = app.integrations["one-drive"].onedrive_search({
  query = "quarterly report"
})

local changes = app.integrations["one-drive"].onedrive_delta({})

local thumbs = app.integrations["one-drive"].onedrive_list_thumbnails({
  id = "01ABCDEITEMID"
})
```

Delta responses may include `@odata.nextLink` or `@odata.deltaLink`. Continue by calling the relative path from those links with `api_get`.

## Sharing And Permissions

```lua
local link = app.integrations["one-drive"].onedrive_create_sharing_link({
  id = "01ABCDEITEMID",
  type = "view",
  scope = "organization"
})

local permissions = app.integrations["one-drive"].onedrive_list_permissions({
  id = "01ABCDEITEMID"
})

app.integrations["one-drive"].onedrive_delete_permission({
  item_id = "01ABCDEITEMID",
  permission_id = "perm-id"
})
```

Sharing capabilities depend on tenant policy and token scopes. Prefer organization-scoped links unless anonymous links are explicitly allowed.

## Generic Graph API Tools

Use `api_get`, `api_post`, `api_patch`, and `api_delete` for documented Microsoft Graph paths that are not wrapped yet. Absolute URLs are rejected; pass paths such as `/me/drive/root/delta`, not full URLs.

```lua
local raw = app.integrations["one-drive"].onedrive_api_get({
  path = "/me/drive/recent"
})

local created = app.integrations["one-drive"].onedrive_api_post({
  path = "/me/drive/root/children",
  payload = {
    name = "Archive",
    folder = {}
  }
})
```

## Account

`get_current_user` returns the signed-in Microsoft Graph user profile. Multi-account namespaces expose the same tools:

```lua
app.integrations["one-drive"].onedrive_list_files({})
app.integrations["one-drive"].default.onedrive_list_files({})
app.integrations["one-drive"].work.onedrive_list_files({})
```
Metadata-derived Lua example 
local result = app.integrations.one_drive.list_files({top = 1, skip_token = "example_skip_token"})
print(result)

Functions

list_files Read

List files and folders in the root of the user's OneDrive. Returns item names, IDs, sizes, and metadata. Use the item ID with onedrive_get_file or onedrive_download_file for details or content.

Lua path
app.integrations.one_drive.list_files
Full name
one-drive.onedrive_list_files
ParameterTypeRequiredDescription
top integer no Maximum number of items to return (default: 100, max: 999).
skip_token string no Pagination token from a previous response to fetch the next page of results.
get_file Read

Get detailed metadata for a specific file or folder in OneDrive by its item ID. Returns name, size, dates, MIME type, and download URL.

Lua path
app.integrations.one_drive.get_file
Full name
one-drive.onedrive_get_file
ParameterTypeRequiredDescription
id string yes The unique identifier of the drive item (obtained from onedrive_list_files or onedrive_list_shared).
get Read

Get metadata for the signed-in user's default OneDrive, including drive ID, owner, quota, and drive type.

Lua path
app.integrations.one_drive.get
Full name
one-drive.onedrive_get_drive
ParameterTypeRequiredDescription
No parameters.
list_children Read

List files and folders under the root folder or under a specific OneDrive parent item.

Lua path
app.integrations.one_drive.list_children
Full name
one-drive.onedrive_list_children
ParameterTypeRequiredDescription
parent_id string no Optional parent folder item ID. Omit to list root children.
top integer no Maximum number of items to return (default: 100, max: 999).
skip_token string no Pagination token from a previous response.
create_folder Write

Create a folder in OneDrive using the Microsoft Graph DriveItem children endpoint.

Lua path
app.integrations.one_drive.create_folder
Full name
one-drive.onedrive_create_folder
ParameterTypeRequiredDescription
name string yes Folder name.
parent_id string no Optional parent folder item ID. Omit to create in root.
conflict_behavior string no Conflict behavior. Defaults to rename.
update_item Write

Update OneDrive file or folder metadata. Use name to rename, parent_reference to move, or payload for official Graph fields.

Lua path
app.integrations.one_drive.update_item
Full name
one-drive.onedrive_update_item
ParameterTypeRequiredDescription
id string yes Drive item ID.
name string no New item name.
parent_reference object no Graph parentReference object for moving an item.
payload object no Additional Graph DriveItem update fields.
delete_item Write

Delete a OneDrive file or folder by drive item ID.

Lua path
app.integrations.one_drive.delete_item
Full name
one-drive.onedrive_delete_item
ParameterTypeRequiredDescription
id string yes Drive item ID to delete.
copy_item Write

Copy a OneDrive file or folder asynchronously. Optionally provide a new name and parentReference.

Lua path
app.integrations.one_drive.copy_item
Full name
one-drive.onedrive_copy_item
ParameterTypeRequiredDescription
id string yes Drive item ID to copy.
name string no Optional new name for the copy.
parent_reference object no Optional Graph parentReference object for the destination folder.
include_all_version_history boolean no Whether to include full version history when supported.
payload object no Additional official Graph copy request fields.
upload_file Write

Upload a file to OneDrive. Specify the destination path and file content. Creates the file if it does not exist, or replaces it if it does. Supports files up to 4 MB via the simple upload API.

Lua path
app.integrations.one_drive.upload_file
Full name
one-drive.onedrive_upload_file
ParameterTypeRequiredDescription
path string yes The destination path in OneDrive, relative to the root (e.g., "Documents/report.txt" or "photos/image.png").
content string yes The content of the file to upload.
content_type string no The MIME type of the file (e.g., "text/plain", "application/json", "image/png"). Defaults to "application/octet-stream".
download_file Read

Download a file's content from OneDrive by its drive item ID. Returns the raw file content. Use onedrive_list_files or onedrive_get_file to find the item ID.

Lua path
app.integrations.one_drive.download_file
Full name
one-drive.onedrive_download_file
ParameterTypeRequiredDescription
id string yes The unique identifier of the drive item to download.
list_shared Read

List files and folders that have been shared with the current user. Returns item names, IDs, sizes, and metadata for shared content.

Lua path
app.integrations.one_drive.list_shared
Full name
one-drive.onedrive_list_shared
ParameterTypeRequiredDescription
top integer no Maximum number of items to return (default: 100, max: 999).
skip_token string no Pagination token from a previous response to fetch the next page of results.
delta Read

List changes in the signed-in user's OneDrive. Continue with @odata.nextLink or @odata.deltaLink values returned by Graph.

Lua path
app.integrations.one_drive.delta
Full name
one-drive.onedrive_delta
ParameterTypeRequiredDescription
params object no Optional delta query parameters. For exact nextLink URLs, use onedrive_api_get with the relative path from the link.
list_thumbnails Read

List thumbnail sets for a OneDrive file or folder item.

Lua path
app.integrations.one_drive.list_thumbnails
Full name
one-drive.onedrive_list_thumbnails
ParameterTypeRequiredDescription
id string yes Drive item ID.
list_permissions Read

List sharing permissions for a OneDrive file or folder.

Lua path
app.integrations.one_drive.list_permissions
Full name
one-drive.onedrive_list_permissions
ParameterTypeRequiredDescription
id string yes Drive item ID.
delete_permission Write

Delete a sharing permission from a OneDrive file or folder.

Lua path
app.integrations.one_drive.delete_permission
Full name
one-drive.onedrive_delete_permission
ParameterTypeRequiredDescription
item_id string yes Drive item ID.
permission_id string yes Permission ID to delete.
get_current_user Read

Get the profile of the currently authenticated Microsoft user. Returns display name, email, job title, and other profile details.

Lua path
app.integrations.one_drive.get_current_user
Full name
one-drive.onedrive_get_current_user
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a relative Microsoft Graph GET path such as "/me/drive". Absolute URLs are rejected.

Lua path
app.integrations.one_drive.api_get
Full name
one-drive.onedrive_api_get
ParameterTypeRequiredDescription
path string yes Relative Graph path, with or without leading slash.
params object no Query parameters.
api_post Write

Call a relative Microsoft Graph POST path with a JSON body. Absolute URLs are rejected.

Lua path
app.integrations.one_drive.api_post
Full name
one-drive.onedrive_api_post
ParameterTypeRequiredDescription
path string yes Relative Graph path, with or without leading slash.
payload object no JSON request body.
api_patch Write

Call a relative Microsoft Graph PATCH path with a JSON body. Absolute URLs are rejected.

Lua path
app.integrations.one_drive.api_patch
Full name
one-drive.onedrive_api_patch
ParameterTypeRequiredDescription
path string yes Relative Graph path, with or without leading slash.
payload object no JSON request body.
api_delete Write

Call a relative Microsoft Graph DELETE path. Absolute URLs are rejected.

Lua path
app.integrations.one_drive.api_delete
Full name
one-drive.onedrive_api_delete
ParameterTypeRequiredDescription
path string yes Relative Graph path, with or without leading slash.
payload object no Optional JSON request body.