KosmoKrator

productivity

Beamer Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.beamer.list_posts({limit = 1, page = 1, status = "example_status"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("beamer"))' --json
kosmo integrations:lua --eval 'print(docs.read("beamer.list_posts"))' --json

Workflow file

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

workflow.lua 
local beamer = app.integrations.beamer
local result = beamer.list_posts({limit = 1, page = 1, status = "example_status"})

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

MCP-only Lua

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

Beamer Lua Reference

Namespace: app.integrations.beamer

The Beamer API uses the Beamer-Api-Key header. Tools return raw Beamer JSON.

Core Tools

local posts = app.integrations.beamer.list_posts({
  limit = 10,
  page = 1,
  status = "published",
})

local post = app.integrations.beamer.get_post({ id = 123 })

local created = app.integrations.beamer.create_post({
  title = "New feature",
  content = "<p>We shipped it.</p>",
  category = 5,
})

local comments = app.integrations.beamer.list_comments({ post_id = 123 })
local categories = app.integrations.beamer.list_categories({})
local me = app.integrations.beamer.get_current_user({})

Generic API

Use generic tools for Beamer endpoints that do not have dedicated wrappers. Paths are relative to https://api.getbeamer.com/v0.

local unread = app.integrations.beamer.api_get({
  path = "/unread/count",
  params = {
    userId = "user_123",
    userEmail = "user@example.test",
  },
})

local comment = app.integrations.beamer.api_post({
  path = "/posts/123/comments",
  body = {
    userEmail = "user@example.test",
    comment = "Great update",
  },
})

Generic write tools:

  • api_post({ path, body })
  • api_put({ path, body })
  • api_delete({ path, body })

Multi-Account Usage

app.integrations.beamer.default.list_posts({})
app.integrations.beamer.production.api_get({ path = "/unread/count" })
Raw agent markdown 
# Beamer Lua Reference

Namespace: `app.integrations.beamer`

The Beamer API uses the `Beamer-Api-Key` header. Tools return raw Beamer JSON.

## Core Tools

```lua
local posts = app.integrations.beamer.list_posts({
  limit = 10,
  page = 1,
  status = "published",
})

local post = app.integrations.beamer.get_post({ id = 123 })

local created = app.integrations.beamer.create_post({
  title = "New feature",
  content = "<p>We shipped it.</p>",
  category = 5,
})

local comments = app.integrations.beamer.list_comments({ post_id = 123 })
local categories = app.integrations.beamer.list_categories({})
local me = app.integrations.beamer.get_current_user({})
```

## Generic API

Use generic tools for Beamer endpoints that do not have dedicated wrappers.
Paths are relative to `https://api.getbeamer.com/v0`.

```lua
local unread = app.integrations.beamer.api_get({
  path = "/unread/count",
  params = {
    userId = "user_123",
    userEmail = "user@example.test",
  },
})

local comment = app.integrations.beamer.api_post({
  path = "/posts/123/comments",
  body = {
    userEmail = "user@example.test",
    comment = "Great update",
  },
})
```

Generic write tools:

- `api_post({ path, body })`
- `api_put({ path, body })`
- `api_delete({ path, body })`

## Multi-Account Usage

```lua
app.integrations.beamer.default.list_posts({})
app.integrations.beamer.production.api_get({ path = "/unread/count" })
```
Metadata-derived Lua example 
local result = app.integrations.beamer.list_posts({limit = 1, page = 1, status = "example_status"})
print(result)

Functions

list_posts Read

List changelog posts and announcements from Beamer. Supports pagination with limit and page, and filtering by status (published, draft, scheduled).

Lua path
app.integrations.beamer.list_posts
Full name
beamer.beamer_list_posts
ParameterTypeRequiredDescription
limit integer no Maximum number of posts to return (default: 10, max: 100).
page integer no Page number for pagination (default: 1).
status string no Filter by publication status: "published", "draft", or "scheduled".
get_post Read

Retrieve a single Beamer changelog post by its ID. Returns the full post including title, content, date, category, and metadata.

Lua path
app.integrations.beamer.get_post
Full name
beamer.beamer_get_post
ParameterTypeRequiredDescription
id integer yes The post ID.
create_post Write

Create a new changelog post or announcement in Beamer. Provide a title and content (HTML supported). Optionally set a category and scheduled publication date.

Lua path
app.integrations.beamer.create_post
Full name
beamer.beamer_create_post
ParameterTypeRequiredDescription
title string yes The post title.
content string yes The post body content. HTML formatting is supported.
category integer no The category ID to assign the post to.
date string no Publication date in ISO 8601 format (e.g., "2025-06-01T12:00:00Z"). Omit to publish immediately.
list_comments Read

List all comments on a specific Beamer post. Returns comment text, author info, and timestamps.

Lua path
app.integrations.beamer.list_comments
Full name
beamer.beamer_list_comments
ParameterTypeRequiredDescription
post_id integer yes The post ID to list comments for.
get_current_user Read

Get the profile of the currently authenticated Beamer user. Returns name, email, role, and account details. Useful for verifying credentials.

Lua path
app.integrations.beamer.get_current_user
Full name
beamer.beamer_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_categories Read

List all post categories in your Beamer account. Returns category IDs and names for use when creating or filtering posts.

Lua path
app.integrations.beamer.list_categories
Full name
beamer.beamer_list_categories
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call any Beamer GET API endpoint relative to the configured base URL.

Lua path
app.integrations.beamer.api_get
Full name
beamer.beamer_api_get
ParameterTypeRequiredDescription
path string yes API path such as /posts or /unread/count.
params object no Query parameters.
api_post Write

Call any Beamer POST API endpoint relative to the configured base URL.

Lua path
app.integrations.beamer.api_post
Full name
beamer.beamer_api_post
ParameterTypeRequiredDescription
path string yes API path such as /posts/{id}/comments.
body object no JSON body.
api_put Write

Call any Beamer PUT API endpoint relative to the configured base URL.

Lua path
app.integrations.beamer.api_put
Full name
beamer.beamer_api_put
ParameterTypeRequiredDescription
path string yes API path.
body object no JSON body.
api_delete Write

Call any Beamer DELETE API endpoint relative to the configured base URL.

Lua path
app.integrations.beamer.api_delete
Full name
beamer.beamer_api_delete
ParameterTypeRequiredDescription
path string yes API path.
body object no JSON body.