KosmoKrator

productivity

Karbon Lua API for KosmoKrator Agents

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

7 functions 6 read 1 write Bearer token auth
Submit Karbon feedback View package source

Lua Namespace

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

Karbon — Lua API Reference

list_contacts

List contacts in Karbon with pagination.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
limitintegernoResults per page (default: 20, max: 100)

Example

local result = app.integrations.karbon.list_contacts({
  page = 1,
  limit = 20
})

for _, contact in ipairs(result) do
  print(contact.firstName .. " " .. contact.lastName)
end

get_contact

Get a single contact by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe unique contact identifier

Example

local contact = app.integrations.karbon.get_contact({
  id = "contact-123"
})

print(contact.firstName .. " " .. contact.lastName)
print(contact.email)
print(contact.company)

create_contact

Create a new contact in Karbon.

Parameters

NameTypeRequiredDescription
firstNamestringyesFirst name
lastNamestringyesLast name
emailstringnoEmail address
companystringnoCompany or organization name
phonestringnoPhone number

Example

local contact = app.integrations.karbon.create_contact({
  firstName = "Jane",
  lastName = "Doe",
  email = "[email protected]",
  company = "Acme Corp",
  phone = "+1234567890"
})

print("Created contact: " .. contact.id)

list_work_items

List work items with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
limitintegernoResults per page (default: 20, max: 100)
statusstringnoFilter by status (e.g., “Open”, “InProgress”, “Completed”)
assigneestringnoFilter by assignee email or ID

Example

-- List open work items
local result = app.integrations.karbon.list_work_items({
  status = "Open",
  limit = 50
})

for _, item in ipairs(result) do
  print(item.title .. " - " .. item.status)
end

-- List work items assigned to a specific user
local assigned = app.integrations.karbon.list_work_items({
  assignee = "[email protected]",
  page = 1
})

get_work_item

Get a single work item by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe unique work item identifier

Example

local item = app.integrations.karbon.get_work_item({
  id = "work-item-456"
})

print(item.title)
print(item.status)
print(item.dueDate)

list_users

List users in the Karbon account.

Parameters

NameTypeRequiredDescription
limitintegernoNumber of users to return (default: 20)

Example

local users = app.integrations.karbon.list_users({
  limit = 50
})

for _, user in ipairs(users) do
  print(user.firstName .. " " .. user.lastName .. " - " .. user.email)
end

get_current_user

Get the currently authenticated user.

Parameters

None.

Example

local me = app.integrations.karbon.get_current_user({})

print("Logged in as: " .. me.firstName .. " " .. me.lastName)
print("Email: " .. me.email)

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.karbon.firm_a.function_name({...})
app.integrations.karbon.firm_b.function_name({...})

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

Raw agent markdown 
# Karbon — Lua API Reference

## list_contacts

List contacts in Karbon with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `limit` | integer | no | Results per page (default: 20, max: 100) |

### Example

```lua
local result = app.integrations.karbon.list_contacts({
  page = 1,
  limit = 20
})

for _, contact in ipairs(result) do
  print(contact.firstName .. " " .. contact.lastName)
end
```

---

## get_contact

Get a single contact by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The unique contact identifier |

### Example

```lua
local contact = app.integrations.karbon.get_contact({
  id = "contact-123"
})

print(contact.firstName .. " " .. contact.lastName)
print(contact.email)
print(contact.company)
```

---

## create_contact

Create a new contact in Karbon.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `firstName` | string | yes | First name |
| `lastName` | string | yes | Last name |
| `email` | string | no | Email address |
| `company` | string | no | Company or organization name |
| `phone` | string | no | Phone number |

### Example

```lua
local contact = app.integrations.karbon.create_contact({
  firstName = "Jane",
  lastName = "Doe",
  email = "[email protected]",
  company = "Acme Corp",
  phone = "+1234567890"
})

print("Created contact: " .. contact.id)
```

---

## list_work_items

List work items with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `limit` | integer | no | Results per page (default: 20, max: 100) |
| `status` | string | no | Filter by status (e.g., "Open", "InProgress", "Completed") |
| `assignee` | string | no | Filter by assignee email or ID |

### Example

```lua
-- List open work items
local result = app.integrations.karbon.list_work_items({
  status = "Open",
  limit = 50
})

for _, item in ipairs(result) do
  print(item.title .. " - " .. item.status)
end

-- List work items assigned to a specific user
local assigned = app.integrations.karbon.list_work_items({
  assignee = "[email protected]",
  page = 1
})
```

---

## get_work_item

Get a single work item by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The unique work item identifier |

### Example

```lua
local item = app.integrations.karbon.get_work_item({
  id = "work-item-456"
})

print(item.title)
print(item.status)
print(item.dueDate)
```

---

## list_users

List users in the Karbon account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of users to return (default: 20) |

### Example

```lua
local users = app.integrations.karbon.list_users({
  limit = 50
})

for _, user in ipairs(users) do
  print(user.firstName .. " " .. user.lastName .. " - " .. user.email)
end
```

---

## get_current_user

Get the currently authenticated user.

### Parameters

None.

### Example

```lua
local me = app.integrations.karbon.get_current_user({})

print("Logged in as: " .. me.firstName .. " " .. me.lastName)
print("Email: " .. me.email)
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.karbon.firm_a.function_name({...})
app.integrations.karbon.firm_b.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.karbon.karbon_list_contacts({
  page = 1,
  limit = 1
})
print(result)

Functions

karbon_list_contacts

List contacts in Karbon. Returns a paginated list of contacts with their names, emails, companies, and other details.

Operation
Read read
Full name
karbon.karbon_list_contacts
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
limit integer no Number of contacts to return per page (default: 20, max: 100).

karbon_get_contact

Get a single contact from Karbon by its unique identifier. Returns full contact details including name, email, phone, company, and any associated notes.

Operation
Read read
Full name
karbon.karbon_get_contact
ParameterTypeRequiredDescription
id string yes The unique identifier of the contact.

karbon_create_contact

Create a new contact in Karbon. Provide at least a first name and last name. Optionally include email, company, and phone number.

Operation
Write write
Full name
karbon.karbon_create_contact
ParameterTypeRequiredDescription
firstName string yes The contact's first name.
lastName string yes The contact's last name.
email string no The contact's email address.
company string no The contact's company or organization name.
phone string no The contact's phone number.

karbon_list_work_items

List work items in Karbon. Returns a paginated list of work items. Optionally filter by status (e.g., "Open", "InProgress", "Completed") or by assignee.

Operation
Read read
Full name
karbon.karbon_list_work_items
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
limit integer no Number of work items to return per page (default: 20, max: 100).
status string no Filter by work item status (e.g., "Open", "InProgress", "Completed").
assignee string no Filter by the email or ID of the assigned user.

karbon_get_work_item

Get a single work item from Karbon by its unique identifier. Returns full details including title, description, status, assignee, due date, and any associated notes.

Operation
Read read
Full name
karbon.karbon_get_work_item
ParameterTypeRequiredDescription
id string yes The unique identifier of the work item.

karbon_list_users

List users in the Karbon account. Returns user details including names, emails, and roles. Use this to find assignees for work items.

Operation
Read read
Full name
karbon.karbon_list_users
ParameterTypeRequiredDescription
limit integer no Number of users to return (default: 20).

karbon_get_current_user

Get the currently authenticated Karbon user. Returns the profile of the user whose access token is configured for this integration.

Operation
Read read
Full name
karbon.karbon_get_current_user
ParameterTypeRequiredDescription
No parameters.