KosmoKrator

productivity

Motion Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.motion.list_tasks({status = "example_status", projectId = "example_projectId", assigneeId = "example_assigneeId", limit = 1, cursor = "example_cursor"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("motion"))' --json
kosmo integrations:lua --eval 'print(docs.read("motion.list_tasks"))' --json

Workflow file

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

workflow.lua 
local motion = app.integrations.motion
local result = motion.list_tasks({status = "example_status", projectId = "example_projectId", assigneeId = "example_assigneeId", limit = 1, cursor = "example_cursor"})

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

MCP-only Lua

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

Motion — Lua API Reference

list_tasks

List tasks from Motion with optional filters.

Parameters

NameTypeRequiredDescription
statusstringnoFilter by task status (e.g., “Todo”, “In Progress”, “Done”)
projectIdstringnoFilter tasks by project ID
assigneeIdstringnoFilter tasks by assignee user ID
limitintegernoMax tasks per page (default: 20, max: 100)
cursorstringnoPagination cursor from a previous response

Examples

-- List all tasks
local result = app.integrations.motion.list_tasks({})

-- List todo tasks
local result = app.integrations.motion.list_tasks({ status = "Todo" })

-- List tasks in a project
local result = app.integrations.motion.list_tasks({ projectId = "proj_abc123" })

-- Paginate
local result = app.integrations.motion.list_tasks({ limit = 10, cursor = "next_page_cursor" })

get_task

Get details of a specific task.

Parameters

NameTypeRequiredDescription
taskIdstringyesThe unique task identifier

Example

local task = app.integrations.motion.get_task({ taskId = "task_abc123" })
print(task.name .. " — " .. task.status)

create_task

Create a new task in Motion. Motion auto-schedules based on priority and due date.

Parameters

NameTypeRequiredDescription
namestringyesTask title
projectIdstringnoProject to add the task to
assigneeIdstringnoUser ID to assign the task to
dueDatestringnoDue date in ISO 8601 (e.g., “2025-12-31”)
prioritystringnoPriority: “ASAP”, “HIGH”, “MEDIUM”, “LOW” (default: “MEDIUM”)
descriptionstringnoTask description (supports Markdown)

Examples

-- Simple task
local task = app.integrations.motion.create_task({
  name = "Review Q1 report"
})

-- Full task with all options
local task = app.integrations.motion.create_task({
  name = "Review Q1 report",
  projectId = "proj_abc123",
  assigneeId = "user_xyz789",
  dueDate = "2025-03-28",
  priority = "HIGH",
  description = "Review the Q1 financial report and provide feedback."
})

list_projects

List all projects in Motion.

Parameters

None.

Example

local result = app.integrations.motion.list_projects({})
for _, project in ipairs(result.projects or {}) do
  print(project.id .. ": " .. project.name)
end

get_project

Get details of a specific project.

Parameters

NameTypeRequiredDescription
projectIdstringyesThe unique project identifier

Example

local project = app.integrations.motion.get_project({ projectId = "proj_abc123" })
print(project.name .. " — " .. (project.description or "No description"))

list_schedules

List schedules within a date range.

Parameters

NameTypeRequiredDescription
startDatestringyesStart date in ISO 8601 (e.g., “2025-01-01”)
endDatestringyesEnd date in ISO 8601 (e.g., “2025-01-31”)

Example

local result = app.integrations.motion.list_schedules({
  startDate = "2025-01-01",
  endDate = "2025-01-31"
})
for _, entry in ipairs(result.schedules or {}) do
  print(entry.date .. ": " .. entry.type)
end

get_current_user

Get the profile of the currently authenticated user.

Parameters

None.

Example

local user = app.integrations.motion.get_current_user({})
print("Logged in as: " .. user.name .. " (" .. user.email .. ")")

Multi-Account Usage

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

-- Default account (always works)
app.integrations.motion.list_tasks({})

-- Explicit default (portable across setups)
app.integrations.motion.default.list_tasks({})

-- Named accounts
app.integrations.motion.work.list_tasks({})
app.integrations.motion.personal.list_tasks({})

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

Raw agent markdown 
# Motion — Lua API Reference

## list_tasks

List tasks from Motion with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | no | Filter by task status (e.g., "Todo", "In Progress", "Done") |
| `projectId` | string | no | Filter tasks by project ID |
| `assigneeId` | string | no | Filter tasks by assignee user ID |
| `limit` | integer | no | Max tasks per page (default: 20, max: 100) |
| `cursor` | string | no | Pagination cursor from a previous response |

### Examples

```lua
-- List all tasks
local result = app.integrations.motion.list_tasks({})

-- List todo tasks
local result = app.integrations.motion.list_tasks({ status = "Todo" })

-- List tasks in a project
local result = app.integrations.motion.list_tasks({ projectId = "proj_abc123" })

-- Paginate
local result = app.integrations.motion.list_tasks({ limit = 10, cursor = "next_page_cursor" })
```

---

## get_task

Get details of a specific task.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `taskId` | string | yes | The unique task identifier |

### Example

```lua
local task = app.integrations.motion.get_task({ taskId = "task_abc123" })
print(task.name .. " — " .. task.status)
```

---

## create_task

Create a new task in Motion. Motion auto-schedules based on priority and due date.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | yes | Task title |
| `projectId` | string | no | Project to add the task to |
| `assigneeId` | string | no | User ID to assign the task to |
| `dueDate` | string | no | Due date in ISO 8601 (e.g., "2025-12-31") |
| `priority` | string | no | Priority: "ASAP", "HIGH", "MEDIUM", "LOW" (default: "MEDIUM") |
| `description` | string | no | Task description (supports Markdown) |

### Examples

```lua
-- Simple task
local task = app.integrations.motion.create_task({
  name = "Review Q1 report"
})

-- Full task with all options
local task = app.integrations.motion.create_task({
  name = "Review Q1 report",
  projectId = "proj_abc123",
  assigneeId = "user_xyz789",
  dueDate = "2025-03-28",
  priority = "HIGH",
  description = "Review the Q1 financial report and provide feedback."
})
```

---

## list_projects

List all projects in Motion.

### Parameters

None.

### Example

```lua
local result = app.integrations.motion.list_projects({})
for _, project in ipairs(result.projects or {}) do
  print(project.id .. ": " .. project.name)
end
```

---

## get_project

Get details of a specific project.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | string | yes | The unique project identifier |

### Example

```lua
local project = app.integrations.motion.get_project({ projectId = "proj_abc123" })
print(project.name .. " — " .. (project.description or "No description"))
```

---

## list_schedules

List schedules within a date range.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `startDate` | string | yes | Start date in ISO 8601 (e.g., "2025-01-01") |
| `endDate` | string | yes | End date in ISO 8601 (e.g., "2025-01-31") |

### Example

```lua
local result = app.integrations.motion.list_schedules({
  startDate = "2025-01-01",
  endDate = "2025-01-31"
})
for _, entry in ipairs(result.schedules or {}) do
  print(entry.date .. ": " .. entry.type)
end
```

---

## get_current_user

Get the profile of the currently authenticated user.

### Parameters

None.

### Example

```lua
local user = app.integrations.motion.get_current_user({})
print("Logged in as: " .. user.name .. " (" .. user.email .. ")")
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.motion.list_tasks({})

-- Explicit default (portable across setups)
app.integrations.motion.default.list_tasks({})

-- Named accounts
app.integrations.motion.work.list_tasks({})
app.integrations.motion.personal.list_tasks({})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.motion.list_tasks({status = "example_status", projectId = "example_projectId", assigneeId = "example_assigneeId", limit = 1, cursor = "example_cursor"})
print(result)

Functions

list_tasks Read

List tasks from Motion with optional filters. Filter by status, project, or assignee. Supports cursor-based pagination.

Lua path
app.integrations.motion.list_tasks
Full name
motion.motion_list_tasks
ParameterTypeRequiredDescription
status string no Filter by task status. Common values: "Todo", "In Progress", "Done".
projectId string no Filter tasks by project ID.
assigneeId string no Filter tasks by assignee user ID.
limit integer no Maximum number of tasks to return per page (default: 20, max: 100).
cursor string no Pagination cursor from a previous response to fetch the next page.
get_task Read

Get details of a specific task in Motion by its ID. Returns the task name, description, status, assignee, due date, priority, and project.

Lua path
app.integrations.motion.get_task
Full name
motion.motion_get_task
ParameterTypeRequiredDescription
taskId string yes The unique identifier of the task.
create_task Write

Create a new task in Motion. Requires a task name. Optionally specify a project, assignee, due date, priority, and description. Motion will auto-schedule the task based on priorities and deadlines.

Lua path
app.integrations.motion.create_task
Full name
motion.motion_create_task
ParameterTypeRequiredDescription
name string yes The title/name of the task.
projectId string no The ID of the project to add the task to.
assigneeId string no The user ID of the person to assign the task to.
dueDate string no Due date in ISO 8601 format (e.g., "2025-12-31"). Motion uses this for auto-scheduling.
priority string no Task priority: "ASAP", "HIGH", "MEDIUM", or "LOW". Defaults to "MEDIUM".
description string no Detailed description of the task. Supports Markdown.
list_projects Read

List all projects in Motion. Returns project IDs, names, and other metadata. Use project IDs to filter tasks or create tasks in specific projects.

Lua path
app.integrations.motion.list_projects
Full name
motion.motion_list_projects
ParameterTypeRequiredDescription
No parameters.
get_project Read

Get details of a specific project in Motion by its ID. Returns the project name, description, status, and other metadata.

Lua path
app.integrations.motion.get_project
Full name
motion.motion_get_project
ParameterTypeRequiredDescription
projectId string yes The unique identifier of the project.
list_schedules Read

List schedules from Motion within a date range. Returns scheduled tasks and events for the authenticated user.

Lua path
app.integrations.motion.list_schedules
Full name
motion.motion_list_schedules
ParameterTypeRequiredDescription
startDate string yes Start date in ISO 8601 format (e.g., "2025-01-01").
endDate string yes End date in ISO 8601 format (e.g., "2025-01-31").
get_current_user Read

Get the profile of the currently authenticated Motion user. Returns user ID, name, email, and other account details.

Lua path
app.integrations.motion.get_current_user
Full name
motion.motion_get_current_user
ParameterTypeRequiredDescription
No parameters.