KosmoKrator

productivity

Todoist Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.todoist.close_task({id = "example_id"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("todoist"))' --json
kosmo integrations:lua --eval 'print(docs.read("todoist.close_task"))' --json

Workflow file

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

workflow.lua 
local todoist = app.integrations.todoist
local result = todoist.close_task({id = "example_id"})

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

MCP-only Lua

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

Client for the Todoist REST API — Lua API Reference

todoist_list_tasks

List tasks in Todoist with optional filters.

Parameters

NameTypeRequiredDescription
project_idstringnoFilter tasks by project ID.
section_idstringnoFilter tasks by section ID.
labelstringnoFilter tasks by label name.
filterstringnoTodoist filter expression (e.g. “today”, “p1 & @email”).
langstringnoLanguage for filter evaluation (e.g. “en”).
idsarraynoArray of task IDs to fetch.

Example

local result = app.integrations.todoist.todoist_list_tasks({
  project_id = ""
  filter = ""
})

todoist_get_task

Get detailed information about a Todoist task.

Parameters

NameTypeRequiredDescription
idstringyesThe task ID.

Example

local result = app.integrations.todoist.todoist_get_task({
  id = ""
})

todoist_create_task

Create a new task in Todoist.

Parameters

NameTypeRequiredDescription
contentstringyesText content of the task.
descriptionstringnoDetailed description of the task (supports Markdown).
project_idstringnoProject ID to add the task to.
section_idstringnoSection ID to add the task to.
parent_idstringnoParent task ID for creating a subtask.
orderintegernoPosition among siblings or in the project.
priorityintegernoPriority level (1=normal, 2=medium, 3=high, 4=urgent).
labelsarraynoArray of label names to assign.
due_stringstringnoHuman-readable due date (e.g. “every first Monday”, “tomorrow”).
due_datestringnoDue date in YYYY-MM-DD format.
due_langstringnoLanguage for due_string parsing (e.g. “en”).
assignee_idstringnoUser ID to assign the task to.

Example

local result = app.integrations.todoist.todoist_create_task({
  content = ""
  description = ""
  project_id = ""
})

todoist_list_projects

List all projects in Todoist.

Parameters

NameTypeRequiredDescription
idsarraynoArray of project IDs to fetch.

Example

local result = app.integrations.todoist.todoist_list_projects()

todoist_get_project

Get detailed information about a Todoist project.

Parameters

NameTypeRequiredDescription
idstringyesThe project ID.

Example

local result = app.integrations.todoist.todoist_get_project({
  id = ""
})

todoist_list_labels

List all personal labels in Todoist.

Parameters

This function takes no parameters.

Example

local result = app.integrations.todoist.todoist_list_labels()

todoist_get_current_user

Get the currently authenticated Todoist user.

Parameters

This function takes no parameters.

Example

local result = app.integrations.todoist.todoist_get_current_user()

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.todoist.work.function_name({...})
app.integrations.todoist.personal.function_name({...})

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

Raw agent markdown 
# Client for the Todoist REST API — Lua API Reference

## todoist_list_tasks

List tasks in Todoist with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project_id` | string | no | Filter tasks by project ID. |
| `section_id` | string | no | Filter tasks by section ID. |
| `label` | string | no | Filter tasks by label name. |
| `filter` | string | no | Todoist filter expression (e.g. "today", "p1 & @email"). |
| `lang` | string | no | Language for filter evaluation (e.g. "en"). |
| `ids` | array | no | Array of task IDs to fetch. |

### Example

```lua
local result = app.integrations.todoist.todoist_list_tasks({
  project_id = ""
  filter = ""
})
```

## todoist_get_task

Get detailed information about a Todoist task.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The task ID. |

### Example

```lua
local result = app.integrations.todoist.todoist_get_task({
  id = ""
})
```

## todoist_create_task

Create a new task in Todoist.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | string | yes | Text content of the task. |
| `description` | string | no | Detailed description of the task (supports Markdown). |
| `project_id` | string | no | Project ID to add the task to. |
| `section_id` | string | no | Section ID to add the task to. |
| `parent_id` | string | no | Parent task ID for creating a subtask. |
| `order` | integer | no | Position among siblings or in the project. |
| `priority` | integer | no | Priority level (1=normal, 2=medium, 3=high, 4=urgent). |
| `labels` | array | no | Array of label names to assign. |
| `due_string` | string | no | Human-readable due date (e.g. "every first Monday", "tomorrow"). |
| `due_date` | string | no | Due date in YYYY-MM-DD format. |
| `due_lang` | string | no | Language for due_string parsing (e.g. "en"). |
| `assignee_id` | string | no | User ID to assign the task to. |

### Example

```lua
local result = app.integrations.todoist.todoist_create_task({
  content = ""
  description = ""
  project_id = ""
})
```

## todoist_list_projects

List all projects in Todoist.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ids` | array | no | Array of project IDs to fetch. |

### Example

```lua
local result = app.integrations.todoist.todoist_list_projects()
```

## todoist_get_project

Get detailed information about a Todoist project.

### Parameters

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

### Example

```lua
local result = app.integrations.todoist.todoist_get_project({
  id = ""
})
```

## todoist_list_labels

List all personal labels in Todoist.

### Parameters

This function takes no parameters.

### Example

```lua
local result = app.integrations.todoist.todoist_list_labels()
```

## todoist_get_current_user

Get the currently authenticated Todoist user.

### Parameters

This function takes no parameters.

### Example

```lua
local result = app.integrations.todoist.todoist_get_current_user()
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.todoist.work.function_name({...})
app.integrations.todoist.personal.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.todoist.close_task({id = "example_id"})
print(result)

Functions

close_task Write

Mark a task as completed (close it). The task will move to the completed view.

Lua path
app.integrations.todoist.close_task
Full name
todoist.todoist_close_task
ParameterTypeRequiredDescription
id string yes The unique ID of the task to close.
create_comment Write

Add a comment to a Todoist task or project. Provide either task_id or project_id along with the content.

Lua path
app.integrations.todoist.create_comment
Full name
todoist.todoist_create_comment
ParameterTypeRequiredDescription
task_id string no ID of the task to comment on (use this or project_id).
project_id string no ID of the project to comment on (use this or task_id).
content string yes The comment text.
create_project Write

Create a new project in Todoist. Projects can be nested using parent_id.

Lua path
app.integrations.todoist.create_project
Full name
todoist.todoist_create_project
ParameterTypeRequiredDescription
name string yes Name of the project.
parent_id string no ID of the parent project for nesting.
color string no Color ID or name for the project.
is_favorite boolean no Whether to mark the project as favorite.
view_style string no View style: "list" or "board".
create_section Write

Create a new section within a Todoist project to organize tasks into groups.

Lua path
app.integrations.todoist.create_section
Full name
todoist.todoist_create_section
ParameterTypeRequiredDescription
name string yes Name of the section.
project_id string yes ID of the project to create the section in.
order integer no Position of the section within the project (1-based).
create_task Write

Create a new task in Todoist.

Lua path
app.integrations.todoist.create_task
Full name
todoist.todoist_create_task
ParameterTypeRequiredDescription
content string yes Text content of the task.
description string no Detailed description of the task (supports Markdown).
project_id string no Project ID to add the task to.
section_id string no Section ID to add the task to.
parent_id string no Parent task ID for creating a subtask.
order integer no Position among siblings or in the project.
priority integer no Priority level (1=normal, 2=medium, 3=high, 4=urgent).
labels array no Array of label names to assign.
due_string string no Human-readable due date (e.g. "every first Monday", "tomorrow").
due_date string no Due date in YYYY-MM-DD format.
due_lang string no Language for due_string parsing (e.g. "en").
assignee_id string no User ID to assign the task to.
delete_project Write

Permanently delete a project and all its tasks from Todoist. This action cannot be undone.

Lua path
app.integrations.todoist.delete_project
Full name
todoist.todoist_delete_project
ParameterTypeRequiredDescription
id string yes The unique ID of the project to delete.
delete_section Write

Permanently delete a section from Todoist. This action cannot be undone.

Lua path
app.integrations.todoist.delete_section
Full name
todoist.todoist_delete_section
ParameterTypeRequiredDescription
id string yes The unique ID of the section to delete.
delete_task Write

Permanently delete a task from Todoist. This action cannot be undone.

Lua path
app.integrations.todoist.delete_task
Full name
todoist.todoist_delete_task
ParameterTypeRequiredDescription
id string yes The unique ID of the task to delete.
get_current_user Read

Get the currently authenticated Todoist user.

Lua path
app.integrations.todoist.get_current_user
Full name
todoist.todoist_get_current_user
ParameterTypeRequiredDescription
No parameters.
get_project Read

Get detailed information about a Todoist project.

Lua path
app.integrations.todoist.get_project
Full name
todoist.todoist_get_project
ParameterTypeRequiredDescription
id string yes The project ID.
get_section Read

Retrieve a single Todoist section by its ID.

Lua path
app.integrations.todoist.get_section
Full name
todoist.todoist_get_section
ParameterTypeRequiredDescription
id string yes The unique ID of the section to retrieve.
get_task Read

Get detailed information about a Todoist task.

Lua path
app.integrations.todoist.get_task
Full name
todoist.todoist_get_task
ParameterTypeRequiredDescription
id string yes The task ID.
list_comments Read

List comments for a Todoist task or project. Provide either task_id or project_id.

Lua path
app.integrations.todoist.list_comments
Full name
todoist.todoist_list_comments
ParameterTypeRequiredDescription
task_id string no ID of the task to list comments for.
project_id string no ID of the project to list comments for.
list_labels Read

List all personal labels in Todoist.

Lua path
app.integrations.todoist.list_labels
Full name
todoist.todoist_list_labels
ParameterTypeRequiredDescription
No parameters.
list_projects Read

List all projects in Todoist.

Lua path
app.integrations.todoist.list_projects
Full name
todoist.todoist_list_projects
ParameterTypeRequiredDescription
ids array no Array of project IDs to fetch.
list_sections Read

List all sections, optionally filtered by a specific project ID.

Lua path
app.integrations.todoist.list_sections
Full name
todoist.todoist_list_sections
ParameterTypeRequiredDescription
project_id string no Filter sections by project ID.
list_tasks Read

List tasks in Todoist with optional filters.

Lua path
app.integrations.todoist.list_tasks
Full name
todoist.todoist_list_tasks
ParameterTypeRequiredDescription
project_id string no Filter tasks by project ID.
section_id string no Filter tasks by section ID.
label string no Filter tasks by label name.
filter string no Todoist filter expression (e.g. "today", "p1 & @email").
lang string no Language for filter evaluation (e.g. "en").
ids array no Array of task IDs to fetch.
quick_add Write

Add a task using Todoist's natural language quick-add. Examples: "Buy milk tomorrow", "Meeting with team every Monday @Work p1".

Lua path
app.integrations.todoist.quick_add
Full name
todoist.todoist_quick_add
ParameterTypeRequiredDescription
text string yes Natural language task text (e.g., "Buy milk tomorrow @Groceries").
note string no Note to attach to the task.
reminder string no Reminder in natural language (e.g., "30 minutes before").
auto_reminder boolean no Whether to add an automatic reminder.
reopen_task Write

Reopen a completed task, returning it to the active task list.

Lua path
app.integrations.todoist.reopen_task
Full name
todoist.todoist_reopen_task
ParameterTypeRequiredDescription
id string yes The unique ID of the task to reopen.
update_project Write

Update an existing project in Todoist. Only the fields provided will be changed.

Lua path
app.integrations.todoist.update_project
Full name
todoist.todoist_update_project
ParameterTypeRequiredDescription
id string yes The unique ID of the project to update.
name string no New name for the project.
color string no New color ID or name.
is_favorite boolean no Whether the project is a favorite.
view_style string no View style: "list" or "board".
update_task Write

Update an existing task in Todoist. Only the fields provided will be changed.

Lua path
app.integrations.todoist.update_task
Full name
todoist.todoist_update_task
ParameterTypeRequiredDescription
id string yes The unique ID of the task to update.
content string no New task content/title.
description string no New task description.
labels array no List of label names to assign.
priority integer no Task priority: 1=normal, 2=medium, 3=high, 4=urgent.
due_date string no Due date in YYYY-MM-DD format.