KosmoKrator

productivity

ReadMe Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local readme = app.integrations.readme
local result = readme.project_metadata({})

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

MCP-only Lua

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

ReadMe

Namespace: readme

Use this integration to inspect ReadMe project metadata, API keys, branches, categories, category pages, guide pages, API reference pages, API definitions, and documentation search results.

Authentication

ReadMe requires api_token. Create an API token in ReadMe and configure it as the integration secret. The integration sends it as a Bearer token.

Tools

  • readme_get_project_metadata
  • readme_list_api_keys
  • readme_list_branches, readme_get_branch
  • readme_list_categories, readme_get_category, readme_list_category_pages
  • readme_get_guide, readme_get_reference
  • readme_list_api_definitions, readme_get_api_definition
  • readme_search_docs

Sections

Branch content endpoints require a section value. Supported values are guides, reference, recipes, and custom_pages.

Return Notes

Responses keep ReadMe’s upstream JSON shape. Slugs, titles, branch names, and API definition IDs are URL-encoded by the integration. Search uses ReadMe’s documented legacy search endpoint and sends version as the x-readme-version header when provided.

Examples

local branches = tools.readme_list_branches({
  per_page = 20
})

local categories = tools.readme_list_categories({
  branch = "stable",
  section = "guides"
})

local pages = tools.readme_list_category_pages({
  branch = "stable",
  section = "guides",
  title = "Getting Started",
  per_page = 25
})

local guide = tools.readme_get_guide({
  branch = "stable",
  slug = "authentication"
})

local results = tools.readme_search_docs({
  search = "webhooks",
  version = "v1.0"
})
Raw agent markdown 
# ReadMe

Namespace: `readme`

Use this integration to inspect ReadMe project metadata, API keys, branches,
categories, category pages, guide pages, API reference pages, API definitions,
and documentation search results.

## Authentication

ReadMe requires `api_token`. Create an API token in ReadMe and configure it as
the integration secret. The integration sends it as a Bearer token.

## Tools

- `readme_get_project_metadata`
- `readme_list_api_keys`
- `readme_list_branches`, `readme_get_branch`
- `readme_list_categories`, `readme_get_category`,
  `readme_list_category_pages`
- `readme_get_guide`, `readme_get_reference`
- `readme_list_api_definitions`, `readme_get_api_definition`
- `readme_search_docs`

## Sections

Branch content endpoints require a `section` value. Supported values are
`guides`, `reference`, `recipes`, and `custom_pages`.

## Return Notes

Responses keep ReadMe's upstream JSON shape. Slugs, titles, branch names, and
API definition IDs are URL-encoded by the integration. Search uses ReadMe's
documented legacy search endpoint and sends `version` as the `x-readme-version`
header when provided.

## Examples

```lua
local branches = tools.readme_list_branches({
  per_page = 20
})

local categories = tools.readme_list_categories({
  branch = "stable",
  section = "guides"
})

local pages = tools.readme_list_category_pages({
  branch = "stable",
  section = "guides",
  title = "Getting Started",
  per_page = 25
})

local guide = tools.readme_get_guide({
  branch = "stable",
  slug = "authentication"
})

local results = tools.readme_search_docs({
  search = "webhooks",
  version = "v1.0"
})
```
Metadata-derived Lua example 
local result = app.integrations.readme.project_metadata({})
print(result)

Functions

project_metadata Read

Get metadata for the current ReadMe project.

Lua path
app.integrations.readme.project_metadata
Full name
readme.readme_get_project_metadata
ParameterTypeRequiredDescription
No parameters.
list_api_keys Read

List API keys for a project subdomain.

Lua path
app.integrations.readme.list_api_keys
Full name
readme.readme_list_api_keys
ParameterTypeRequiredDescription
subdomain string yes ReadMe project subdomain.
list_branches Read

List ReadMe branches.

Lua path
app.integrations.readme.list_branches
Full name
readme.readme_list_branches
ParameterTypeRequiredDescription
No parameters.
get_branch Read

Get one ReadMe branch.

Lua path
app.integrations.readme.get_branch
Full name
readme.readme_get_branch
ParameterTypeRequiredDescription
No parameters.
list_categories Read

List categories in a branch section.

Lua path
app.integrations.readme.list_categories
Full name
readme.readme_list_categories
ParameterTypeRequiredDescription
No parameters.
get_category Read

Get one category in a branch section.

Lua path
app.integrations.readme.get_category
Full name
readme.readme_get_category
ParameterTypeRequiredDescription
No parameters.
category_pages Read

List pages within a category.

Lua path
app.integrations.readme.category_pages
Full name
readme.readme_list_category_pages
ParameterTypeRequiredDescription
No parameters.
get_guide Read

Get a guide page by slug.

Lua path
app.integrations.readme.get_guide
Full name
readme.readme_get_guide
ParameterTypeRequiredDescription
No parameters.
get_reference Read

Get an API reference page by slug.

Lua path
app.integrations.readme.get_reference
Full name
readme.readme_get_reference
ParameterTypeRequiredDescription
No parameters.
list_api_definitions Read

List API definitions.

Lua path
app.integrations.readme.list_api_definitions
Full name
readme.readme_list_api_definitions
ParameterTypeRequiredDescription
No parameters.
get_api_definition Read

Get one API definition.

Lua path
app.integrations.readme.get_api_definition
Full name
readme.readme_get_api_definition
ParameterTypeRequiredDescription
api_id string yes ReadMe API definition ID.
search_docs Read

Search ReadMe docs using the documented legacy search endpoint.

Lua path
app.integrations.readme.search_docs
Full name
readme.readme_search_docs
ParameterTypeRequiredDescription
No parameters.