KosmoKrator

productivity

ServiceM8 Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.service_m8.list_jobs({status = "example_status", limit = 1, offset = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("service-m8"))' --json
kosmo integrations:lua --eval 'print(docs.read("service-m8.list_jobs"))' --json

Workflow file

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

workflow.lua 
local service_m8 = app.integrations.service_m8
local result = service_m8.list_jobs({status = "example_status", 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.service_m8, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.service_m8.default.* or app.integrations.service_m8.work.* when you configured named credential accounts.

MCP-only Lua

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

ServiceM8 Integration

Tools

servicem8_list_jobs

List jobs from ServiceM8.

  • Parameters: status (string, optional), limit (integer, optional), offset (integer, optional)
  • Returns: Array of job objects with UUID, status, client, dates, and description.

servicem8_get_job

Get a specific job by UUID.

  • Parameters: uuid (string, required)
  • Returns: Full job details.

servicem8_list_clients

List clients from ServiceM8.

  • Parameters: limit (integer, optional), offset (integer, optional)
  • Returns: Array of client objects.

servicem8_get_client

Get a specific client by UUID.

  • Parameters: uuid (string, required)
  • Returns: Full client details.

servicem8_create_job

Create a new job in ServiceM8.

  • Parameters: client_id (string, required), template_id (string, optional), description (string, optional)
  • Returns: The created job object.

servicem8_list_activities

List activity records from ServiceM8.

  • Parameters: job_uuid (string, optional), limit (integer, optional), offset (integer, optional)
  • Returns: Array of activity objects.

servicem8_get_current_user

List staff members visible to the authenticated ServiceM8 token.

  • Parameters: (none)
  • Returns: Array of staff member objects. ServiceM8’s public API exposes staff records rather than a dedicated /me endpoint.
Raw agent markdown 
# ServiceM8 Integration

## Tools

### servicem8_list_jobs
List jobs from ServiceM8.
- **Parameters:** `status` (string, optional), `limit` (integer, optional), `offset` (integer, optional)
- **Returns:** Array of job objects with UUID, status, client, dates, and description.

### servicem8_get_job
Get a specific job by UUID.
- **Parameters:** `uuid` (string, required)
- **Returns:** Full job details.

### servicem8_list_clients
List clients from ServiceM8.
- **Parameters:** `limit` (integer, optional), `offset` (integer, optional)
- **Returns:** Array of client objects.

### servicem8_get_client
Get a specific client by UUID.
- **Parameters:** `uuid` (string, required)
- **Returns:** Full client details.

### servicem8_create_job
Create a new job in ServiceM8.
- **Parameters:** `client_id` (string, required), `template_id` (string, optional), `description` (string, optional)
- **Returns:** The created job object.

### servicem8_list_activities
List activity records from ServiceM8.
- **Parameters:** `job_uuid` (string, optional), `limit` (integer, optional), `offset` (integer, optional)
- **Returns:** Array of activity objects.

### servicem8_get_current_user
List staff members visible to the authenticated ServiceM8 token.
- **Parameters:** (none)
- **Returns:** Array of staff member objects. ServiceM8's public API exposes staff records rather than a dedicated `/me` endpoint.
Metadata-derived Lua example 
local result = app.integrations.service_m8.list_jobs({status = "example_status", limit = 1, offset = 1})
print(result)

Functions

list_jobs Read

List jobs from ServiceM8. Returns job details including status, client, dates, and descriptions. Supports filtering by status and pagination.

Lua path
app.integrations.service_m8.list_jobs
Full name
service-m8.servicem8_list_jobs
ParameterTypeRequiredDescription
status string no Filter by job status (e.g. "open", "in_progress", "completed", "cancelled").
limit integer no Maximum number of jobs to return per page.
offset integer no Number of records to skip for pagination.
get_job Read

Get detailed information about a specific ServiceM8 job by its UUID. Returns full job details including status, client, description, dates, and assigned staff.

Lua path
app.integrations.service_m8.get_job
Full name
service-m8.servicem8_get_job
ParameterTypeRequiredDescription
uuid string yes The UUID of the job to retrieve.
list_clients Read

List clients from ServiceM8. Returns client details including name, email, phone, and address. Supports pagination.

Lua path
app.integrations.service_m8.list_clients
Full name
service-m8.servicem8_list_clients
ParameterTypeRequiredDescription
limit integer no Maximum number of clients to return per page.
offset integer no Number of records to skip for pagination.
get_client Read

Get detailed information about a specific ServiceM8 client by their UUID. Returns client details including name, email, phone, billing address, and notes.

Lua path
app.integrations.service_m8.get_client
Full name
service-m8.servicem8_get_client
ParameterTypeRequiredDescription
uuid string yes The UUID of the client to retrieve.
create_job Write

Create a new job in ServiceM8. Requires a client UUID. Optionally specify a job template and description to pre-populate the job.

Lua path
app.integrations.service_m8.create_job
Full name
service-m8.servicem8_create_job
ParameterTypeRequiredDescription
client_id string yes The UUID of the client to assign the job to.
template_id string no The UUID of a job template to apply.
description string no A description for the new job.
list_activities Read

List activity records from ServiceM8. Returns a timeline of events such as job status changes, comments, and notes. Supports filtering by job and pagination.

Lua path
app.integrations.service_m8.list_activities
Full name
service-m8.servicem8_list_activities
ParameterTypeRequiredDescription
job_uuid string no Filter activities to a specific job by its UUID.
limit integer no Maximum number of activities to return per page.
offset integer no Number of records to skip for pagination.
get_current_user Read

List staff members visible to the authenticated ServiceM8 token. ServiceM8 does not expose a dedicated /me endpoint in the public API.

Lua path
app.integrations.service_m8.get_current_user
Full name
service-m8.servicem8_get_current_user
ParameterTypeRequiredDescription
No parameters.