KosmoKrator

productivity

Google Docs Lua API for KosmoKrator Agents

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

7 functions 5 read 2 write Manual OAuth token auth
Submit Google Docs feedback View package source

Lua Namespace

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

Google Docs — Lua API Reference

list_documents

List Google Docs documents visible to the authenticated user.

Parameters

NameTypeRequiredDescription
pageSizeintegernoMax results per page (default: 100, max: 1000)
pageTokenstringnoToken for the next page of results
qstringnoDrive API query string for filtering (defaults to Google Docs mimeType)

Query Examples

-- Filter by name
app.integrations["google-docs"].list_documents({
  q = "name contains 'report'"
})

-- Filter by modification time
app.integrations["google-docs"].list_documents({
  q = "modifiedTime > '2025-01-01T00:00:00'"
})

-- Combine filters
app.integrations["google-docs"].list_documents({
  q = "name contains 'meeting' and modifiedTime > '2025-06-01T00:00:00'"
})

Response

Returns an array of documents with id, name, owners, createdTime, modifiedTime, and webViewLink. If there are more results, nextPageToken is included for pagination.

get_document

Get the full content and structure of a Google Docs document.

Parameters

NameTypeRequiredDescription
documentIdstringyesThe document ID (from the document URL)

Example

local doc = app.integrations["google-docs"].get_document({
  documentId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
})

print(doc.title)
print(doc.plainText)

Response

Returns documentId, title, revisionId, plainText (extracted text content), and raw (full API response with styling and structure).

create_document

Create a new Google Docs document.

Parameters

NameTypeRequiredDescription
titlestringyesTitle for the new document

Example

local result = app.integrations["google-docs"].create_document({
  title = "Project Meeting Notes"
})

print("Created: " .. result.editUrl)

Response

Returns documentId, title, revisionId, and editUrl.

batch_update

Send batch update requests to a document (insert text, styling, etc.).

Parameters

NameTypeRequiredDescription
documentIdstringyesThe document ID to update
requestsarrayyesArray of Google Docs API request objects

Common Request Types

Request TypeDescription
insertTextInsert text at a specific location
updateTextStyleChange font, size, bold, italic, etc.
createParagraphBulletsAdd bullet points to paragraphs
updateParagraphStyleChange alignment, spacing, etc.
deleteContentRangeDelete content in a range

Example — Insert text at end of document

app.integrations["google-docs"].batch_update({
  documentId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  requests = {
    {
      insertText = {
        location = { endIndex = 1 },
        text = "Hello, world!\n"
      }
    }
  }
})

Response

Returns documentId, replies (per-request responses), and writeControl.

list_permissions

List all permissions (sharing settings) for a Google Docs document.

Parameters

NameTypeRequiredDescription
fileIdstringyesThe document ID
pageSizeintegernoMax results per page (default: 100)

Example

local result = app.integrations["google-docs"].list_permissions({
  fileId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
})

for _, perm in ipairs(result.permissions) do
  print(perm.emailAddress .. " — " .. perm.role)
end

Response

Returns permissions array with id, type, emailAddress, role, and displayName.

get_permission

Get details of a specific permission for a document.

Parameters

NameTypeRequiredDescription
fileIdstringyesThe document ID
permissionIdstringyesThe permission ID (from list_permissions)

Example

local perm = app.integrations["google-docs"].get_permission({
  fileId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  permissionId = "1234567890"
})

print(perm.emailAddress .. " (" .. perm.role .. ")")

get_current_user

Get the authenticated Google user’s profile information.

Parameters

None required.

Example

local user = app.integrations["google-docs"].get_current_user({})

print("Connected as: " .. user.email .. " (" .. user.name .. ")")

Response

Returns id, email, name, givenName, familyName, picture, locale, and verifiedEmail.

Multi-Account Usage

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

-- Default account (always works)
app.integrations["google-docs"].list_documents({})

-- Explicit default (portable across setups)
app.integrations["google-docs"].default.list_documents({})

-- Named accounts
app.integrations["google-docs"].work.list_documents({})
app.integrations["google-docs"].personal.list_documents({})

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

Raw agent markdown 
# Google Docs — Lua API Reference

## list_documents

List Google Docs documents visible to the authenticated user.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pageSize` | integer | no | Max results per page (default: 100, max: 1000) |
| `pageToken` | string | no | Token for the next page of results |
| `q` | string | no | Drive API query string for filtering (defaults to Google Docs mimeType) |

### Query Examples

```lua
-- Filter by name
app.integrations["google-docs"].list_documents({
  q = "name contains 'report'"
})

-- Filter by modification time
app.integrations["google-docs"].list_documents({
  q = "modifiedTime > '2025-01-01T00:00:00'"
})

-- Combine filters
app.integrations["google-docs"].list_documents({
  q = "name contains 'meeting' and modifiedTime > '2025-06-01T00:00:00'"
})
```

### Response

Returns an array of documents with `id`, `name`, `owners`, `createdTime`, `modifiedTime`, and `webViewLink`. If there are more results, `nextPageToken` is included for pagination.

---

## get_document

Get the full content and structure of a Google Docs document.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `documentId` | string | yes | The document ID (from the document URL) |

### Example

```lua
local doc = app.integrations["google-docs"].get_document({
  documentId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
})

print(doc.title)
print(doc.plainText)
```

### Response

Returns `documentId`, `title`, `revisionId`, `plainText` (extracted text content), and `raw` (full API response with styling and structure).

---

## create_document

Create a new Google Docs document.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | yes | Title for the new document |

### Example

```lua
local result = app.integrations["google-docs"].create_document({
  title = "Project Meeting Notes"
})

