KosmoKrator

data

Samsara Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.samsara.list_vehicles({limit = 1, after = "example_after"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("samsara"))' --json
kosmo integrations:lua --eval 'print(docs.read("samsara.list_vehicles"))' --json

Workflow file

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

workflow.lua 
local samsara = app.integrations.samsara
local result = samsara.list_vehicles({limit = 1, after = "example_after"})

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

MCP-only Lua

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

Samsara

Namespace: samsara

Samsara exposes fleet telematics, driver workflow, routing, address book, tag, document, maintenance, sensor, and user APIs. This package uses bearer-token authentication against the current REST API base URL https://api.samsara.com and keeps responses in Samsara’s original JSON shape.

Coverage

Core tools:

  • Vehicles and drivers: list/get vehicles, list/get drivers, vehicle stats snapshot/history/feed
  • Trailers and equipment: list/get/create/update/delete where supported, stats snapshot/history/feed
  • Routes: list/get/create/update/delete route plans
  • Addresses and tags: list/get/create/update/delete address book entries and tags
  • Documents: list/get/create documents and list/get document types
  • Maintenance: defects, defect history, defect types
  • Sensors and users: list sensors, current user, list/get users
  • Raw helpers: samsara_api_get, samsara_api_post, samsara_api_patch, samsara_api_delete

Usage Notes

Samsara tokens are permissioned by endpoint category and by account license. A 401 usually means the token is missing or invalid. A 403 usually means the token exists but lacks the required endpoint permission or Samsara license.

Most list endpoints use cursor pagination with after, limit, and a pagination.endCursor value in the response. Many stats endpoints require types; pass either a comma-separated string or an array of strings. The integration preserves repeated query parameters when arrays are provided.

Examples

local vehicles = app.integrations.samsara.samsara_list_vehicles({
  limit = 100
})

local stats = app.integrations.samsara.samsara_get_vehicle_stats({
  types = { "gps", "obdOdometerMeters" },
  vehicleIds = { "vehicle-id" }
})

local route = app.integrations.samsara.samsara_create_route({
  payload = {
    name = "Morning deliveries",
    driverId = "driver-id",
    stops = {}
  }
})

local documents = app.integrations.samsara.samsara_list_documents({
  startTime = "2026-01-01T00:00:00Z",
  endTime = "2026-01-31T23:59:59Z"
})

Use raw helpers for newly released Samsara endpoints while staying scoped to the configured API host:

local users = app.integrations.samsara.samsara_api_get({
  path = "/users",
  limit = 50
})

For feeds such as vehicle, trailer, or equipment stats, keep the pagination.endCursor and pass it as after on the next request. If hasNextPage is false, wait before polling again.

Raw agent markdown 
# Samsara

Namespace: `samsara`

Samsara exposes fleet telematics, driver workflow, routing, address book, tag, document, maintenance, sensor, and user APIs. This package uses bearer-token authentication against the current REST API base URL `https://api.samsara.com` and keeps responses in Samsara's original JSON shape.

## Coverage

Core tools:

- Vehicles and drivers: list/get vehicles, list/get drivers, vehicle stats snapshot/history/feed
- Trailers and equipment: list/get/create/update/delete where supported, stats snapshot/history/feed
- Routes: list/get/create/update/delete route plans
- Addresses and tags: list/get/create/update/delete address book entries and tags
- Documents: list/get/create documents and list/get document types
- Maintenance: defects, defect history, defect types
- Sensors and users: list sensors, current user, list/get users
- Raw helpers: `samsara_api_get`, `samsara_api_post`, `samsara_api_patch`, `samsara_api_delete`

## Usage Notes

Samsara tokens are permissioned by endpoint category and by account license. A 401 usually means the token is missing or invalid. A 403 usually means the token exists but lacks the required endpoint permission or Samsara license.

Most list endpoints use cursor pagination with `after`, `limit`, and a `pagination.endCursor` value in the response. Many stats endpoints require `types`; pass either a comma-separated string or an array of strings. The integration preserves repeated query parameters when arrays are provided.

## Examples

```lua
local vehicles = app.integrations.samsara.samsara_list_vehicles({
  limit = 100
})

local stats = app.integrations.samsara.samsara_get_vehicle_stats({
  types = { "gps", "obdOdometerMeters" },
  vehicleIds = { "vehicle-id" }
})

local route = app.integrations.samsara.samsara_create_route({
  payload = {
    name = "Morning deliveries",
    driverId = "driver-id",
    stops = {}
  }
})

local documents = app.integrations.samsara.samsara_list_documents({
  startTime = "2026-01-01T00:00:00Z",
  endTime = "2026-01-31T23:59:59Z"
})
```

Use raw helpers for newly released Samsara endpoints while staying scoped to the configured API host:

```lua
local users = app.integrations.samsara.samsara_api_get({
  path = "/users",
  limit = 50
})
```

For feeds such as vehicle, trailer, or equipment stats, keep the `pagination.endCursor` and pass it as `after` on the next request. If `hasNextPage` is false, wait before polling again.
Metadata-derived Lua example 
local result = app.integrations.samsara.list_vehicles({limit = 1, after = "example_after"})
print(result)

Functions

list_vehicles Read

List fleet vehicles from Samsara. Returns vehicle details including name, VIN, make, model, year, and GPS location. Supports pagination.

Lua path
app.integrations.samsara.list_vehicles
Full name
samsara.samsara_list_vehicles
ParameterTypeRequiredDescription
limit integer no Maximum number of vehicles to return per page (default: 100, max: 512).
after string no Pagination cursor - pass the "pagination.endCursor" value from a previous response to fetch the next page.
get_vehicle Read

Get detailed information about a specific vehicle by its Samsara ID, including name, VIN, make, model, year, GPS location, and odometer reading.

Lua path
app.integrations.samsara.get_vehicle
Full name
samsara.samsara_get_vehicle
ParameterTypeRequiredDescription
id string yes The Samsara vehicle ID (e.g., "123456789012345").
list_drivers Read

List fleet drivers from Samsara. Returns driver details including name, username, email, phone, and driver license info. Supports pagination.

Lua path
app.integrations.samsara.list_drivers
Full name
samsara.samsara_list_drivers
ParameterTypeRequiredDescription
limit integer no Maximum number of drivers to return per page (default: 100, max: 512).
after string no Pagination cursor - pass the "pagination.endCursor" value from a previous response to fetch the next page.
get_driver Read

Get detailed information about a specific driver by their Samsara ID, including name, username, email, phone, and driver license details.

Lua path
app.integrations.samsara.get_driver
Full name
samsara.samsara_get_driver
ParameterTypeRequiredDescription
id string yes The Samsara driver ID (e.g., "123456789012345").
list_sensors Read

List IoT sensors from Samsara. Returns sensor details including name, type, model, connectivity, and current readings. Supports pagination.

Lua path
app.integrations.samsara.list_sensors
Full name
samsara.samsara_list_sensors
ParameterTypeRequiredDescription
limit integer no Maximum number of sensors to return per page (default: 100, max: 512).
after string no Pagination cursor - pass the "pagination.endCursor" value from a previous response to fetch the next page.
get_current_user Read

Get the currently authenticated Samsara user profile, including name, email, role, and organization details.

Lua path
app.integrations.samsara.get_current_user
Full name
samsara.samsara_get_current_user
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative Samsara API path with GET.

Lua path
app.integrations.samsara.api_get
Full name
samsara.samsara_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call a safe relative Samsara API path with POST.

Lua path
app.integrations.samsara.api_post
Full name
samsara.samsara_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Call a safe relative Samsara API path with PATCH.

Lua path
app.integrations.samsara.api_patch
Full name
samsara.samsara_api_patch
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call a safe relative Samsara API path with DELETE.

Lua path
app.integrations.samsara.api_delete
Full name
samsara.samsara_api_delete
ParameterTypeRequiredDescription
No parameters.
get_vehicle_stats Read

Get latest vehicle stats.

Lua path
app.integrations.samsara.get_vehicle_stats
Full name
samsara.samsara_get_vehicle_stats
ParameterTypeRequiredDescription
No parameters.
get_vehicle_stats_history Read

Get historical vehicle stats.

Lua path
app.integrations.samsara.get_vehicle_stats_history
Full name
samsara.samsara_get_vehicle_stats_history
ParameterTypeRequiredDescription
No parameters.
get_vehicle_stats_feed Read

Follow a vehicle stats feed.

Lua path
app.integrations.samsara.get_vehicle_stats_feed
Full name
samsara.samsara_get_vehicle_stats_feed
ParameterTypeRequiredDescription
No parameters.
list_trailers Read

List trailers.

Lua path
app.integrations.samsara.list_trailers
Full name
samsara.samsara_list_trailers
ParameterTypeRequiredDescription
No parameters.
get_trailer Read

Retrieve a trailer.

Lua path
app.integrations.samsara.get_trailer
Full name
samsara.samsara_get_trailer
ParameterTypeRequiredDescription
No parameters.
create_trailer Write

Create a trailer.

Lua path
app.integrations.samsara.create_trailer
Full name
samsara.samsara_create_trailer
ParameterTypeRequiredDescription
No parameters.
update_trailer Write

Update a trailer.

Lua path
app.integrations.samsara.update_trailer
Full name
samsara.samsara_update_trailer
ParameterTypeRequiredDescription
No parameters.
delete_trailer Write

Delete a trailer.

Lua path
app.integrations.samsara.delete_trailer
Full name
samsara.samsara_delete_trailer
ParameterTypeRequiredDescription
No parameters.
get_trailer_stats Read

Get latest trailer stats.

Lua path
app.integrations.samsara.get_trailer_stats
Full name
samsara.samsara_get_trailer_stats
ParameterTypeRequiredDescription
No parameters.
get_trailer_stats_history Read

Get historical trailer stats.

Lua path
app.integrations.samsara.get_trailer_stats_history
Full name
samsara.samsara_get_trailer_stats_history
ParameterTypeRequiredDescription
No parameters.
get_trailer_stats_feed Read

Follow a trailer stats feed.

Lua path
app.integrations.samsara.get_trailer_stats_feed
Full name
samsara.samsara_get_trailer_stats_feed
ParameterTypeRequiredDescription
No parameters.
list_equipment Read

List equipment.

Lua path
app.integrations.samsara.list_equipment
Full name
samsara.samsara_list_equipment
ParameterTypeRequiredDescription
No parameters.
get_equipment Read

Retrieve equipment.

Lua path
app.integrations.samsara.get_equipment
Full name
samsara.samsara_get_equipment
ParameterTypeRequiredDescription
No parameters.
get_equipment_stats Read

Get latest equipment stats.

Lua path
app.integrations.samsara.get_equipment_stats
Full name
samsara.samsara_get_equipment_stats
ParameterTypeRequiredDescription
No parameters.
get_equipment_stats_history Read

Get historical equipment stats.

Lua path
app.integrations.samsara.get_equipment_stats_history
Full name
samsara.samsara_get_equipment_stats_history
ParameterTypeRequiredDescription
No parameters.
get_equipment_stats_feed Read

Follow an equipment stats feed.

Lua path
app.integrations.samsara.get_equipment_stats_feed
Full name
samsara.samsara_get_equipment_stats_feed
ParameterTypeRequiredDescription
No parameters.
list_routes Read

List routes.

Lua path
app.integrations.samsara.list_routes
Full name
samsara.samsara_list_routes
ParameterTypeRequiredDescription
No parameters.
get_route Read

Retrieve a route.

Lua path
app.integrations.samsara.get_route
Full name
samsara.samsara_get_route
ParameterTypeRequiredDescription
No parameters.
create_route Write

Create a route.

Lua path
app.integrations.samsara.create_route
Full name
samsara.samsara_create_route
ParameterTypeRequiredDescription
No parameters.
update_route Write

Update a route.

Lua path
app.integrations.samsara.update_route
Full name
samsara.samsara_update_route
ParameterTypeRequiredDescription
No parameters.
delete_route Write

Delete a route.

Lua path
app.integrations.samsara.delete_route
Full name
samsara.samsara_delete_route
ParameterTypeRequiredDescription
No parameters.
list_addresses Read

List addresses.

Lua path
app.integrations.samsara.list_addresses
Full name
samsara.samsara_list_addresses
ParameterTypeRequiredDescription
No parameters.
get_address Read

Retrieve an address.

Lua path
app.integrations.samsara.get_address
Full name
samsara.samsara_get_address
ParameterTypeRequiredDescription
No parameters.
create_address Write

Create an address.

Lua path
app.integrations.samsara.create_address
Full name
samsara.samsara_create_address
ParameterTypeRequiredDescription
No parameters.
update_address Write

Update an address.

Lua path
app.integrations.samsara.update_address
Full name
samsara.samsara_update_address
ParameterTypeRequiredDescription
No parameters.
delete_address Write

Delete an address.

Lua path
app.integrations.samsara.delete_address
Full name
samsara.samsara_delete_address
ParameterTypeRequiredDescription
No parameters.
list_tags Read

List tags.

Lua path
app.integrations.samsara.list_tags
Full name
samsara.samsara_list_tags
ParameterTypeRequiredDescription
No parameters.
get_tag Read

Retrieve a tag.

Lua path
app.integrations.samsara.get_tag
Full name
samsara.samsara_get_tag
ParameterTypeRequiredDescription
No parameters.
create_tag Write

Create a tag.

Lua path
app.integrations.samsara.create_tag
Full name
samsara.samsara_create_tag
ParameterTypeRequiredDescription
No parameters.
update_tag Write

Update a tag.

Lua path
app.integrations.samsara.update_tag
Full name
samsara.samsara_update_tag
ParameterTypeRequiredDescription
No parameters.
delete_tag Write

Delete a tag.

Lua path
app.integrations.samsara.delete_tag
Full name
samsara.samsara_delete_tag
ParameterTypeRequiredDescription
No parameters.
list_users Read

List users.

Lua path
app.integrations.samsara.list_users
Full name
samsara.samsara_list_users
ParameterTypeRequiredDescription
No parameters.
get_user Read

Retrieve a user.

Lua path
app.integrations.samsara.get_user
Full name
samsara.samsara_get_user
ParameterTypeRequiredDescription
No parameters.
list_defects Read

List DVIR defects.

Lua path
app.integrations.samsara.list_defects
Full name
samsara.samsara_list_defects
ParameterTypeRequiredDescription
No parameters.
get_defects_history Read

Get historical DVIR defects.

Lua path
app.integrations.samsara.get_defects_history
Full name
samsara.samsara_get_defects_history
ParameterTypeRequiredDescription
No parameters.
list_defect_types Read

List defect types.

Lua path
app.integrations.samsara.list_defect_types
Full name
samsara.samsara_list_defect_types
ParameterTypeRequiredDescription
No parameters.
list_documents Read

List documents.

Lua path
app.integrations.samsara.list_documents
Full name
samsara.samsara_list_documents
ParameterTypeRequiredDescription
No parameters.
get_document Read

Retrieve a document.

Lua path
app.integrations.samsara.get_document
Full name
samsara.samsara_get_document
ParameterTypeRequiredDescription
No parameters.
create_document Write

Create a document.

Lua path
app.integrations.samsara.create_document
Full name
samsara.samsara_create_document
ParameterTypeRequiredDescription
No parameters.
list_document_types Read

List document types.

Lua path
app.integrations.samsara.list_document_types
Full name
samsara.samsara_list_document_types
ParameterTypeRequiredDescription
No parameters.
get_document_type Read

Retrieve a document type.

Lua path
app.integrations.samsara.get_document_type
Full name
samsara.samsara_get_document_type
ParameterTypeRequiredDescription
No parameters.