KosmoKrator

productivity

Kimai Lua API for KosmoKrator Agents

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

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

Lua Namespace

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

Kimai — Lua API Reference

list_timesheets

List time-tracking entries with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number for pagination (default: 1)
sizeintegernoNumber of results per page (default: 50)
userstringnoFilter by user ID or username
projectintegernoFilter by project ID
beginstringnoFilter start date (ISO 8601, e.g., "2025-01-01T00:00:00")
endstringnoFilter end date (ISO 8601, e.g., "2025-01-31T23:59:59")
statestringnoFilter by state: "running" or "stopped"

Examples

-- List recent timesheets
local result = app.integrations.kimai.list_timesheets({
  size = 10
})

for _, entry in ipairs(result) do
  print(entry.id .. ": " .. entry.description)
end

-- Filter by project and date range
local result = app.integrations.kimai.list_timesheets({
  project = 5,
  begin = "2025-01-01T00:00:00",
  end = "2025-01-31T23:59:59"
})

get_timesheet

Get details of a specific timesheet entry.

Parameters

NameTypeRequiredDescription
idintegeryesThe timesheet entry ID

Example

local result = app.integrations.kimai.get_timesheet({ id = 42 })
print("Duration: " .. result.duration .. " seconds")

create_timesheet

Create a new time-tracking entry.

Parameters

NameTypeRequiredDescription
beginstringyesStart time (ISO 8601, e.g., "2025-01-15T09:00:00")
endstringnoEnd time (ISO 8601). Omit to start a running timer.
projectintegeryesProject ID to associate
activityintegernoActivity ID to categorize the entry
descriptionstringnoDescription of the work performed

Examples

-- Create a completed time entry
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  end = "2025-01-15T17:00:00",
  project = 3,
  activity = 7,
  description = "Implementing login feature"
})

-- Start a running timer
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  project = 3
})

list_projects

List projects with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
sizeintegernoResults per page (default: 50)
customerintegernoFilter by customer ID
visibleintegernoVisibility: 1 = visible, 2 = hidden, 3 = all

Example

local result = app.integrations.kimai.list_projects({
  customer = 2,
  visible = 1
})

get_project

Get details of a specific project.

Parameters

NameTypeRequiredDescription
idintegeryesThe project ID

Example

local result = app.integrations.kimai.get_project({ id = 5 })
print("Project: " .. result.name .. " (Customer: " .. result.customer.name .. ")")

list_customers

List customers with optional filters.

Parameters

NameTypeRequiredDescription
pageintegernoPage number (default: 1)
sizeintegernoResults per page (default: 50)
visibleintegernoVisibility: 1 = visible, 2 = hidden, 3 = all

Example

local result = app.integrations.kimai.list_customers({ visible = 1 })
for _, customer in ipairs(result) do
  print(customer.id .. ": " .. customer.name)
end

get_current_user

Get the currently authenticated user profile. Takes no parameters.

Example

local result = app.integrations.kimai.get_current_user({})
print("Logged in as: " .. result.displayName)

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.kimai.work.function_name({...})
app.integrations.kimai.freelance.function_name({...})

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

Raw agent markdown 
# Kimai — Lua API Reference

## list_timesheets

List time-tracking entries with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number for pagination (default: 1) |
| `size` | integer | no | Number of results per page (default: 50) |
| `user` | string | no | Filter by user ID or username |
| `project` | integer | no | Filter by project ID |
| `begin` | string | no | Filter start date (ISO 8601, e.g., `"2025-01-01T00:00:00"`) |
| `end` | string | no | Filter end date (ISO 8601, e.g., `"2025-01-31T23:59:59"`) |
| `state` | string | no | Filter by state: `"running"` or `"stopped"` |

### Examples

```lua
-- List recent timesheets
local result = app.integrations.kimai.list_timesheets({
  size = 10
})

for _, entry in ipairs(result) do
  print(entry.id .. ": " .. entry.description)
end

-- Filter by project and date range
local result = app.integrations.kimai.list_timesheets({
  project = 5,
  begin = "2025-01-01T00:00:00",
  end = "2025-01-31T23:59:59"
})
```

---

## get_timesheet

Get details of a specific timesheet entry.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The timesheet entry ID |

### Example

```lua
local result = app.integrations.kimai.get_timesheet({ id = 42 })
print("Duration: " .. result.duration .. " seconds")
```

---

## create_timesheet

Create a new time-tracking entry.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `begin` | string | yes | Start time (ISO 8601, e.g., `"2025-01-15T09:00:00"`) |
| `end` | string | no | End time (ISO 8601). Omit to start a running timer. |
| `project` | integer | yes | Project ID to associate |
| `activity` | integer | no | Activity ID to categorize the entry |
| `description` | string | no | Description of the work performed |