print("Created: " .. result.editUrl)
```

### Response

Returns `documentId`, `title`, `revisionId`, and `editUrl`.

---

## batch_update

Send batch update requests to a document (insert text, styling, etc.).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `documentId` | string | yes | The document ID to update |
| `requests` | array | yes | Array of Google Docs API request objects |

### Common Request Types

| Request Type | Description |
|-------------|-------------|
| `insertText` | Insert text at a specific location |
| `updateTextStyle` | Change font, size, bold, italic, etc. |
| `createParagraphBullets` | Add bullet points to paragraphs |
| `updateParagraphStyle` | Change alignment, spacing, etc. |
| `deleteContentRange` | Delete content in a range |

### Example — Insert text at end of document

```lua
app.integrations["google-docs"].batch_update({
  documentId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  requests = {
    {
      insertText = {
        location = { endIndex = 1 },
        text = "Hello, world!\n"
      }
    }
  }
})
```

### Response

Returns `documentId`, `replies` (per-request responses), and `writeControl`.

---

## list_permissions

List all permissions (sharing settings) for a Google Docs document.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `fileId` | string | yes | The document ID |
| `pageSize` | integer | no | Max results per page (default: 100) |

### Example

```lua
local result = app.integrations["google-docs"].list_permissions({
  fileId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"
})

for _, perm in ipairs(result.permissions) do
  print(perm.emailAddress .. " — " .. perm.role)
end
```

### Response

Returns `permissions` array with `id`, `type`, `emailAddress`, `role`, and `displayName`.

---

## get_permission

Get details of a specific permission for a document.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `fileId` | string | yes | The document ID |
| `permissionId` | string | yes | The permission ID (from list_permissions) |

### Example

```lua
local perm = app.integrations["google-docs"].get_permission({
  fileId = "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
  permissionId = "1234567890"
})

print(perm.emailAddress .. " (" .. perm.role .. ")")
```

---

## get_current_user

Get the authenticated Google user's profile information.

### Parameters

None required.

### Example

```lua
local user = app.integrations["google-docs"].get_current_user({})

print("Connected as: " .. user.email .. " (" .. user.name .. ")")
```

### Response

Returns `id`, `email`, `name`, `givenName`, `familyName`, `picture`, `locale`, and `verifiedEmail`.

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations["google-docs"].list_documents({})

-- Explicit default (portable across setups)
app.integrations["google-docs"].default.list_documents({})

-- Named accounts
app.integrations["google-docs"].work.list_documents({})
app.integrations["google-docs"].personal.list_documents({})
```

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

Metadata-Derived Lua Example

local result = app.integrations.google_docs.gdocs_list_documents({
  pageSize = 1,
  pageToken = "example_pageToken",
  q = "example_q"
})
print(result)

Functions

gdocs_list_documents

List Google Docs documents visible to the authenticated user. Returns document IDs, names, owners, and modification times. Supports pagination and custom Drive API query filters.

Operation
Read read
Full name
google-docs.gdocs_list_documents
ParameterTypeRequiredDescription
pageSize integer no Maximum number of documents to return per page (default: 100, max: 1000).
pageToken string no Token for the next page of results, from a previous response.
q string no Drive API query string for filtering. Defaults to mimeType="application/vnd.google-apps.document". Example: "name contains 'report' and modifiedTime > '2025-01-01'".

gdocs_get_document

Get the full content and structure of a Google Docs document by its ID. Returns the document title, body content (paragraphs, text runs), and styling information.

Operation
Read read
Full name
google-docs.gdocs_get_document
ParameterTypeRequiredDescription
documentId string yes The ID of the Google Docs document. Can be extracted from the document URL: https://docs.google.com/document/d/{documentId}/edit

gdocs_create_document

Create a new Google Docs document with a given title. Returns the document ID and a link to edit the document in the browser.

Operation
Write write
Full name
google-docs.gdocs_create_document
ParameterTypeRequiredDescription
title string yes The title for the new document.

gdocs_batch_update

Send batch update requests to a Google Docs document. Supports inserting text, updating text styles, creating paragraphs, and other document modifications. Each request in the array is a Google Docs API request object.

Operation
Write write
Full name
google-docs.gdocs_batch_update
ParameterTypeRequiredDescription
documentId string yes The ID of the document to update.
requests array yes Array of Google Docs API request objects. Each request is an object with one key (e.g., insertText, updateTextStyle, createParagraphBullets). See Google Docs API reference for all request types.

gdocs_list_permissions

List all permissions (sharing settings) for a Google Docs document. Returns who has access, their roles (owner, writer, reader), and their email addresses.

Operation
Read read
Full name
google-docs.gdocs_list_permissions
ParameterTypeRequiredDescription
fileId string yes The ID of the Google Docs document (same as the document ID).
pageSize integer no Maximum number of permissions to return per page (default: 100).

gdocs_get_permission

Get details of a specific permission for a Google Docs document. Returns the permission type, role, and email address for a single permission entry.

Operation
Read read
Full name
google-docs.gdocs_get_permission
ParameterTypeRequiredDescription
fileId string yes The ID of the Google Docs document.
permissionId string yes The ID of the permission to retrieve. Obtain this from gdocs_list_permissions.

gdocs_get_current_user

Get the authenticated Google user's profile information. Returns user ID, email address, display name, and profile picture URL. Use this to verify which Google account is being used.

Operation
Read read
Full name
google-docs.gdocs_get_current_user
ParameterTypeRequiredDescription
No parameters.