KosmoKrator

data

Payload CMS Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.payload_cms.*. Use lua_read_doc("integrations.payload-cms") 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 Payload CMS workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.payload_cms.list_collections({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("payload-cms"))' --json
kosmo integrations:lua --eval 'print(docs.read("payload-cms.list_collections"))' --json

Workflow file

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

workflow.lua 
local payload_cms = app.integrations.payload_cms
local result = payload_cms.list_collections({})

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

MCP-only Lua

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

Client for the Payload CMS REST API covering collections, documents, and user management — Lua API Reference

payload_cms_list_collections

List all collections defined in the Payload CMS instance.

Example

local result = app.integrations.payload_cms.payload_cms_list_collections({
})

payload_cms_get_collection

Get detailed information about a specific collection by its slug.

Parameters

NameTypeRequiredDescription
slugstringyesThe slug of the collection to retrieve.

Example

local result = app.integrations.payload_cms.payload_cms_get_collection({
  slug = ""
})

payload_cms_list_documents

List documents in a Payload CMS collection with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
collectionstringyesThe collection slug to query.
limitintegernoMaximum number of documents to return (default 10).
pageintegernoPage number for pagination (default 1).
sortstringnoSort field. Prefix with ”-” for descending. E.g. “createdAt” or “-updatedAt”.
wherestringnoJSON object for filtering. E.g. ’{“title”:{“equals”:“Hello”}}’.

Example

local result = app.integrations.payload_cms.payload_cms_list_documents({
  collection = ""
  limit = 10
  page = 1
})

payload_cms_get_document

Get a single document by its ID within a collection.

Parameters

NameTypeRequiredDescription
collectionstringyesThe collection slug the document belongs to.
document_idstringyesThe ID of the document to retrieve.

Example

local result = app.integrations.payload_cms.payload_cms_get_document({
  collection = ""
  document_id = ""
})

payload_cms_create_document

Create a new document in a Payload CMS collection.

Parameters

NameTypeRequiredDescription
collectionstringyesThe collection slug to create the document in.
datastringyesJSON object of field values. E.g. ’{“title”:“Hello”,“content”:“World”}’.

Example

local result = app.integrations.payload_cms.payload_cms_create_document({
  collection = ""
  data = '{"title":"My Title","content":"My content"}'
})

payload_cms_list_users

List users in the Payload CMS instance.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of users to return (default 10).
pageintegernoPage number for pagination (default 1).

Example

local result = app.integrations.payload_cms.payload_cms_list_users({
  limit = 10
  page = 1
})

payload_cms_get_current_user

Get the profile of the currently authenticated Payload CMS user.

Example

local result = app.integrations.payload_cms.payload_cms_get_current_user({
})

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.payload_cms.production.function_name({...})
app.integrations.payload_cms.staging.function_name({...})

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

Raw agent markdown 
# Client for the Payload CMS REST API covering collections, documents, and user management — Lua API Reference

## payload_cms_list_collections

List all collections defined in the Payload CMS instance.

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_list_collections({
})
```

## payload_cms_get_collection

Get detailed information about a specific collection by its slug.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `slug` | string | yes | The slug of the collection to retrieve. |

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_get_collection({
  slug = ""
})
```

## payload_cms_list_documents

List documents in a Payload CMS collection with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | string | yes | The collection slug to query. |
| `limit` | integer | no | Maximum number of documents to return (default 10). |
| `page` | integer | no | Page number for pagination (default 1). |
| `sort` | string | no | Sort field. Prefix with "-" for descending. E.g. "createdAt" or "-updatedAt". |
| `where` | string | no | JSON object for filtering. E.g. '{"title":{"equals":"Hello"}}'. |

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_list_documents({
  collection = ""
  limit = 10
  page = 1
})
```

## payload_cms_get_document

Get a single document by its ID within a collection.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | string | yes | The collection slug the document belongs to. |
| `document_id` | string | yes | The ID of the document to retrieve. |

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_get_document({
  collection = ""
  document_id = ""
})
```

## payload_cms_create_document

Create a new document in a Payload CMS collection.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `collection` | string | yes | The collection slug to create the document in. |
| `data` | string | yes | JSON object of field values. E.g. '{"title":"Hello","content":"World"}'. |

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_create_document({
  collection = ""
  data = '{"title":"My Title","content":"My content"}'
})
```

## payload_cms_list_users

List users in the Payload CMS instance.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of users to return (default 10). |
| `page` | integer | no | Page number for pagination (default 1). |

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_list_users({
  limit = 10
  page = 1
})
```

## payload_cms_get_current_user

Get the profile of the currently authenticated Payload CMS user.

### Example

```lua
local result = app.integrations.payload_cms.payload_cms_get_current_user({
})
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.payload_cms.production.function_name({...})
app.integrations.payload_cms.staging.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.payload_cms.list_collections({})
print(result)

Functions

list_collections Read

List all collections defined in the Payload CMS instance. Returns each collection's slug, labels, and field configuration.

Lua path
app.integrations.payload_cms.list_collections
Full name
payload-cms.payload_cms_list_collections
ParameterTypeRequiredDescription
No parameters.
get_collection Read

Get detailed information about a specific collection by its slug. Returns field definitions, labels, default sort, and other configuration.

Lua path
app.integrations.payload_cms.get_collection
Full name
payload-cms.payload_cms_get_collection
ParameterTypeRequiredDescription
slug string yes The slug of the collection to retrieve.
list_documents Read

List documents in a Payload CMS collection. Supports pagination (limit, page), sorting, and filtering via the where parameter. Returns document IDs, timestamps, and field values.

Lua path
app.integrations.payload_cms.list_documents
Full name
payload-cms.payload_cms_list_documents
ParameterTypeRequiredDescription
collection string yes The collection slug to query.
limit integer no Maximum number of documents to return (default 10).
page integer no Page number for pagination (default 1).
sort string no Sort field. Prefix with "-" for descending. E.g. "createdAt" or "-updatedAt".
where string no JSON object for filtering. E.g. '{"title":{"equals":"Hello"}}'.
get_document Read

Get detailed information about a specific document by its ID within a collection. Returns all field values, timestamps, and metadata.

Lua path
app.integrations.payload_cms.get_document
Full name
payload-cms.payload_cms_get_document
ParameterTypeRequiredDescription
collection string yes The collection slug the document belongs to.
document_id string yes The ID of the document to retrieve.
create_document Write

Create a new document in a Payload CMS collection. Provide the collection slug and a JSON object of field values. The document is created as a draft by default (if versions are enabled on the collection).

Lua path
app.integrations.payload_cms.create_document
Full name
payload-cms.payload_cms_create_document
ParameterTypeRequiredDescription
collection string yes The collection slug to create the document in.
data string yes JSON object of field values. E.g. '{"title":"Hello","content":"World"}'.
list_users Read

List users in the Payload CMS instance. Supports pagination with limit and page parameters. Returns user IDs, emails, names, and roles.

Lua path
app.integrations.payload_cms.list_users
Full name
payload-cms.payload_cms_list_users
ParameterTypeRequiredDescription
limit integer no Maximum number of users to return (default 10).
page integer no Page number for pagination (default 1).
get_current_user Read

Get the profile of the currently authenticated Payload CMS user. Returns email, name, roles, and account metadata.

Lua path
app.integrations.payload_cms.get_current_user
Full name
payload-cms.payload_cms_get_current_user
ParameterTypeRequiredDescription
No parameters.