KosmoKrator

productivity

Split Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.split.list({workspace_id = "example_workspace_id", limit = 1, offset = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("split"))' --json
kosmo integrations:lua --eval 'print(docs.read("split.list"))' --json

Workflow file

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

workflow.lua 
local split = app.integrations.split
local result = split.list({workspace_id = "example_workspace_id", limit = 1, offset = 1})

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

MCP-only Lua

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

Split — Lua API Reference

list_splits

List feature splits in a Split workspace.

Parameters

NameTypeRequiredDescription
workspace_idstringnoWorkspace ID (defaults to configured workspace)
limitintegernoMax splits to return (default: 20, max: 100)
offsetintegernoPagination offset (default: 0)

Examples

-- List splits in default workspace
local result = app.integrations.split.list_splits({})

for _, split in ipairs(result.splits) do
  print(split.name .. " (" .. split.trafficTypeName .. ")")
end

-- Paginated listing
local result = app.integrations.split.list_splits({
  limit = 50,
  offset = 0
})

-- Specific workspace
local result = app.integrations.split.list_splits({
  workspace_id = "abc123"
})

get_split

Get detailed information about a specific feature split.

Parameters

NameTypeRequiredDescription
split_namestringyesThe split name, e.g. "new-checkout-flow"
workspace_idstringnoWorkspace ID (defaults to configured workspace)

Examples

local result = app.integrations.split.get_split({
  split_name = "new-checkout-flow"
})

print("Split: " .. result.name)
print("Traffic Type: " .. result.trafficTypeName)
print("Killed: " .. tostring(result.killed))
print("Treatments: " .. #result.treatments)

create_split

Create a new feature split in a workspace.

Parameters

NameTypeRequiredDescription
namestringyesThe split name
traffic_type_namestringyesTraffic type name, e.g. "user"
descriptionstringnoOptional description
workspace_idstringnoWorkspace ID (defaults to configured workspace)

Examples

-- Create a basic split
local result = app.integrations.split.create_split({
  name = "new-checkout-flow",
  traffic_type_name = "user"
})
print(result.message)

-- Create with description
local result = app.integrations.split.create_split({
  name = "new-pricing-page",
  traffic_type_name = "user",
  description = "Controls the new pricing page rollout"
})
print(result.message)

list_environments

List all environments for a Split workspace.

Parameters

NameTypeRequiredDescription
workspace_idstringnoWorkspace ID (defaults to configured workspace)

Examples

local result = app.integrations.split.list_environments({})

for _, env in ipairs(result.environments) do
  print(env.id .. ": " .. env.name .. " (" .. env.type .. ")")
end

get_environment

Get detailed information about a specific Split environment.

Parameters

NameTypeRequiredDescription
environment_idstringyesThe environment ID
workspace_idstringnoWorkspace ID (defaults to configured workspace)

Examples

local result = app.integrations.split.get_environment({
  environment_id = "env-123"
})

print("Environment: " .. result.name)
print("Type: " .. result.type)
print("Status: " .. result.status)

list_workspaces

List all Split workspaces.

Parameters

This tool takes no parameters.

Examples

local result = app.integrations.split.list_workspaces({})

for _, ws in ipairs(result.workspaces) do
  print(ws.id .. ": " .. ws.name)
end

get_current_user

Get the currently authenticated Split user.

Parameters

This tool takes no parameters.

Examples

local result = app.integrations.split.get_current_user({})

print("User: " .. result.name)
print("Email: " .. result.email)
print("Type: " .. result.type)

Multi-Account Usage

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

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

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

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

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

Raw agent markdown 
# Split — Lua API Reference

## list_splits

List feature splits in a Split workspace.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | no | Workspace ID (defaults to configured workspace) |
| `limit` | integer | no | Max splits to return (default: 20, max: 100) |
| `offset` | integer | no | Pagination offset (default: 0) |

### Examples

```lua
-- List splits in default workspace
local result = app.integrations.split.list_splits({})

for _, split in ipairs(result.splits) do
  print(split.name .. " (" .. split.trafficTypeName .. ")")
end

-- Paginated listing
local result = app.integrations.split.list_splits({
  limit = 50,
  offset = 0
})

-- Specific workspace
local result = app.integrations.split.list_splits({
  workspace_id = "abc123"
})
```

---

## get_split

Get detailed information about a specific feature split.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `split_name` | string | yes | The split name, e.g. `"new-checkout-flow"` |
| `workspace_id` | string | no | Workspace ID (defaults to configured workspace) |

### Examples

```lua
local result = app.integrations.split.get_split({
  split_name = "new-checkout-flow"
})

print("Split: " .. result.name)
print("Traffic Type: " .. result.trafficTypeName)
print("Killed: " .. tostring(result.killed))
print("Treatments: " .. #result.treatments)
```

---

## create_split

Create a new feature split in a workspace.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | The split name |
| `traffic_type_name` | string | yes | Traffic type name, e.g. `"user"` |
| `description` | string | no | Optional description |
| `workspace_id` | string | no | Workspace ID (defaults to configured workspace) |

### Examples

```lua
-- Create a basic split
local result = app.integrations.split.create_split({
  name = "new-checkout-flow",
  traffic_type_name = "user"
})
print(result.message)

-- Create with description
local result = app.integrations.split.create_split({
  name = "new-pricing-page",
  traffic_type_name = "user",
  description = "Controls the new pricing page rollout"
})
print(result.message)
```

---

## list_environments

List all environments for a Split workspace.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | no | Workspace ID (defaults to configured workspace) |

### Examples

```lua
local result = app.integrations.split.list_environments({})

for _, env in ipairs(result.environments) do
  print(env.id .. ": " .. env.name .. " (" .. env.type .. ")")
end
```

---

## get_environment

Get detailed information about a specific Split environment.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `environment_id` | string | yes | The environment ID |
| `workspace_id` | string | no | Workspace ID (defaults to configured workspace) |

### Examples

```lua
local result = app.integrations.split.get_environment({
  environment_id = "env-123"
})

print("Environment: " .. result.name)
print("Type: " .. result.type)
print("Status: " .. result.status)
```

---

## list_workspaces

List all Split workspaces.

### Parameters

This tool takes no parameters.

### Examples

```lua
local result = app.integrations.split.list_workspaces({})

for _, ws in ipairs(result.workspaces) do
  print(ws.id .. ": " .. ws.name)
end
```

---

## get_current_user

Get the currently authenticated Split user.

### Parameters

This tool takes no parameters.

### Examples

```lua
local result = app.integrations.split.get_current_user({})

print("User: " .. result.name)
print("Email: " .. result.email)
print("Type: " .. result.type)
```

---

## Multi-Account Usage

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

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

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

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

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.split.list({workspace_id = "example_workspace_id", limit = 1, offset = 1})
print(result)

Functions

list Read

List feature splits in a Split workspace. Returns split names, descriptions, traffic type, and creation date.

Lua path
app.integrations.split.list
Full name
split.split_list_splits
ParameterTypeRequiredDescription
workspace_id string no The workspace ID (defaults to the configured workspace).
limit integer no Maximum number of splits to return (default: 20, max: 100).
offset integer no Offset for pagination (default: 0).
get Read

Get detailed information about a specific Split feature split, including its definition and traffic allocation.

Lua path
app.integrations.split.get
Full name
split.split_get_split
ParameterTypeRequiredDescription
split_name string yes The split name (e.g., "new-checkout-flow").
workspace_id string no The workspace ID (defaults to the configured workspace).
create Write

Create a new feature split in a Split workspace. Specify a name, traffic type, and optional description.

Lua path
app.integrations.split.create
Full name
split.split_create_split
ParameterTypeRequiredDescription
name string yes The split name (e.g., "new-checkout-flow").
traffic_type_name string yes The traffic type name (e.g., "user", "account").
description string no Optional description for the split.
workspace_id string no The workspace ID (defaults to the configured workspace).
list_environments Read

List all environments for a Split workspace. Returns environment IDs, names, and their status.

Lua path
app.integrations.split.list_environments
Full name
split.split_list_environments
ParameterTypeRequiredDescription
workspace_id string no The workspace ID (defaults to the configured workspace).
get_environment Read

Get detailed information about a specific Split environment, including its name, type, and status.

Lua path
app.integrations.split.get_environment
Full name
split.split_get_environment
ParameterTypeRequiredDescription
environment_id string yes The environment ID.
workspace_id string no The workspace ID (defaults to the configured workspace).
list_workspaces Read

List all Split workspaces. Returns workspace IDs, names, and the number of environments.

Lua path
app.integrations.split.list_workspaces
Full name
split.split_list_workspaces
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get information about the currently authenticated Split user. Useful for verifying API credentials.

Lua path
app.integrations.split.get_current_user
Full name
split.split_get_current_user
ParameterTypeRequiredDescription
No parameters.