### Examples

```lua
-- Create a completed time entry
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  end = "2025-01-15T17:00:00",
  project = 3,
  activity = 7,
  description = "Implementing login feature"
})

-- Start a running timer
local result = app.integrations.kimai.create_timesheet({
  begin = "2025-01-15T09:00:00",
  project = 3
})
```

---

## list_projects

List projects with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `size` | integer | no | Results per page (default: 50) |
| `customer` | integer | no | Filter by customer ID |
| `visible` | integer | no | Visibility: 1 = visible, 2 = hidden, 3 = all |

### Example

```lua
local result = app.integrations.kimai.list_projects({
  customer = 2,
  visible = 1
})
```

---

## get_project

Get details of a specific project.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The project ID |

### Example

```lua
local result = app.integrations.kimai.get_project({ id = 5 })
print("Project: " .. result.name .. " (Customer: " .. result.customer.name .. ")")
```

---

## list_customers

List customers with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `page` | integer | no | Page number (default: 1) |
| `size` | integer | no | Results per page (default: 50) |
| `visible` | integer | no | Visibility: 1 = visible, 2 = hidden, 3 = all |

### Example

```lua
local result = app.integrations.kimai.list_customers({ visible = 1 })
for _, customer in ipairs(result) do
  print(customer.id .. ": " .. customer.name)
end
```

---

## get_current_user

Get the currently authenticated user profile. Takes no parameters.

### Example

```lua
local result = app.integrations.kimai.get_current_user({})
print("Logged in as: " .. result.displayName)
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.kimai.work.function_name({...})
app.integrations.kimai.freelance.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.kimai.kimai_list_timesheets({
  page = 1,
  size = 1,
  user = "example_user",
  project = 1,
  begin = "example_begin",
  end = "example_end",
  state = "example_state"
})
print(result)

Functions

kimai_list_timesheets

List time-tracking entries from Kimai. Supports filtering by user, project, date range, and state. Returns paginated results with timesheet details including duration, description, and associated project/activity.

Operation
Read read
Full name
kimai.kimai_list_timesheets
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
size integer no Number of results per page (default: 50).
user string no Filter by user ID or username.
project integer no Filter by project ID.
begin string no Filter start date (ISO 8601, e.g., "2025-01-01T00:00:00"). Only entries starting on or after this date.
end string no Filter end date (ISO 8601, e.g., "2025-01-31T23:59:59"). Only entries starting before or on this date.
state string no Filter by state: "running" for active timers, "stopped" for completed entries. Omit for all.

kimai_get_timesheet

Get details of a specific timesheet entry from Kimai. Returns the full timesheet record including begin/end timestamps, duration, description, project, activity, and user information.

Operation
Read read
Full name
kimai.kimai_get_timesheet
ParameterTypeRequiredDescription
id integer yes The timesheet entry ID.

kimai_create_timesheet

Create a new time-tracking entry in Kimai. Requires a begin timestamp and at least a project ID. Optionally specify an end time, activity, and description to categorize the time entry.

Operation
Write write
Full name
kimai.kimai_create_timesheet
ParameterTypeRequiredDescription
begin string yes Start time in ISO 8601 format (e.g., "2025-01-15T09:00:00").
end string no End time in ISO 8601 format (e.g., "2025-01-15T17:00:00"). Omit to start a running timer.
project integer yes The project ID to associate the time entry with.
activity integer no The activity ID to categorize the time entry (e.g., "Development", "Meeting").
description string no A description of the work performed during this time entry.

kimai_list_projects

List projects from Kimai. Supports filtering by customer and visibility. Returns project details including name, customer, budget, and time budget information.

Operation
Read read
Full name
kimai.kimai_list_projects
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
size integer no Number of results per page (default: 50).
customer integer no Filter by customer ID to list only projects for a specific customer.
visible integer no Visibility filter: 1 for visible projects only, 2 for hidden, 3 for all.

kimai_get_project

Get details of a specific project from Kimai. Returns the full project record including name, customer, comment, budget, time budget, and visibility status.

Operation
Read read
Full name
kimai.kimai_get_project
ParameterTypeRequiredDescription
id integer yes The project ID.

kimai_list_customers

List customers from Kimai. Supports filtering by visibility. Returns customer details including name, company, contact information, and associated project count.

Operation
Read read
Full name
kimai.kimai_list_customers
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
size integer no Number of results per page (default: 50).
visible integer no Visibility filter: 1 for visible customers only, 2 for hidden, 3 for all.

kimai_get_current_user

Get the profile of the currently authenticated Kimai user. Returns user details including username, display name, email, timezone, and language preferences.

Operation
Read read
Full name
kimai.kimai_get_current_user
ParameterTypeRequiredDescription
No parameters.